Skip to content

Kotlin SDK

Add geocoding, search, routing, and more to your apps and services with just a few lines of code.

The Stadia Maps Kotlin SDK is your go-to tool for utilizing our APIs in Android applications, Spring Boot services, or anything else running on the JVM. Every class, method, and property includes detailed documentation straight from our API spec.

Everything is Kotlin-native, so you can opt into newer features like coroutines as desired, while remaining fully compatibility with Java and other languages in the ecosystem.

Looking for maps?

If you're building interactive maps in Kotlin, head over to maps for mobile.

Quickstart

Installation

If aren't already using Maven Central, add the repository in your Gradle build script.

repositories {
    mavenCentral()
}

Then, add the API package and its dependencies.

build.gradle.kts
dependencies {
    val retrofitVersion = "2.11.0"

    // API package
    implementation("com.stadiamaps:api:3.2.1")

    // Dependencies
    implementation("com.squareup.moshi:moshi-kotlin:1.14.0")
    implementation("com.squareup.moshi:moshi-adapters:1.14.0")
    implementation("com.squareup.okhttp3:logging-interceptor:4.10.0")
    implementation("com.squareup.retrofit2:retrofit:$retrofitVersion")
    implementation("com.squareup.retrofit2:converter-moshi:$retrofitVersion")
    implementation("com.squareup.retrofit2:converter-scalars:$retrofitVersion")
}
build.gradle
dependencies {
    def retrofitVersion = "2.11.0"

    // API package
    implementation 'com.stadiamaps:api:3.2.1'

    // Dependencies
    implementation 'com.squareup.moshi:moshi-kotlin:1.15.1'
    implementation 'com.squareup.moshi:moshi-adapters:1.15.1'
    implementation 'com.squareup.okhttp3:logging-interceptor:4.10.0'
    implementation "com.squareup.retrofit2:retrofit:${retrofitVersion}"
    implementation "com.squareup.retrofit2:converter-moshi:${retrofitVersion}"
    implementation "com.squareup.retrofit2:converter-scalars:${retrofitVersion}"
}

Our API package is available on Maven Central. All you need to do is add a few dependencies to your pom.xml.

pom.xml
<properties>
    <retrofit.version>2.9.0</retrofit.version>
</properties>

<dependencies>
    <!-- API package -->
    <dependency>
        <groupId>com.stadiamaps</groupId>
        <artifactId>api</artifactId>
        <version>3.2.1</version>
    </dependency>

    <!-- Dependencies -->
    <dependency>
        <groupId>com.squareup.moshi</groupId>
        <artifactId>moshi-kotlin</artifactId>
        <version>1.15.1</version>
    </dependency>
    <dependency>
        <groupId>com.squareup.moshi</groupId>
        <artifactId>moshi-adapters</artifactId>
        <version>1.15.1</version>
    </dependency>
    <dependency>
        <groupId>com.squareup.okhttp3</groupId>
        <artifactId>logging-interceptor</artifactId>
        <version>4.10.0</version>
    </dependency>
    <dependency>
        <groupId>com.squareup.retrofit2</groupId>
        <artifactId>retrofit</artifactId>
        <version>${retrofit.version}</version>
    </dependency>
    <dependency>
        <groupId>com.squareup.retrofit2</groupId>
        <artifactId>converter-moshi</artifactId>
        <version>${retrofit.version}</version>
    </dependency>
    <dependency>
        <groupId>com.squareup.retrofit2</groupId>
        <artifactId>converter-scalars</artifactId>
        <version>${retrofit.version}</version>
    </dependency>
</dependencies>
Want to use something other than retrofit2?

If your team has standardized around another library like okhttp, chances are the code generator we use to make our official SDK has you covered. We've published a tutorial that will walk you through generating an API client inside your gradle project that's customized to your needs.

Getting an API Key

You'll need an API key to use the client in your project.

  1. Sign in to the client dashboard. (If you don't have an account yet, sign up for free; no credit card required!)
  2. Click "Manage Properties."
  3. If you have more than one property (ex: for several websites or apps), make sure you have selected the correct property from the dropdown at the top of the page.
  4. Under "Authentication Configuration," you can generate, view or revoke your API key.

Video: How to generate your API key

Example code

Here's a quick usage example of how to set up a client and do some geocoding.

// Imports (at the top of your source file; we'veß used some wildcard imports for simplicity)
import com.stadiamaps.api.apis.*
import com.stadiamaps.api.auth.ApiKeyAuth
import com.stadiamaps.api.infrastructure.ApiClient

// Set your API key (from an environment variable in this case) (1)
val apiKey = System.getenv("STADIA_API_KEY") ?: throw RuntimeException("API Key not set")

// Defining the host is optional and defaults to https://api.stadiamaps.com
// You can also use our EU endpoint to keep traffic within the EU like so:
// val client = ApiClient(baseUrl = "https://api-eu.stadiamaps.com")
val client = ApiClient()
client.addAuthorization("ApiKeyAuth", ApiKeyAuth("query", "api_key", apiKey))

// Configure a service for the group of APIs we want to talk to
val service = client.createService(GeocodingApi::class.java)

// Set up the request.
// Note: this code is blocking for demonstration purposes.
// If you're using Kotlin with coroutines,
// you can also use these asynchronously within suspend functions.
// Synchronous code can enqueue a callback to avoid blocking
// (you'll definitely want to do one of these instead when on the main thread of an app).
// See the docs for details: https://square.github.io/retrofit/2.x/retrofit/retrofit2/Call.html
val res = service.autocomplete("Põhja pst 27").execute()

if (res.isSuccessful) {
    println("Found result: ${res.body()?.features?.first()}")
} else {
    println("Request failed with error code ${res.code()}")
}
  1. Learn how to get an API key in our authentication guide.

You can find additional usage examples on the endpoint documentation pages.

Source Code

Our Kotlin SDK is completely open source! You can find the source code on GitHub.