SDK Maps pour Android

Ce que c’est

Une fine couche au-dessus de MapLibre Native pour Android (org.maplibre.gl:android-sdk 11), le moteur cartographique open source. Elle :

• applique le style hébergé de N-Ways (clair ou sombre, noms en anglais ou en français) ;
• envoie votre clé et l’identité de votre application (X-Android-Package et X-Android-Cert, le SHA-1 de votre certificat de signature) avec chaque requête vers N-Ways, et jamais à qui que ce soit d’autre, pour qu’une clé restreinte à votre application fonctionne ;
• garde la mention « © N-Ways · © OpenStreetMap contributors · Protomaps » sur la carte ;
• a un client pour le géocodage, les codes postaux, la saisie semi-automatique, la validation d’adresse, les lieux, les itinéraires, la matrice d’itinéraires et les tarifs.

Android 6.0 (API 23) ou plus récent.

Installation

En attendant sa publication, compilez-le depuis le code source et installez-le dans votre dépôt Maven local :

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

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

Restreindre votre clé

Restreignez la clé à votre application : son nom de package et l’empreinte SHA-1 du certificat avec lequel elle est signée. Les applications de Google Play sont signées par la signature d’application Play (Play App Signing) : utilisez le SHA-1 que la Play Console affiche sous App integrity, plus celui de votre certificat d’importation ou de débogage pour les builds que vous installez vous-même. Clés d’API

Afficher une carte

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

// Dans une Activity : une carte de Lagos, sombre, avec les noms en français.
val mapView = MapView(this, NWaysMapDefaults.mapOptions(this))
setContentView(mapView)
mapView.getMapAsync { map ->
    map.setNWaysStyle(Theme.DARK, lang = "fr") { style ->
        // Ajoutez ici vos marqueurs et vos couches.
    }
}

Tout le reste, c’est MapLibre Native : marqueurs, sources GeoJSON, mouvements de caméra, affichage de la position. Le style compte pour un chargement de carte chaque fois qu’il est appliqué.

Appeler les API

NWaysMaps.client a des fonctions suspend qui lèvent NWaysError (avec httpStatus, reason, message et l’attente de Retry-After) :

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

Pour les autres API (optimisation de tournées, cartes statiques, suivi de flotte), utilisez la bibliothèque cliente Kotlin.

Hors connexion

Pour les livreurs qui perdent le réseau, téléchargez un pack hors connexion et faites pointer le style vers le fichier local.

Application d’exemple

Le code source du SDK contient une application d’exemple (android/sample) : une carte de Lagos, un bouton clair/sombre et une recherche qui pose un marqueur. Mettez votre clé dans android/local.properties sous la forme nways.apiKey=… (ne la commitez jamais).

Licence

Le SDK Android (ng.nways:maps) est open source sous licence Apache 2.0 (Apache-2.0), Copyright 2026 N-WAYS LIMITED ; son code source contient les fichiers LICENSE et NOTICE. Il dépend de MapLibre Native pour Android (BSD 2-Clause), OkHttp et kotlinx.serialization (Apache 2.0), chacun sous sa propre licence. La licence couvre uniquement le code : les cartes et les données de N-Ways restent © les contributeurs d’OpenStreetMap sous l’Open Database Licence (ODbL), avec la mention affichée partout où elles apparaissent.