Maps SDK for Android

What it is

A thin layer over MapLibre Native for Android (org.maplibre.gl:android-sdk 11), the open-source map engine. It:

• sets N-Ways’ hosted style (light or dark, English or French names);
• sends your key and your app’s identity (X-Android-Package and X-Android-Cert, the SHA-1 of your signing certificate) with every request to N-Ways, and never to anyone else, so a key restricted to your app works;
• keeps the credit “© N-Ways · © OpenStreetMap contributors · Protomaps” on the map;
• has a client for geocoding, postcodes, autocomplete, address validation, places, routes, the route matrix and fares.

Android 6.0 (API 23) and later.

Install

Until it’s published, build it from source and install it into your local Maven repository:

cd sdk-native/android && ./gradlew :nways-maps:publishToMavenLocal

repositories { mavenLocal(); google(); mavenCentral() }
dependencies { implementation("ng.nways:maps:1.0.0") }

Restrict your key

Restrict the key to your app: its package name and the SHA-1 fingerprint of the certificate it’s signed with. Apps from Google Play are signed by Play App Signing: use the SHA-1 Play Console shows under App integrity, plus your upload or debug certificate’s for builds you install yourself. API keys

Show a map

import ng.nways.maps.NWaysMaps
import ng.nways.maps.NWaysMapDefaults
import ng.nways.maps.Theme
import ng.nways.maps.setNWaysStyle

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        NWaysMaps.init(this, apiKey = BuildConfig.NWAYS_API_KEY)
    }
}

// In an Activity: a map over Lagos, dark, with French names.
val mapView = MapView(this, NWaysMapDefaults.mapOptions(this))
setContentView(mapView)
mapView.getMapAsync { map ->
    map.setNWaysStyle(Theme.DARK, lang = "fr") { style ->
        // Add your markers and layers here.
    }
}

Everything else is MapLibre Native: markers, GeoJSON sources, camera moves, location display. The style is one map load each time it’s set.

Call the APIs

NWaysMaps.client has suspend functions that throw NWaysError (with httpStatus, reason, message and the Retry-After wait):

lifecycleScope.launch {
    try {
        val found = NWaysMaps.client.geocode("Allen Avenue", near = NWaysLatLng(6.6018, 3.3515), limit = 5)
        val trip = NWaysMaps.client.route(
            origin = NWaysLatLng(6.6018, 3.3515).asWaypoint(),
            destination = Waypoint.Postcode("LA08A09DB09"),
            mode = TravelMode.OKADA,
            fares = true,
        )
        val best = trip.routes.first() // distanceM, durationS, geometry, steps, fares
    } catch (e: NWaysError) {
        if (e.isRetryable) retryLater(e.retryAfterSeconds) else showProblem(e.message)
    }
}

For the other APIs (route optimisation, static maps, fleet tracking), use the Kotlin client library.

Offline

For riders who lose the network, download an offline pack and point the style at the local file.

Sample app

The SDK’s source has a sample app (android/sample): a map of Lagos, a light and dark switch, and a search that drops a marker. Put your key in android/local.properties as nways.apiKey=… (never commit it).

Licence

The Android SDK (ng.nways:maps) is open source under the Apache License 2.0 (Apache-2.0), Copyright 2026 N-WAYS LIMITED; its source has the LICENSE and NOTICE files. It depends on MapLibre Native for Android (BSD 2-Clause), OkHttp and kotlinx.serialization (Apache 2.0), each under its own licence. The licence covers the code only: N-Ways maps and data stay © OpenStreetMap contributors under the Open Database Licence (ODbL), with the credit shown wherever they appear.