Algolia Search API Client for Java

Algolia Search is a hosted search engine capable of delivering realtime results from the first keystroke.

The Algolia Search API Client for Java lets you easily use the Algolia Search REST API from your Java code.

Contributing

WARNING: The JVM has an infinite cache on successful DNS resolution. As our hostnames points to multiple IPs, the load could be not evenly spread among our machines, and you might also target a dead machine.

You should change this TTL by setting the property networkaddress.cache.ttl. For example to set the cache to 60 seconds:

java.security.Security.setProperty("networkaddress.cache.ttl", "60");

For debug purposes you can enable debug logging on the API client. It's using slf4j so it should be compatible with most java logger. The logger is named algoliasearch.

API Documentation

You can find the full reference on Algolia's website.

1. Supported platforms

2. Install

3. Quick Start

4. Push data

5. Configure

6. Search

7. Search UI

8. List of available methods

9. Getting Help

10. List of available methods

Getting Started

Supported platforms

The API client only supports Java 1.8 & Java 1.9. If you need support for an older version, please use this package.

Install

With Maven, add the following dependency to your pom.xml file:

<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch</artifactId>
  <version>2.22</version>
</dependency>

Then, for the asynchronous version, use:

<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-async</artifactId>
  <version>2.22</version>
</dependency>

Or on Google AppEngine, use:

<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch-appengine</artifactId>
  <version>2.22</version>
</dependency>

Builder

The v2 of the API client uses a builder to create the APIClient object:

• On Google App Engine use the AppEngineAPIClientBuilder
  • If you fancy Future, use the AsyncHttpAPIClientBuilder
• On Android, use the Android API Client
• On a regular JVM, use the ApacheAPIClientBuilder

POJO, JSON & Jackson2

The Index (and AsyncIndex) classes are parametrized with a Java class. If you specify one, it lets you have type safe method results. This parametrized Java class should follow the POJO convention:

• A constructor without parameters
• Getters & setters for every field you want to (de)serialize

Example:

public class Contact {

  private String name;
  private int age;

  public Contact() {}

  public String getName() {
    return name;
  }

  public Contact setName(String name) {
    this.name = name;
    return this;
  }

  public int getAge() {
    return age;
  }

  public Contact setAge(int age) {
    this.age = age;
    return this;
  }
}

All the serialization/deserialization is done with Jackson2. You can add your custom ObjectMapper with the method setObjectMapper of the builder. Changing it might produce unexpected results. You can find the one used in the interface com.algolia.search.Defaults.DEFAULT_OBJECT_MAPPER.

Async & Future

All methods of the AsyncAPIClient are exactly the same as the APIClient but return CompletableFuture<?>. All other classes are prefixed with Async. You can also pass an optional ExecutorService to the build of the AsyncHttpAPIClientBuilder.

Quick Start

In 30 seconds, this quick start tutorial will show you how to index and search objects.

Initialize the client

To start, you need to initialize the client. To do this, you need your Application ID and API Key. You can find both on your Algolia account.

APIClient client =
  new ApacheAPIClientBuilder("YourApplicationID", "YourAdminAPIKey").build();

Index<Contact> index = client.initIndex("your_index_name", Contact.class);

For the asynchronous version:

AsyncAPIClient client =
  new AsyncHttpAPIClientBuilder("YourApplicationID", "YourAdminAPIKey").build();

AsyncIndex<Contact> index = client.initIndex("your_index_name", Contact.class);

For Google AppEngine:

APIClient client =
  new AppEngineAPIClientBuilder("YourApplicationID", "YourAdminAPIKey").build();

Index<Contact> index = client.initIndex("your_index_name", Contact.class);

Push data

Without any prior configuration, you can start indexing contacts in the contacts index using the following code:

class Contact {

  private String firstname;
  private String lastname;
  private int followers;
  private String company;

  // Getters/setters ommitted
}

Index<Contact> index = client.initIndex("contacts", Contact.class);
index.addObject(new Contact()
     .setFirstname("Jimmie")
     .setLastname("Barninger")
     .setFollowers(93)
     .setCompany("California Paint"));
index.addObject(new JSONObject()
     .setFirstname("Warren")
     .setLastname("Speach")
     .setFollowers(42)
     .setCompany("Norwalk Crmc"));

If you prefer the async version:

AsyncIndex<Contact> index = client.initIndex("contacts", Contact.class);
index.addObject(new Contact()
     .setFirstname("Jimmie")
     .setLastname("Barninger")
     .setFollowers(93)
     .setCompany("California Paint"));
index.addObject(new JSONObject()
     .setFirstname("Warren")
     .setLastname("Speach")
     .setFollowers(42)
     .setCompany("Norwalk Crmc"));

Configure

You can customize settings to fine tune the search behavior. For example, you can add a custom ranking by number of followers to further enhance the built-in relevance:

// Sync & Async version

