API client / Getting started / Customize

May. 28, 2024

Customize your Kotlin client

To change individual requests made with an API client, pass individual request options. To change all requests, create a custom configuration. This lets you change timeouts, add HTTP headers, and so on.

Use a custom host

You can change the default hosts to which the API client connects:

Copy
val client =
    ClientSearch(
        ConfigurationSearch(
            applicationID = ApplicationID("YourApplicationID"),
            apiKey = APIKey("YourWriteAPIKey"),
            hosts = listOf(RetryableHost("yourapplication.example.net"))
        )
    )

Changing the hosts can be useful if you want to proxy the search requests through another server, for example, to process the request or response, or to perform custom analytics.

Add HTTP headers to every request

Adding HTTP headers to your requests lets you set parameters such as a user identifier or an IP address. This can be useful for analytics, geographical search, or applying API key rate limits.

Copy
val configuration = ConfigurationSearch(
    applicationID = ApplicationID("YourApplicationID"),
    apiKey = APIKey("YourWriteAPIKey"),
    defaultHeaders = mapOf("NAME-OF-HEADER" to "value-of-header")
)
ClientSearch(configuration)

You can add these headers to your requests:

Header	Use case
`X-Algolia-UserToken`	Use API key rate limits
`X-Algolia-UserToken`	The Analytics API uses the value of this header to distinguish between users. It takes priority over any value in `X-Forwarded-For`. Use the `X-Algolia-UserToken` header to forward the user’s identity without relying on IP addresses.
`X-Forwarded-For`	Use for analytics in backend implementations. If your server sends the user’s IP address with every search, analytics can distinguish between users. Otherwise, the analytics uses the server’s IP address and considers all your users as a single user.
`X-Forwarded-For`	Use for geolocation, when you perform searches from your backend. This ensures that the geolocation for a search uses your user’s IP address and not that of your server.

Copy

1
2
3
4
5
$index = $client->initIndex('indexName');

$res = $index->search('query string', [
  'X-Algolia-UserToken' => 'user123'
]);

1
2
3
4
5
6
7
8
9
10
const index = client.initIndex('indexName');

const requestOptions = {
  headers: { 'X-Algolia-UserToken': 'user123' }
}

index.search('query string', requestOptions)
  .then(({ hits }) => {
    console.log(hits);
  });

1
2
3
4
5
6
7
8
let index = client.index(withName: "indexName")
var requestOptions = RequestOptions()
requestOptions.headers["X-Algolia-UserToken"] = "user123"
index.search(query: "query string", requestOptions: requestOptions) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
val indexName = IndexName("indexName")
val index = client.initIndex(indexName)
val query = Query("query string")
val requestOptions = requestOptions {
    header("X-Algolia-User-ID", "user123")
}

index.search(query, requestOptions)

1
2
3
4
5
6
7
8
Index index = client.InitIndex("indexName");

RequestOptions requestOptions = new RequestOptions
{
    Headers = new Dictionary<string,string>{ { "X-Algolia-UserToken", "user123" } }
};

var result = index.Search<Result>(new Query("query string"), requestOptions);

1
2
3
4
5
6
7
8
9
10
SearchIndex<Result> index = client.initIndex("indexName", Result.class);
Query query = new Query("query string");
RequestOptions requestOptions =
    new RequestOptions().addExtraHeader("X-Algolia-UserToken", "user123");

// Sync
SearchResult<Result> search = index.search(query, requestOptions);

// Async
CompletableFuture<SearchResult<Result>> search = index.searchAsync(query, requestOptions);

1
2
3
4
5
6
7
opts := []interface{}{
  opt.ExtraHeaders(map[string]string{
    "X-Algolia-UserToken": "user123",
  }),
}

res, err := index.Search("query string", opts...)

1
2
3
4
5
6
7
client.execute {
  search into "indexName" query Query(
      query = Some("query string")
  ) options RequestOptions(
      extraHeaders = Some(Map("X-Algolia-UserToken" -> "user123"))
  )
}

Make sure to use the same user token for your events (Insights API) and search requests (Search API).

If you send the authenticatedUserToken with your events, send the same value with your search requests.
If you send the userToken with your events, send the same value with your search requests.

Change timeouts for all requests

Network connections and DNS resolution can be slow. That’s why the API clients come with default timeouts.

