The perfect starting point to integrate Algolia within your Java project

Documentation • Community Forum • Stack Overflow • Report a bug • FAQ • Support

✨ Features

• Support Java 8 and above
• Asynchronous and synchronous methods to interact with Algolia's API
• Thread-safe clients
• Typed requests and responses
• Injectable HTTP client

Migration note from v2.x to v3.x

In June 2019, we released v3 of our Java client. If you are using version 2.x of the client, read the migration guide to version 3.x. Version 2.x will no longer be under active development.

💡 Getting Started

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");

Install

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

<dependency>
      <groupId>com.algolia</groupId>
      <artifactId>algoliasearch-core</artifactId>
      <version>LATEST</version>
</dependency>

Concerning the HTTP layer, the library can be used with one of the modules below depending on your needs.

The Apache HTTP Client for users supporting Java 8:

<dependency>
     <groupId>com.algolia</groupId>
     <artifactId>algoliasearch-apache</artifactId>
     <version>LATEST</version>
</dependency>

The Java native HTTP Client for users supporting Java 11 or above:

<dependency>
     <groupId>com.algolia</groupId>
     <artifactId>algoliasearch-java-net</artifactId>
     <version>LATEST</version>
</dependency>

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.

SearchClient client = DefaultSearchClient.create("YourApplicationID", "YourAdminAPIKey");
SearchIndex index = client.initIndex("your_index_name");

If you need to customize the configuration of the Apache HTTP client used internally by the Algolia API client, you can provide your own HttpAsyncClientBuilder when instantiating the Algolia SearchClient instance.

SearchConfig config = new SearchConfig.Builder("YourApplicationID", "YourAdminAPIKey").build();
HttpAsyncClientBuilder builder = HttpAsyncClientBuilder.create();

builder.setMaxConnPerRoute(1);
builder.setMaxConnTotal(1);

SearchClient client = new SearchClient(config, new ApacheHttpRequester(config, builder));
SearchIndex index = client.initIndex("your_index_name");

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;
  private String objectID;
  // Getters/setters ommitted
}

SearchIndex<Contact> index = client.initIndex("contacts", Contact.class);

index.saveObject(new Contact()
   .setObjectID("one")
   .setFirstname("Jimmie")
   .setLastname("Barninger")
   .setFollowers(93)
   .setCompany("California Paint"));

Search

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

// Synchronous search
index.search(new Query("jimmie"));

// Asynchronous search
index.searchAsync(new Query("jimmie"));

For full documentation, visit the Algolia Java API Client's documentation.

📝 Examples

You can find code samples in the Algolia's API Clients playground.

❓ Troubleshooting

Encountering an issue? Before reaching out to support, we recommend heading to our FAQ where you will find answers for the most common issues and gotchas with the client.

Use the Dockerfile

If you want to contribute to this project without installing all its dependencies, you can use our Docker image. Please check our dedicated guide to learn more.

📄 License

Algolia Java API Client is an open-sourced software licensed under the MIT license.