index.setSettings(new IndexSettings().setCustomRanking(Collections.singletonList("desc(followers)")));

You can also configure the list of attributes you want to index by order of importance (most important first).

Note: Algolia is designed to suggest results as you type, which means you'll generally search by prefix. In this case, the order of attributes is crucial to decide which hit is the best.

// Sync & Async version

index.setSettings(new IndexSettings().setSearchableAttributes(
  Arrays.asList("lastname", "firstname", "company")
);

Search

You can now search for contacts by firstname, lastname, company, etc. (even with typos):

//Sync version

// Search for a first name
System.out.println(index.search(new Query("jimmie")));
// Search for a first name with typo
System.out.println(index.search(new Query("jimie")));
// Search for a company
System.out.println(index.search(new Query("california paint")));
// Search for a first name and a company
System.out.println(index.search(new Query("jimmie paint")));

//Async version

// Search for a first name
System.out.println(index.search(new Query("jimmie")).get());
// Search for a first name with typo
System.out.println(index.search(new Query("jimie")).get());
// Search for a company
System.out.println(index.search(new Query("california paint")).get());
// Search for a first name and a company
System.out.println(index.search(new Query("jimmie paint")).get());

Search UI

Warning: If you're building a web application, you may be interested in using one of our front-end search UI libraries.

The following example shows how to quickly build a front-end search using InstantSearch.js

index.html

<!doctype html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/instantsearch.css@7.1.1/themes/algolia.css" integrity="sha256-4SlodglhMbXjGQfNWiCBLSGNiq90FUw3Mtre9u4vLG8=" crossorigin="anonymous">
</head>
<body>
  <header>
    
  </header>

  <main>
      
      
  </main>

  <script type="text/html" id="hit-template">
    
      <p class="hit-name">
        {}{ "attribute": "firstname" }{{/helpers.highlight}}
        {}{ "attribute": "lastname" }{{/helpers.highlight}}
      </p>
    
  </script>

  <script src="https://cdn.jsdelivr.net/npm/algoliasearch@3.32.1/dist/algoliasearchLite.min.js" integrity="sha256-NSTRUP9bvh8kBKi7IHQSmOrMAdVEoSJFBbTA+LoRr3A=" crossorigin="anonymous"></script>
  <script src="https://cdn.jsdelivr.net/npm/instantsearch.js@3.2.0" integrity="sha256-/8usMtTwZ01jujD7KAZctG0UMk2S2NDNirGFVBbBZCM=" crossorigin="anonymous"></script>
  <script src="app.js"></script>
</body>

app.js

// Replace with your own values
const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey' // search only API key, not admin API key
);

const search = instantsearch({
  indexName: 'instant_search',
  searchClient,
  routing: true,
});

search.addWidget(
  instantsearch.widgets.configure({
    hitsPerPage: 10,
  })
);

search.addWidget(
  instantsearch.widgets.searchBox({
    container: '#search-box',
    placeholder: 'Search for products',
  })
);

search.addWidget(
  instantsearch.widgets.hits({
    container: '#hits',
    templates: {
      item: document.getElementById('hit-template').innerHTML,
      empty: `We didn't find any results for the search <em>"{{query}}"</em>`,
    },
  })
);

search.start();

List of available methods

Personalization

• Add strategy
• Get strategy

Search

• Search index
• Search for facet values
• Search multiple indices
• Browse index

Indexing

• Add objects
• Save objects
• Partial update objects
• Delete objects
• Replace all objects
• Delete by
• Clear objects
• Get objects
• Custom batch

Settings

• Get settings
• Set settings
• Copy settings

Manage indices

• List indices
• Delete index
• Copy index
• Move index

API keys

• Create secured API Key
• Add API Key
• Update API Key
• Delete API Key
• Restore API Key
• Get API Key permissions
• List API Keys

Synonyms

• Save synonym
• Batch synonyms
• Delete synonym
• Clear all synonyms
• Get synonym
• Search synonyms
• Replace all synonyms
• Copy synonyms
• Export Synonyms

Query rules

• Save rule
• Batch rules
• Get rule
• Delete rule
• Clear rules
• Search rules
• Replace all rules
• Copy rules
• Export rules

A/B Test

• Add A/B test
• Get A/B test
• List A/B tests
• Stop A/B test
• Delete A/B test

Insights

• Clicked Object IDs After Search
• Clicked Object IDs
• Clicked Filters
• Converted Objects IDs After Search
• Converted Object IDs
• Converted Filters
• Viewed Object IDs
• Viewed Filters

MultiClusters

• Assign or Move userID
• Get top userID
• Get userID
• List clusters
• List userIDs
• Remove userID
• Search userID

Advanced

• Get logs
• Configuring timeouts
• Set extra header
• Wait for operations

Vault

Getting Help

• Need help? Ask a question to the Algolia Community or on Stack Overflow.
• Found a bug? You can open a GitHub issue.