Recombee API Client

Documentation   •   Issues   •   Support

✨ Features

• Thin Kotlin wrapper around the Recombee API
• Supported endpoints: Interactions, Recommendations & Search
• Made for Android apps and Compose Multiplatform

🚀 Getting Started

Add the dependency into your build.gradle.kts:

implementation("com.recombee:apiclientkotlin:5.0.0")

📚 Version Catalogs

If you're using version catalogs, first add the dependency into your libs.versions.toml:

[versions]
recombee = "5.0.0"

[libraries]
recombee = { group = "com.recombee", name = "apiclientkotlin", version.ref = "recombee" }

Then reference it in your build.gradle.kts:

implementation(libs.recombee)

🏗️ Example

You can send user-item interactions and receive recommendations as follows:

// Initialize the API client with the ID of your database and the associated PUBLIC token
val client =
    RecombeeClient(
        databaseId = "database-id",
        publicToken = "...db-public-token...",
        region = Region.UsWest // the region of your database
    )

// Send interactions
client.send(
    AddDetailView(
        userId = "user-4395",
        itemId = "item-129",
        recommId = "23eaa09b-0e24-4487-ba9c-8e255feb01bb",
    )
)

// Request recommendations
client.send(
    // Get 10 items for "user-x" using the "homepage-top-for-you" scenario from the Admin UI
    RecommendItemsToUser(
        userId = "user-x",
        count = 10,
        scenario = "homepage-top-for-you",
        returnProperties = true,
        includedProperties = listOf("title")
    ),
    { response: RecommendationResponse ->
        // `recommId` needs to be sent with interactions based on recommendations
        println("recommId: ${response.recommId}")

        // The `recomms` object contains the `id` (and `values` if `returnProperties` is true)
        for (item in response.recomms) {
            println("ID: ${item.id}, Title: ${item.getValues()["title"]}")
        }
    },
    { exception: ApiException ->
        println("Exception: $exception")
        // Ideally, you should provide a fallback if an error occurs...
    }
)

Coroutine support is also available, simply replace send with sendAsync:

suspend fun getItems(): List<Item> {
    // Get 10 items for "user-x" using the "homepage-top-for-you" scenario from the Admin UI
    val result =
        client.sendAsync(
            RecommendItemsToUser(
                userId = "user-x",
                count = 10,
                scenario = "homepage-top-for-you",
                returnProperties = true,
                includedProperties = listOf("title", "images")
            )
        )

    // Ideally, you should provide a fallback if an error occurs
    if (result.isFailure) {
        return listOf()
    }

    val data = result.getOrNull() ?: return listOf()

    // `recommId` needs to be sent with interactions based on recommendations
    println("recommId: ${data.recommId}")

    // Map the recommendations to your own internal data type
    return data.recomms.map { item ->
        Item(
            id = item.id,
            title = item.getValues()["title"] as? String ?: "",
            images = item.getValues()["images"] as? List<String> ?: listOf(),
            recommId = data.recommId
        )
    }
}

Tip

We also published a simple example Android app to help you with the integration. Feel free to use it as a reference.

📝 Documentation

Discover the full Kotlin API Client documentation for comprehensive guides and examples.

For a complete breakdown of all endpoints and their responses, check out our API Reference.

🤝 Contributing

We welcome all contributions—whether it’s fixing a bug, improving documentation, or suggesting a new feature.

To contribute, simply fork the repository, make your changes, and submit a pull request. Be sure to provide a clear description of your changes.

Thanks for helping make this project better!

🔧 Troubleshooting

Are you having issues? We recommend checking our documentation to see if it contains a possible solution.

If you want to reach out, you can either open a GitHub issue or send an email to support@recombee.com.

📄 License

The Recombee Kotlin API Client is provided under the MIT License.