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¶

Authenticate to GitHub Packages

We host our Maven packages on GitHub Packages. GitHub requires authentication for this, and has a guide on setting this up.

Add the Maven Repository

Next, add the repository to the repositories block in your Gradle build script like so.

KotlinGroovy

build.gradle.kts

repositories {
    mavenCentral()

    maven {
        url = uri("https://maven.pkg.github.com/stadiamaps/stadiamaps-api-kotlin")
        credentials {
            username = project.findProperty("gpr.user") as String? ?: System.getenv("USERNAME")
            password = project.findProperty("gpr.token") as String? ?: System.getenv("TOKEN")
        }
    }
}

build.gradle

repositories {
    mavenCentral()

    maven {
        url = uri("https://maven.pkg.github.com/stadiamaps/stadiamaps-api-kotlin")
        credentials {
            username = project.findProperty("gpr.user") ?: System.getenv("USERNAME")
            password = project.findProperty("gpr.token") ?: System.getenv("TOKEN")
        }
    }
}

Add Dependencies

Now you're ready to add the package and its dependencies.

KotlinGroovy

build.gradle.kts

dependencies {
    val retrofitVersion = "2.9.0"

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

    // 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.9.0"

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

    // 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}"
}

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.

Sign in to the client dashboard. (If you don't have an account yet, sign up for free; no credit card required!)
Click "Manage Properties."
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.
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()}")
}

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.