Usage

warning

The amount of changes in this new version is significant. If you are upgrading for v4, you should thoroughly test your application before deploying to production.

Installation

To get started, you first need to install algoliasearch (or any other available API client package).

All of our clients comes with type definition, and are available for both browser and node environments.

yarn add algoliasearch@beta
# or
npm install algoliasearch@beta

Or use a specific package:

yarn add @algolia/client-search@beta
# or
npm install @algolia/client-search@beta

Without a package manager

Add the following JavaScript snippet to the <head> of your website:

<script src="https://cdn.jsdelivr.net/npm/algoliasearch@beta/dist/algoliasearch.umd.min.js"></script>

First, install Algolia Python API Client via the pip package manager:

pip install --upgrade 'algoliasearch>=4.0,<5.0'

First, install Algolia PHP API Client via the composer package manager:

composer require algolia/algoliasearch-client-php "^4.0@beta"

To get started, add the algoliasearch-client-java dependency to your project, either with Maven:

<dependency>
  <groupId>com.algolia</groupId>
  <artifactId>algoliasearch</artifactId>
  <version>4.0.0-beta.38</version>
</dependency>

or Gradle:

dependencies {
  implementation 'com.algolia:algoliasearch:4.0.0-beta.38'
}

JVM

Install the Kotlin client by adding the following dependency to your gradle.build file:

repositories {
  mavenCentral()
}

dependencies {
  implementation "com.algolia:algoliasearch-client-kotlin:3.0.0-beta.33"
}

Choose and add to your dependencies one of Ktor’s engines.

BOM

Alternatively, you can use algoliasearch-client-kotlin-bom by adding the following dependency to your build.gradle file

dependencies {
    // import Kotlin API client BOM
    implementation platform("com.algolia:algoliasearch-client-kotlin-bom:3.0.0-beta.33}")

    // define dependencies without versions
    implementation 'com.algolia:algoliasearch-client-kotlin'
    runtimeOnly 'io.ktor:ktor-client-okhttp'
}

Multiplaform

In multiplatform projects, add Algolia API client dependency to commonMain, and choose an engine for each target.

First, install the Algolia API Go Client via the go get command:

go get github.com/algolia/algoliasearch-client-go/v4

To get started, first install the Algolia.Search client.

You can get the last version of the client from NuGet.

If you are using the .NET CLI, you can install the package using the following command:

dotnet add package Algolia.Search --version <The version you want to install>

Or directly in your .csproj file:

<PackageReference Include="Algolia.Search" Version=${versions.csharp} />

Example

You can now import the Algolia API client in your project and play with it.

using Algolia.Search.Clients;
using Algolia.Search.Http;

var client = new SearchClient(new SearchConfig("YOUR_APP_ID", "YOUR_API_KEY"));

// Add a new record to your Algolia index
var response = await client.SaveObjectAsync(
  "<YOUR_INDEX_NAME>",
  new Dictionary<string, string> { { "objectID", "id" }, { "test", "val" } }
);

// Poll the task status to know when it has been indexed
await client.WaitForTaskAsync("<YOUR_INDEX_NAME>", response.TaskID);

// Fetch search results, with typo tolerance
var response = await client.SearchAsync<Object>(
  new SearchMethodParams
  {
    Requests = new List<SearchQuery>
    {
      new SearchQuery(
        new SearchForHits
        {
          IndexName = "<YOUR_INDEX_NAME>",
          Query = "<YOUR_QUERY>",
          HitsPerPage = 50,
        }
      )
    },
  }
);

import 'package:algolia_client_search/algolia_client_search.dart';

final client = SearchClient(appId: 'YOUR_APP_ID', apiKey: 'YOUR_API_KEY');

// Add a new record to your Algolia index
final response = await client.saveObject(
  indexName: "<YOUR_INDEX_NAME>",
  body: {
    'objectID': "id",
    'test': "val",
  },
);

// Poll the task status to know when it has been indexed
await client.waitTask('<YOUR_INDEX_NAME>', response.taskID);

