Java Wrapper for Loop54 JSON V3 API

How to install

Either download any of these jars and import them into you project:

Or download the source and reference the core and spring modules and build it using gradle.

Requires Java 1.8 or later. If running Java 1.7 or under please use an older version of the library available in the GitHub history.

Javadoc for the latest release is available here

How to use

The Loop54 Connector is easily configured if running Spring.


Simply add the following code to the Spring configuration class marked with @Configuration:

public ILoop54Client loop54Client() {
    Loop54Settings settings = new Loop54Settings("");
    return new Loop54Client(
        new RequestManager(settings),
        new SpringRemoteClientInfoProvider()); //Will use Spring classes to extract user data

An ILoop54Client is then injectable by using the @Autowire annotation

Multiple instances

If you are using multiple instances of the Loop54 engine within you application you instead need to do the following:

public ILoop54ClientProvider loop54ClientProvider() {
    return new Loop54ClientProvider(
            new SpringRemoteClientInfoProvider(),
                    .add("english", "")
                    .add("swedish", ""));

And then inject the ILoop54ClientProvider interface into your application with the @Autowire annotation. And obtain a specific instance using the getNamed method with the same name as above:

ILoop54Client loop54Client = clientProvider.getNamed("swedish");

Using the ILoop54Client

The ILoop54Client contains methods for making all public API calls to the Loop54 e-commerce search engine. It contains both synchronous and asynchronous variants of all methods.

String searchQuery = "banana";
SearchRequest request = new SearchRequest(searchQuery);
SearchResponse response =;

To add parameters to the SearchRequest you could do this:

request.resultsOptions.skip = 0;
request.resultsOptions.take = 20;

All other request types also have their own types to use:

CreateEventsRequest createEventRequest = new CreateEventsRequest(event);

AutoCompleteRequest autoCompleteRequest = new AutoCompleteRequest(query);

GetRelatedEntitiesRequest getRelatedEntitiesRequest 
    = new GetRelatedEntitiesRequest(entityType, entityId);
GetEntitiesRequest getEntitiesRequest = new GetEntitiesRequest();

GetEntitiesByAttributeRequest getEntitiesByAttributeRequest 
    = new GetEntitiesByAttributeRequest(attributeName, attributeValue);

But wait! I'm not using Spring

There is still hope for you. If not using the above mentioned frameworks you can implement some of the functionality yourself and use the client just as well. You will need to implement the IRemoteClientInfoProvider interface and the IRemoteClientInfo interface and after doing that you can create a new instance of ILoop54Client like this:

IRemoteClientInfoProvider myRemoteClientInfoProvider = new MySuperAwesomeCustomRemoteClientInfoProvider();
Loop54Settings settings = new Loop54Settings("");
ILoop54Client loop54Client = new Loop54Client(new RequestManager(settings), myRemoteClientInfoProvider);

And you are good to go!


  • Native support for search, autoComplete, createEvent, getEntities, getEntitiesByAttribute and getRelatedEntities call. With intuitive APIs to call them.
  • Handles user identification using random-generated cookies.
  • Uses X-Forwarded-For as client IP if it's available.
  • Configurable HTTP timeout.
  • GZIP support.
  • Relays HTTP data to engine:
    • Referer
    • UserAgent
    • Library version

Building and testing

To build the library simply use the supplied gradle wrapper by going to the root directory of the repository in the command line and issue the following command:

gradlew build

This will download gradle 4.6 and all dependencies, build all modules and run the unit tests.

To generate the javadoc, run:

gradlew javadoc

Run the test application in the web module by using the following command:

gradlew :web:appRun

And the application will start and be hosted on http://localhost:8080/web.

Building, generating javadoc and running the test app requires JDK 1.8.