osrmroute
Documentation

Mobile SDKs

Kotlin for Android/JVM and Swift for iOS. Call OSRMRoute geographic APIs with typed models and asynchronous requests.

Kotlin · AndroidSwift · iOSOSRMRouteAPI

Mobile Access

Register an application, configure platform verification, then enable access.

Applications share their linked API key’s allowance. Caps count all traffic on that key; creating an app adds no credits.

Register application →
  1. Register platform and app identity
  2. Connect provider and verify a real device
  3. Add SDK, enable access and send a request

Kotlin and Swift SDK 0.2.0 include Mobile Access. Install the stable package, configure platform verification and use your public app ID.

Android · Play Integrity

Register your app in Google Play and link its Cloud project to Play Integrity. Contact support with the public OSRMRoute App ID, package name and Cloud project number. We will arrange the private credential transfer separately and confirm the connection. Then install from a Play test track, enable access and verify a real device. Never attach a private key to a ticket.

App signing certificate SHA-256

Google Play Console → App integrity → App signing key certificate → SHA-256. Paste the colon-separated fingerprint; conversion is automatic.

Android · app/build.gradle.kts
implementation("com.google.android.play:integrity:1.6.0")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.10.1")
Kotlin · Play Integrity
import android.content.Context
import android.util.Base64
import com.google.android.play.core.integrity.IntegrityManagerFactory
import com.google.android.play.core.integrity.StandardIntegrityManager
import com.osrmroute.MobileAccess
import com.osrmroute.OSRMRoute
import kotlinx.coroutines.tasks.await
import java.util.UUID

// Call once; reuse the returned pair and close both when no longer needed.
suspend fun makeMapClient(context: Context, cloudProjectNumber: Long): Pair<MobileAccess, OSRMRoute> {
    val appId = "YOUR_PUBLIC_APP_ID"
    val prefs = context.getSharedPreferences("osrmroute.$appId", Context.MODE_PRIVATE)
    val keyId = prefs.getString("installation", null) ?: UUID.randomUUID().toString().also {
        prefs.edit().putString("installation", it).apply()
    }
    val provider = IntegrityManagerFactory.createStandard(context.applicationContext)
        .prepareIntegrityToken(StandardIntegrityManager.PrepareIntegrityTokenRequest.builder()
            .setCloudProjectNumber(cloudProjectNumber).build()).await()
    val access = MobileAccess(appId, keyId) { payload ->
        val hash = Base64.encodeToString(MobileAccess.requestHash(payload),
            Base64.URL_SAFE or Base64.NO_WRAP or Base64.NO_PADDING)
        provider.request(StandardIntegrityManager.StandardIntegrityTokenRequest.builder()
            .setRequestHash(hash).build()).await().token()
    }
    return access to OSRMRoute(baseUrl = "https://osrmroute.com", tokenProvider = { access.token() })
}
// cloudProjectNumber: your Google Cloud project linked to Play Integrity.
// After enabling the app and allowing the geocode scope:
// val (access, client) = makeMapClient(context, yourCloudProjectNumber)
// val result = client.geocode("Berlin", 1)

iOS · App Attest

Copy the 10-character App ID prefix from Apple Developer. Enable production App Attest in the signed app.

Swift · App Attest
import Foundation
import OSRMRoute

// Call once during application setup; retain and reuse the returned client.
@MainActor
func makeMapClient() async throws -> OSRMRouteClient {
    let appID = "YOUR_PUBLIC_APP_ID"
    let storageKey = "osrmroute.attest.\(appID)"
    let keyID: String
    if let saved = UserDefaults.standard.string(forKey: storageKey) {
        keyID = saved
    } else {
        keyID = try await AppleMobileProof.generateKey()
        UserDefaults.standard.set(keyID, forKey: storageKey)
    }
    let access = try MobileAccess(appID: appID, keyID: keyID) { payload, enrolled in
        try await AppleMobileProof.proof(keyID: keyID, payload: payload, enrolled: enrolled)
    }
    return try OSRMRouteClient(baseURL: URL(string: "https://osrmroute.com")!) {
        try await access.token()
    }
}
// After enabling the app and allowing the geocode scope:
// let client = try await makeMapClient()
// let result = try await client.geocode("Berlin", limit: 1)

Alternative: use your own backend

Keep your OSRMRoute API key on your server. The app supplies its short-lived application session to your own authenticated proxy. The proxy must allowlist endpoints, enforce user access and usage limits, and inject the OSRMRoute key server-side. It must not forward the application token to OSRMRoute.

Download and install

Install Kotlin 0.2.0 from Maven Central and Swift 0.2.0 using its public GitHub URL in Xcode or Swift Package Manager. Source ZIP downloads remain available.

settings.gradle.kts
dependencyResolutionManagement {
    repositories { mavenCentral() }
}
app/build.gradle.kts
dependencies {
    implementation("com.osrmroute:osrmroute-kotlin:0.2.0")
}
// AndroidManifest.xml:
// <uses-permission android:name="android.permission.INTERNET" />
Xcode · Swift Package Manager
.package(url: "https://github.com/Mammadoff/osrmroute-swift.git", from: "0.2.0")
// Xcode: File > Add Package Dependencies > enter the GitHub URL.
// Add the OSRMRoute library to your application target.

Kotlin · Android / JVM

GitHub · Kotlin
Kotlin
import com.osrmroute.OSRMRoute
import com.osrmroute.Coordinate

// Call from a coroutine. Use your app session, not an embedded OSRMRoute key.
val client = OSRMRoute(
    baseUrl = "https://your-backend.example/location",
    tokenProvider = { applicationSessionToken }
)
val result = client.route(listOf(
    Coordinate(latitude = 52.52, longitude = 13.405),
    Coordinate(latitude = 52.50, longitude = 13.39)
))
val metres = result.routes.first().distance
// Close the shared client when its owner is disposed.
client.close()

Swift · iOS

GitHub · Swift
Swift
import Foundation
import OSRMRoute

// Call from an async function. Use your own authenticated backend.
let client = try OSRMRouteClient(
    baseURL: URL(string: "https://your-backend.example/location")!,
    tokenProvider: { applicationSessionToken }
)
let result = try await client.route([
    Coordinate(latitude: 48.8566, longitude: 2.3522),
    Coordinate(latitude: 48.8606, longitude: 2.3376)
])
let metres = result.routes[0].distance

Supported methods

Typed responses: route, matrix, geocode, reverse and autocomplete. Places returns JSON. getJson/getJSON and postJson/postJSON support additional geographic API endpoints. Server plan limits and coverage still apply.

Requests and errors

Retries default to zero. Opt-in retries apply only to GET responses with status 429, 502, 503 or 504, at most twice. Retry-After delays over 30 seconds or date-form headers are not replayed. Network failures and POST requests are never retried automatically.

Kotlin / Swift
// Kotlin: OSRMRouteException.status and .code
// Swift: SDKError.http(status:), .transport, .invalidResponse, .invalidInput
// Cancellation propagates to the caller.
// Default timeout: 30 seconds. Configurable maximum: 120 seconds.
// Coordinates: latitude, longitude. Distances: metres. Durations: seconds.
// Matrix null cells mean unreachable, not zero.

API integration only

These packages do not render maps, provide offline maps or implement turn-by-turn navigation. Kotlin targets Android API 21+ and JVM 17; Swift targets iOS 15+ and macOS 12+. Package tests do not replace real-device acceptance.

Documentation →

OSRMRoute Support

Talk directly to our team

HERE TO HELP

How can we help?

Send a message. Ticket replies are also sent to your verified email.

Your chats

Your chats will appear here.