// Fetch search results, with typo tolerance
final response = await client.search(
  searchMethodParams: SearchMethodParams(
    requests: [
      SearchForHits(
        indexName: "<YOUR_INDEX_NAME>",
        query: "<YOUR_QUERY>",
        hitsPerPage: 50,
      ),
    ],
  ),
);

import "github.com/algolia/algoliasearch-client-go/v4/algolia/search"

client, err := search.NewClient("YOUR_APP_ID", "YOUR_API_KEY")

// Add a new record to your Algolia index
response, err := client.SaveObject(client.NewApiSaveObjectRequest(
  "<YOUR_INDEX_NAME>", map[string]any{"objectID": "id", "test": "val"},
))
if err != nil {
  // handle the eventual error
  panic(err)
}

// use the model directly
print(response)

// Poll the task status to know when it has been indexed
taskResponse, err := searchClient.WaitForTask("<YOUR_INDEX_NAME>", response.TaskID, nil, nil, nil)
if err != nil {
  panic(err)
}

// Fetch search results, with typo tolerance
response, err := client.Search(client.NewApiSearchRequest(

  search.NewEmptySearchMethodParams().SetRequests(
    []search.SearchQuery{*search.SearchForHitsAsSearchQuery(
      search.NewEmptySearchForHits().SetIndexName("<YOUR_INDEX_NAME>").SetQuery("<YOUR_QUERY>").SetHitsPerPage(50))}),
))
if err != nil {
  // handle the eventual error
  panic(err)
}

// use the model directly
print(response)

import com.algolia.api.SearchClient;
import com.algolia.model.search.*;

SearchClient client = new SearchClient("YOUR_APP_ID", "YOUR_API_KEY");

// Add a new record to your Algolia index
client.saveObject("<YOUR_INDEX_NAME>", Map.of("objectID", "id", "test", "val"));

// Poll the task status to know when it has been indexed
client.waitForTask("<YOUR_INDEX_NAME>", response.getTaskID());

// Fetch search results, with typo tolerance
client.search(
  new SearchMethodParams()
    .setRequests(List.of(new SearchForHits().setIndexName("<YOUR_INDEX_NAME>").setQuery("<YOUR_QUERY>").setHitsPerPage(50))),
  Hit.class
);

import { searchClient } from '@algolia/client-search';

const client = searchClient('YOUR_APP_ID', 'YOUR_API_KEY');

// Add a new record to your Algolia index
const response = await client.saveObject({
  indexName: '<YOUR_INDEX_NAME>',
  body: { objectID: 'id', test: 'val' },
});

// use typed response
console.log(response);

// Poll the task status to know when it has been indexed
await client.waitForTask({ indexName: '<YOUR_INDEX_NAME>', taskID: response.taskID });

// Fetch search results, with typo tolerance
const response = await client.search({
  requests: [
    {
      indexName: '<YOUR_INDEX_NAME>',
      query: '<YOUR_QUERY>',
      hitsPerPage: 50,
    },
  ],
});

// use typed response
console.log(response);

import com.algolia.client.api.SearchClient

val client = SearchClient(appId = "YOUR_APP_ID", apiKey = "YOUR_API_KEY")

// Add a new record to your Algolia index
var response = client.saveObject(
  indexName = "<YOUR_INDEX_NAME>",
  body = buildJsonObject {
    put(
      "objectID",
      JsonPrimitive("id"),
    )
    put(
      "test",
      JsonPrimitive("val"),
    )
  },
)

// Use the response
println(response)

// Poll the task status to know when it has been indexed
client.waitTask("<YOUR_INDEX_NAME>", response.taskID)

// Fetch search results, with typo tolerance
var response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = listOf(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = "<YOUR_QUERY>",
        hitsPerPage = 50,
      ),
    ),
  ),
)

// Use the response
println(response)

use Algolia\AlgoliaSearch\Api\SearchClient;

$client = SearchClient::create('<YOUR_APP_ID>', '<YOUR_API_KEY>');

// Add a new record to your Algolia index
$response = $client->saveObject(
    '<YOUR_INDEX_NAME>',
    ['objectID' => 'id',
        'test' => 'val',
    ],
);

// play with the response
var_dump($response);