Copy
val configuration = ConfigurationSearch(
    applicationID = ApplicationID("YourApplicationID"),
    apiKey = APIKey("YourWriteAPIKey"),
    connectTimeout = 2000 // connection timeout in milliseconds
    readTimeout = 5000, // read timeout in milliseconds
    writeTimeout = 30000 // write timeout in milliseconds
)
ClientSearch(configuration)

Don’t change the default timeouts without a good reason.

Copy

1
2
3
4
5
6
$index = $client->initIndex('indexName');

$res = $index->search('query string', [
  // Set the readTimeout to 20 seconds
  'readTimeout' => 20
]);

1
2
3
4
5
6
7
8
index = client.init_index('indexName')

request_options = {
  # Set the read_timeout to 20 seconds
      'read_timeout': 20
}

res = index.search('query string', request_options)

1
2
3
4
5
6
7
8
9
10
11
const index = client.initIndex('indexName');

const requestOptions = {
  // Set the readTimeout to 20 seconds
  timeouts: { read: 20 }
}

index.search('query string', requestOptions)
  .then(({ hits }) => {
    console.log(hits);
  });

1
2
3
4
5
6
7
8
index = client.init_index('indexName')

request_options = {
  # Set the readTimeout to 20 seconds
  "readTimeout": 20,
}

res = index.search('query string', request_options)

1
2
3
4
5
6
7
8
9
let index = client.index(withName: "indexName")
var requestOptions = RequestOptions()
// Set the readTimeout to 20 seconds
requestOptions.readTimeout = 20
index.search(query: "query string", requestOptions: requestOptions) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
val indexName = IndexName("indexName")
val index = client.initIndex(indexName)
val query = Query("query string")
val requestOptions = requestOptions {
  // Set the readTimeout to 20 seconds
    readTimeout = 20
}

index.search(query, requestOptions)

1
2
3
4
5
6
7
8
9
Index index = client.InitIndex("indexName");

RequestOptions requestOptions = new RequestOptions
{
  // Set the readTimeout to 20 seconds
  Timeout = 20
};

var result = index.Search<Result>(new Query("query string"), requestOptions);

1
2
3
4
5
6
7
8
9
10
11
12
SearchIndex<Result> index = client.initIndex("indexName", Result.class);
Query query = new Query("query string");
RequestOptions requestOptions =
    new RequestOptions()
        // Set the timeout to 20 seconds
        .setTimeout(20000);

// Sync
SearchResult<Result> search = index.search(query, requestOptions);

// Async
CompletableFuture<SearchResult<Result>> search = index.searchAsync(query, requestOptions);

1
2
3
4
5
6
7
8
// Set the readTimeout to 20 seconds
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)

opts := []interface{}{
    ctx,
}

res, err := index.Search("query string", opts...)

Select an HTTP client

The Kotlin API client relies on Ktor for its HTTP layer. Ktor lets you choose and configure the underlying HTTP engine.

See Engines in the Ktor documentation for a list of all supported HTTP engines.

If you don’t explicitly specify an HTTP engine, Ktor selects one for you, depending on which dependencies you installed.

Apache

Copy

1
implementation "io.ktor:ktor-client-apache:$ktor_version"

Copy
ClientSearch(
    ConfigurationSearch(
        applicationID = ApplicationID("Your Application ID"),
        apiKey = APIKey("Your API key"),
        engine = Apache.create {
            // Pass additional configuration here.
        }
    )
)

OkHttp

Copy

1
implementation "io.ktor:ktor-client-okhttp:$ktor_version"

Copy
ClientSearch(
    ConfigurationSearch(
        applicationID = ApplicationID("Your Application ID"),
        apiKey = APIKey("Your API key"),
        engine = OkHttp.create {
            // Pass additional configuration here.
        }
    )
)

Android HttpUrlConnection

Copy

1
implementation "io.ktor:ktor-client-android:$ktor_version"

Copy
ClientSearch(
    ConfigurationSearch(
        applicationID = ApplicationID("Your Application ID"),
        apiKey = APIKey("Your API key"),
        engine = Android.create {
            // Pass additional configuration here.
        }
    )
)

Did you find this page helpful?

Customize your Kotlin client

Use a custom host

Add HTTP headers to every request

Change timeouts for all requests

Select an HTTP client

Apache

OkHttp

Android HttpUrlConnection

On this page