Skip to content

Kotlin SDK

Developers targeting JVM languages like Kotlin can install our official package to get started with the geospatial APIs in just a few lines of code. The core of the SDK is generated using our official OpenAPI spec, so you get a strongly typed interface, fantastic code completion and documentation, and quick access to new features as we release them.

Quickstart

Authenticate to GitHub Packages

You'll need an access token to install from GitHub Packages. GitHub has a guide on setting this up.

Add the Maven Repository

Next, add the repository to your repositories block like so.

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.

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: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}"
}
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.

Screenshot of API key management in the client dashboard when no key exists

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)
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)

// If you're using Kotlin with coroutines, you can also await rather than executing
// synchronously when using suspend functions.
val res = service.autocomplete("Põhja pst 27a").execute()

if (res.isSuccessful) {
    println("Found result: ${res.body()?.features?.first()}")
} else {
    println("Request failed with error code ${res.code()}")
}

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.