Guides

Android SDK

Install and use io.navvo:maps-android — a NavvoMapView for Kotlin apps plus a full NavvoServices client for search, geocoding, places, routing, traffic and more.

Android SDK

The official io.navvo:maps-android library gives you two things:

NavvoMapView — an embeddable, interactive Navvo basemap view (camera, markers, style switching, GeoJSON layers) pointed at Navvo's GET /tiles/style.
NavvoServices — a coroutine-first client for the Navvo Web Service (search, geocode, places, routing, traffic, matrix, isochrone, weather, EV, transit…).

Everything is Navvo-branded and only ever calls https://navvo.io/api/v1. Coordinates are uniformly LatLng(lat, lng).

Since 0.2.0 the SDK also ships an opt-in Android Auto layer (io.navvo.maps.car) — the same map on the car screen — and the view is size-agnostic, so tablets, foldables and Chromebooks work with no extra configuration.

Requires: Android 5.0+ (minSdk 21) · Kotlin 1.9+ · JDK 17 / AGP 8.2+ · Android Auto additionally needs androidx.car.app:app.

Install

Download the library source from docs.navvo.io/sdks, include it as a Gradle module (or publish it to your Maven repository), then:

dependencies {
    implementation("io.navvo:maps-android:0.2.0")
}

Initialize

NavvoMaps.initialize(apiKey = "nvvo_YOUR_KEY")

Provide your API key. Without a key the basemap renders with a "Navvo Map Developer (Provide Your API Key)" watermark on every tile. Basemap attribution is © Navvo.

Display a map

val mapView = NavvoMapView(context).apply {
    setStyle(NavvoMapStyle.STANDARD) // STANDARD · DARK · POSITRON · SATELLITE · TERRAIN · THREE_D
    moveCamera(CameraPosition(target = LatLng(31.9539, 35.9106), zoom = 12.0))
    addMarker(NavvoMarker(id = "a", position = LatLng(31.9539, 35.9106)))
    setOnMapClickListener { latLng -> /* … */ }
}

Use the services (no map required)

val svc = NavvoServices.instance // uses the key from NavvoMaps.initialize

val result = svc.search("coffee in Abdoun", near = LatLng(31.95, 35.91), limit = 8)
val hits = svc.geocode("Rainbow Street, Amman")
val plan = svc.plan(RoutePlanRequest(
    locations = listOf(PlanStop(LatLng(31.95, 35.91)), PlanStop(LatLng(31.99, 35.95))),
    costing = RouteCosting.AUTO,
))

All calls are suspend; synchronous variants exist for non-coroutine callers.

Android Auto

io.navvo.maps.car (0.2.0+) renders the Navvo map on the car screen through the androidx Car App Library and adds template-safe chrome — no separate car SDK:

Class	Role
`NavvoCarAppService` / `NavvoCarSession`	Ready-to-declare car entry point (host validation included); subclass to customize.
`NavvoCarMapScreen`	Base map screen — `NavigationTemplate` + zoom action strip over the live map.
`NavvoCarNavigationScreen`	Turn-by-turn skeleton: `updateStep(cue, meters)`, `updateDestination(meters, seconds, arrivalMillis)`, `clearNavigationInfo()`.
`NavvoCarMapRenderer`	Draws the map onto the car surface and turns host pan/zoom gestures into camera moves; `screen.renderer.getMapAsync { map -> … }` hands you the normal `NavvoMapController`.

1. Add the car library next to the SDK (the SDK itself compiles against it compileOnly, so phone-only apps carry nothing):

dependencies {
    implementation("io.navvo:maps-android:0.2.0")
    implementation("androidx.car.app:app:1.4.0")
}

2. Declare the service and car metadata in your app's AndroidManifest.xml:

<uses-permission android:name="androidx.car.app.ACCESS_SURFACE" />
<uses-permission android:name="androidx.car.app.NAVIGATION_TEMPLATES" />

<application>
    <meta-data android:name="androidx.car.app.minCarApiLevel" android:value="1" />
    <meta-data
        android:name="com.google.android.gms.car.application"
        android:resource="@xml/automotive_app_desc" />

    <service
        android:name="io.navvo.maps.car.NavvoCarAppService"
        android:exported="true">
        <intent-filter>
            <action android:name="androidx.car.app.CarAppService" />
            <category android:name="androidx.car.app.category.NAVIGATION" />
        </intent-filter>
    </service>
</application>

with res/xml/automotive_app_desc.xml:

<automotiveApp>
    <uses name="template" />
</automotiveApp>

3. Customize the screen (NavvoMaps.initialize from Application.onCreate already covers the car session — same process, same key):

class MyCarSession : NavvoCarSession() {
    override fun onCreateScreen(intent: Intent): Screen =
        object : NavvoCarNavigationScreen(carContext) {}.also { screen ->
            screen.renderer.getMapAsync { map ->
                map.moveCamera(CameraPosition(target = LatLng(31.95, 35.91), zoom = 13.0))
            }
            screen.updateStep("Turn right onto Rainbow Street", 320.0)
        }
}

Test with Android's Desktop Head Unit; debug builds accept any host, release builds only the known Android Auto hosts.

Tablets & large screens need nothing at all: NavvoMapView is a plain size-agnostic FrameLayout that fills whatever bounds your layout gives it — phones, tablets, foldables and Chromebooks, any orientation.

Errors

Every call throws a typed subclass of NavvoException: NavvoAuthError (401), NavvoScopeError (403), NavvoNotFoundError (404), NavvoValidationError (400/422), NavvoRateLimitError (429, honours Retry-After), NavvoServerError (5xx), NavvoNetworkError/NavvoTimeoutError. place(slug) returns null for unknown slugs.

NavvoMapView renders via an embedded open-source map engine under the hood — you only ever interact with Navvo classes and Navvo endpoints.

Flutter SDK

Install and use the official navvo_maps_flutter package — an embeddable NavvoMap widget plus a pure-Dart NavvoServices client for search, geocoding, places, routing, traffic and more.

iOS SDK

Install and use the NavvoMaps Swift package — a NavvoMapView for UIKit/SwiftUI plus an async NavvoServices client for search, geocoding, places, routing, traffic and more.