API Reference / API Methods / The Java API client

The Java API client

Algolia’s Java API client lets you use Algolia’s APIs from your Java application. Compared to using the APIs directly, using the Java API client has these benefits:

  • Network retry strategy. The API client automatically retries connecting to another Algolia server, if the connection fails. Thanks to that, using the API clients is covered by Algolia’s SLA.

  • Reindexing. The API clients let you reindex your records in a single operation.

  • Automatic batching. When you add records to your index, the API client automatically batches your records to make fewer API requests.

Algolia’s Java API client is open source. You can find the source code on GitHub.

Get the source on GitHub

We released a new version of the Java API client in public beta. Read the beta documentation for more information.

Quickstart sample app

To download and run a self-contained example, see the Java quickstart on GitHub.

See quickstart samples on GitHub

Install the Java API client

The Algolia Java API client requires Java 1.8 or higher for all modules except algoliasearch-java-net. The algoliasearch-java-net module requires Java 11 or higher.

Install via Maven

With Maven, add one of the following dependencies to your pom.xml file.

For Java 8 and higher, use the Algolia Java API client with the Apache HTTP client:

Copy 
1
2
3
4
5
6
7
8
9
10

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

For Java 11 and higher, you can use the native HTTP client with Algolia:

Copy 
1
2
3
4
5
6
7
8
9
10

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

You can also include the API client and its dependencies as a single uber-JAR (Java 8 and higher):

Copy 
1
2
3
4
5

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

Install via Gradle

If you already have a Gradle project, add the API client as dependencies to your build.gradle file:

For Java 8 and higher, use the Algolia Java API client with the Apache HTTP client:

Copy 
1
2
3
4
5

dependencies {
  // ...
  implementation 'com.algolia:algoliasearch-core:3.16.5'
  implementation 'com.algolia:algoliasearch-apache:3.16.5'
}

For Java 11 and higher, you can use the native HTTP client with Algolia:

Copy 
1
2
3
4
5

dependencies {
  // ...
  implementation 'com.algolia:algoliasearch-core:3.16.5'
  implementation 'com.algolia:algoliasearch-java-net:3.16.5'
}

You can initialize a new project with:

Copy 
1

gradle init

Install manually

If you don’t use Maven or Gradle, you can download all JAR files from Maven Central’s Sonatype servers:

Install for Adobe Experience Manager and other OSGi platforms

OSGi platforms like Adobe Experience Manager require a single uber JAR as a dependency. If you want to integrate Algolia into such a platform, add algoliasearch-apache-uber as a dependency.

Test your installation

If you haven’t already, create an Algolia account and create a new Algolia app to get started.

To test whether you can connect to Algolia, run a simple program that adds a record to a new index, searches the index, and print the results.

  1. In your Java project, create a new class Record.java:

    Copy 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

    // Record.java
import java.io.Serializable;

public class Record implements Serializable {
   private String name;
   private String objectID;

   public Record() {}

   public Record(String name, String objectID) {
      this.name = name;
      this.objectID = objectID;
   }

   @Override
   public String toString() {
      return String.format("Name: %s, objectID: %s", this.name, this.objectID);
   }
   public String getName() { return name; }
   public void setName(String name) { this.name = name; }
   public String getObjectID() { return objectID; }
   public void setObjectID(String objectID) { this.objectID = objectID; }
}

    This class defines how a single record looks like in your index.

  2. Create a new class Program.java with the following code. If you’re signed in, the code samples below show your Algolia application ID. If you’re not signed in, replace YourApplicationID with your Algolia application ID and YourWriteAPIKey with your Write API Key. You can find both in your Algolia account.

    Copy 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

    // Program.java
import com.algolia.search.DefaultSearchClient;
import com.algolia.search.SearchClient;
import com.algolia.search.SearchIndex;
import com.algolia.search.models.indexing.Query;
import com.algolia.search.models.indexing.SearchResult;

public class Program {
   public static void main(String[] args) {
      // Connect and authenticate with your Algolia app
      SearchClient client = DefaultSearchClient.create("YourApplicationID", "YourWriteAPIKey");

      // Create a new index and add a record (using the `Record` class)
      SearchIndex<Record> index = client.initIndex("test_index", Record.class);
      Record record = new Record("test_record", "1");
      index.saveObject(record).waitTask();

      // Search the index and print the results
      SearchResult<Record> results = index.search(new Query("test_record"));
      System.out.println(results.getHits().get(0));
   }
}

  3. Build and run the project.

  4. If the program ran successfully, you should see:

    Copy 
    1

    Name: test_record, objectID: 1

You can inspect your index now in the Algolia dashboard.

Next steps

Now you can interact with the Algolia Search API, you can look at the available methods, for example, for search or indexing.

Other APIs, for example for Algolia Recommend or Analytics, come with their own clients. To get an overview, see Initialize the API client.

Did you find this page helpful?
Java v3