// Poll the task status to know when it has been indexed
$client->waitForTask('<YOUR_INDEX_NAME>', $response['taskID']);

// Fetch search results, with typo tolerance
$response = $client->search(
    ['requests' => [
        ['indexName' => '<YOUR_INDEX_NAME>',
            'query' => '<YOUR_QUERY>',
            'hitsPerPage' => 50,
        ],
    ],
    ],
);

// play with the response
var_dump($response);

from algoliasearch.search.client import SearchClient

_client = SearchClient("YOUR_APP_ID", "YOUR_API_KEY")

# Add a new record to your Algolia index
response = await _client.save_object(
    index_name="<YOUR_INDEX_NAME>",
    body={
        "objectID": "id",
        "test": "val",
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())

# Poll the task status to know when it has been indexed
await client.wait_for_task(index_name="<YOUR_INDEX_NAME>", task_id=response.task_id)

# Fetch search results, with typo tolerance
response = await _client.search(
    search_method_params={
        "requests": [
            {
                "indexName": "<YOUR_INDEX_NAME>",
                "query": "<YOUR_QUERY>",
                "hitsPerPage": 50,
            },
        ],
    },
)

# use the class directly
print(response)

# print the JSON response
print(response.to_json())

require 'algolia'

client = Algolia::SearchClient.create('YOUR_APP_ID', 'YOUR_API_KEY')

# Add a new record to your Algolia index
response = client.save_object("<YOUR_INDEX_NAME>", { objectID: "id", test: "val" })

# use the class directly
puts response

# print the JSON response
puts response.to_json

# Poll the task status to know when it has been indexed
client.wait_for_task("<YOUR_INDEX_NAME>", response.task_id)

# Fetch search results, with typo tolerance
response = client.search(
  SearchMethodParams.new(
    requests: [SearchForHits.new(
      index_name: "<YOUR_INDEX_NAME>", query: "<YOUR_QUERY>", hits_per_page: 50
    )]
  )
)

# use the class directly
puts response

# print the JSON response
puts response.to_json

import algoliasearch.api.SearchClient

val client = SearchClient(appId = "YOUR_APP_ID", apiKey = "YOUR_API_KEY")

// Add a new record to your Algolia index
val response = client.saveObject(
  indexName = "<YOUR_INDEX_NAME>",
  body = JObject(List(JField("objectID", JString("id")), JField("test", JString("val"))))
)

// Use the response
val value = Await.result(response, Duration(100, "sec"))

// Poll the task status to know when it has been indexed
client.waitTask("<YOUR_INDEX_NAME>", response.getTaskID())

// Fetch search results, with typo tolerance
val response = client.search(
  searchMethodParams = SearchMethodParams(
    requests = Seq(
      SearchForHits(
        indexName = "<YOUR_INDEX_NAME>",
        query = Some("<YOUR_QUERY>"),
        hitsPerPage = Some(50)
      )
    )
  )
)

// Use the response
val value = Await.result(response, Duration(100, "sec"))

import Search

let client = try SearchClient(appID: "YOUR_APP_ID", apiKey: "YOUR_API_KEY")

// Add a new record to your Algolia index
let response = try await client.saveObject(
    indexName: "<YOUR_INDEX_NAME>",
    body: ["objectID": "id", "test": "val"]
)

// Poll the task status to know when it has been indexed
try await client.waitForTask(with: response.taskID, in: "<YOUR_INDEX_NAME>")

// Fetch search results, with typo tolerance
let response: SearchResponses<Hit> = try await client
    .search(searchMethodParams: SearchMethodParams(requests: [SearchQuery.searchForHits(SearchForHits(
        query: "<YOUR_QUERY>",
        hitsPerPage: 50,
        indexName: "<YOUR_INDEX_NAME>"
    ))]))

Advanced use cases

If you don’t find a use case that suits your needs, please request it.

You can learn more on how to use Algolia in your project by reading our dedicated guides for advanced use cases.

The generated API clients are a work in progress, you can also find our stable clients on the Algolia documentation.

Installation​

Example​

Advanced use cases​

Installation

Example

Advanced use cases