SDK Maps para Android

O que é

Uma camada fina sobre o MapLibre Native para Android (org.maplibre.gl:android-sdk 11), o motor cartográfico de código aberto. Esta camada:

• aplica o estilo alojado do N-Ways (claro ou escuro, nomes em inglês ou em francês);
• envia a sua chave e a identidade da sua aplicação (X-Android-Package e X-Android-Cert, o SHA-1 do seu certificado de assinatura) com cada pedido para o N-Ways, e nunca para mais ninguém, para que uma chave restringida à sua aplicação funcione;
• mantém a menção «© N-Ways · © OpenStreetMap contributors · Protomaps» no mapa;
• tem um cliente para a geocodificação, os códigos postais, o preenchimento automático, a validação de endereços, os lugares, os percursos, a matriz de percursos e as tarifas.

Android 6.0 (API 23) ou mais recente.

Instalação

Enquanto não é publicado, compile-o a partir do código-fonte e instale-o no seu repositório Maven local:

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

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

Restringir a sua chave

Restrinja a chave à sua aplicação: o nome do pacote e a impressão digital SHA-1 do certificado com que é assinada. As aplicações do Google Play são assinadas pela assinatura de aplicações do Play (Play App Signing): use o SHA-1 que a Play Console mostra em App integrity, mais o do seu certificado de carregamento ou de depuração para as builds que instala o próprio. Chaves de API

Mostrar um mapa

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

// Numa Activity: um mapa de Lagos, escuro, com os nomes em francês.
val mapView = MapView(this, NWaysMapDefaults.mapOptions(this))
setContentView(mapView)
mapView.getMapAsync { map ->
    map.setNWaysStyle(Theme.DARK, lang = "fr") { style ->
        // Acrescente aqui os seus marcadores e camadas.
    }
}

Tudo o resto é MapLibre Native: marcadores, fontes GeoJSON, movimentos de câmara, apresentação da localização. O estilo conta como um carregamento de mapa sempre que é aplicado.

Chamar as API

NWaysMaps.client tem funções suspend que lançam NWaysError (com httpStatus, reason, message e a espera 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)
    }
}

Para as outras API (otimização de percursos, mapas estáticos, seguimento de frota), use a biblioteca cliente Kotlin.

Offline

Para os estafetas que perdem a rede, transfira um pacote offline e aponte o estilo para o ficheiro local.

Aplicação de exemplo

O código-fonte do SDK contém uma aplicação de exemplo (android/sample): um mapa de Lagos, um botão claro/escuro e uma pesquisa que coloca um marcador. Ponha a sua chave em android/local.properties na forma nways.apiKey=… (nunca faça commit dela).

Licença

O SDK Android (ng.nways:maps) é de código aberto sob a licença Apache 2.0 (Apache-2.0), Copyright 2026 N-WAYS LIMITED; o seu código-fonte contém os ficheiros LICENSE e NOTICE. Depende do MapLibre Native para Android (BSD 2-Clause), do OkHttp e do kotlinx.serialization (Apache 2.0), cada um sob a sua própria licença. A licença cobre apenas o código: os mapas e os dados do N-Ways continuam © dos contribuidores do OpenStreetMap sob a Open Database Licence (ODbL), com a menção mostrada em todo o lado onde aparecem.