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