API Reference / API Methods / The Kotlin API client

Algolia’s Kotlin API client lets you use Algolia’s APIs from your Kotlin application. Compared to using the APIs directly, using the Kotlin 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.

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

The Kotlin API client is built on top of these Kotlin libraries:

Install the Kotlin API client

The Algolia Kotlin API client requires Kotlin version 1.13.30 or higher. The API client supports both JVM (back end) and Android (front end) projects.

Install the Kotlin API client by adding the following dependencies to your build.gradle.kts file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
dependencies {
    // for Gradle version 6.0 and higher
    implementation("com.algolia:algoliasearch-client-kotlin:1.12.2")
    // for Gradle < 6.0:
    implementation("com.algolia:algoliasearch-client-kotlin-jvm:1.12.2")

    // Choose one of the following HTTP clients
    implementation("io.ktor:ktor-client-apache:1.6.8")
    implementation("io.ktor:ktor-client-okhttp:1.6.8")
    implementation("io.ktor:ktor-client-android:1.6.8")
    implementation("io.ktor:ktor-client-cio:1.6.8")
    implementation("io.ktor:ktor-client-jetty:1.6.8")

    // For serializing your records to and from JSON
    imlpementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.3.2")
}

For serializing and deserializing your records, add the following plugin to your build.gradle.kts file:

1
2
3
4
plugins {
  // ...
  kotlin("plugin.serialization") version "1.6.10"
}

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. Copy the following code into a text editor. If you’re signed in, the code samples below show your Algolia application ID and API key. If you’re not signed in, replace YourApplicationID with your Algolia application ID and YourAdminAPIKey with your Admin API key. You can find both in your Algolia account.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    
    // Main.kt
    import com.algolia.search.client.ClientSearch
    import com.algolia.search.helper.deserialize
    import com.algolia.search.model.APIKey
    import com.algolia.search.model.ApplicationID
    import com.algolia.search.model.IndexName
    import com.algolia.search.model.ObjectID
    import com.algolia.search.model.indexing.Indexable
    import com.algolia.search.model.search.Query
    import kotlinx.serialization.Serializable
    
    // A simple record for your index
    @Serializable
    private data class Record(
       val name: String,
       override val objectID: ObjectID
    ) : Indexable
    
    suspend fun main() {
       // Connect and authenticate with your Algolia app
       val client = ClientSearch(
          applicationID = ApplicationID("YourApplicationID"),
          apiKey = APIKey("YourAdminAPIKey")
       )
    
       // Create a new index and add a record (using the `Record` class)
       val index = client.initIndex(indexName = IndexName("test_index"))
       val record = Record("test_record", ObjectID("1"))
    
       index.run {
          saveObject(Record.serializer(), record).wait()
       }
    
       // Search the index and print the results
       val response = index.run {
          search(Query("test_record"))
       }
       val results: List<Record> = response.hits.deserialize(Record.serializer())
       println(results[0])
    }
    
  2. Build and run the project.

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

    1
    
    Record(name=foo, 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?