SDK Maps para a web

O que é

O SDK Maps do N-Ways para a web é uma camada fina sobre o MapLibre GL JS, a biblioteca cartográfica de código aberto. Dá-lhe um mapa MapLibre com o estilo alojado, os mosaicos vetoriais e os tipos de letra do N-Ways, a menção do OpenStreetMap e a sua chave de API em cada pedido, bem como:

• um cliente para as API do N-Ways: geocodificação, códigos postais, preenchimento automático, lugares, percursos, matriz de percursos, tarifas de viagem e trânsito;
• uma caixa de pesquisa que sugere endereços, códigos postais e lugares enquanto se escreve;
• endereços de mapas estáticos para as imagens nos e-mails e nos recibos.

Tudo o que o MapLibre sabe fazer (marcadores, popups, camadas GeoJSON, movimentos de câmara, eventos) funciona no mapa que ele lhe dá.

Carregá-lo

Numa página web, sem mais nada

A versão autónoma inclui o MapLibre GL JS, por isso basta um único import:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="https://nways.ng/sdk/v1/maplibre-gl.css" />
    <style>body { margin: 0 } #map { height: 100vh }</style>
  </head>
  <body>
    <div id="map"></div>
    <script type="module">
      import { createMap } from 'https://nways.ng/sdk/v1/nways-maps.standalone.js'
      const map = createMap({ container: 'map', key: 'A_SUA_CHAVE_API', center: [7.4951, 9.0579], zoom: 12 })
    </script>
  </body>
</html>

Com npm e um bundler

Com Vite, webpack, Next.js e os outros bundlers, o MapLibre GL JS 6 e o pmtiles 4 são dependências pares (peer dependencies), para que a sua aplicação só guarde uma cópia de cada um:

npm install @nways/maps maplibre-gl@6 pmtiles@4

import 'maplibre-gl/dist/maplibre-gl.css'
import { createMap } from '@nways/maps'

const map = createMap({ container: 'map', key: import.meta.env.VITE_NWAYS_KEY, center: [3.3792, 6.5244], zoom: 12 })

Sem npm, importe https://nways.ng/sdk/v1/nways-maps.js (importa maplibre-gl e pmtiles pelo nome, para um import map ou um bundler), ou copie os seus quatro ficheiros (nways-maps.js, style.js, services.js, autocomplete.js) para o seu projeto. Os tipos estão ao lado (nways-maps.d.ts).

Criar um mapa

createMap(options) devolve um Map MapLibre. Aceita as opções de mapa do MapLibre e, além disso:

Cada createMap lê o estilo alojado uma vez: é um carregamento de mapa para a faturação. As deslocações e os zooms são gratuitos. Se o estilo alojado não estiver acessível (um problema de rede), o mapa passa sozinho para o estilo integrado.

Estilos alojados

O SDK usa https://nways.ng/maps/v1/styles/streets-light.json e streets-dark.json. Pode usá-los sem o SDK, em qualquer mapa MapLibre: styleUrl() dá o endereço com a sua chave.

import * as maplibregl from 'maplibre-gl'
import { Protocol } from 'pmtiles'
import { styleUrl, withKey } from '@nways/maps'

maplibregl.addProtocol('pmtiles', new Protocol().tile)
const key = 'A_SUA_CHAVE_API'
new maplibregl.Map({
  container: 'map',
  style: styleUrl({ key, theme: 'dark', lang: 'fr' }),
  // Os mosaicos e os tipos de letra também precisam da chave.
  transformRequest: (url) => ({ url: withKey(url, key) }),
  center: [1.2228, 6.1319],
  zoom: 12,
})

Mapas escuros e nomes em francês

import { createMap, setTheme } from '@nways/maps'

const map = createMap({ container: 'map', key: 'A_SUA_CHAVE_API', lang: 'fr', center: [2.4183, 6.3654], zoom: 12 })

// Seguir a definição clara ou escura do telemóvel.
const dark = matchMedia('(prefers-color-scheme: dark)')
const follow = () => setTheme(map, dark.matches ? 'dark' : 'light')
dark.addEventListener('change', follow)
follow()

Marcadores e popups

O SDK exporta o MapLibre com o nome maplibregl, por isso a versão autónoma não precisa de mais nenhum import:

import { createMap, maplibregl } from 'https://nways.ng/sdk/v1/nways-maps.standalone.js'

const map = createMap({ container: 'map', key: 'A_SUA_CHAVE_API', center: [3.3515, 6.6018], zoom: 15 })
new maplibregl.Marker({ color: '#0b7a3e' })
  .setLngLat([3.3515, 6.6018])
  .setPopup(new maplibregl.Popup().setText('Ponto de recolha: rotunda da Allen Avenue'))
  .addTo(map)

Chamar as API

createClient({ key }) devolve um objeto com um método por API. Os pontos podem escrever-se { lat, lng } ou [lng, lat]; as respostas são o JSON das API.

Os erros lançam um ApiError com status, reason e retryAfter. Erros

Um percurso no mapa

Os traçados dos percursos chegam em GeoJSON, prontos para uma camada de mapa:

import { createClient, createMap } from '@nways/maps'

const key = 'A_SUA_CHAVE_API'
const map = createMap({ container: 'map', key, center: [3.37, 6.53], zoom: 11 })
const nways = createClient({ key })

const { routes } = await nways.route({
  origin: { lat: 6.6018, lng: 3.3515 },
  destination: { lat: 6.4541, lng: 3.3947 },
  mode: 'okada',
})

map.on('load', () => {
  map.addSource('route', { type: 'geojson', data: { type: 'Feature', properties: {}, geometry: routes[0].geometry } })
  map.addLayer({ id: 'route', type: 'line', source: 'route', layout: { 'line-cap': 'round', 'line-join': 'round' }, paint: { 'line-color': '#1a73e8', 'line-width': 6 } })
})

Uma caixa de pesquisa

attachAutocomplete(input, options) transforma qualquer <input> numa caixa de pesquisa com as sugestões do N-Ways, navegação por teclado e etiquetas para os leitores de ecrã. Uma pesquisa, da primeira letra até à escolha, conta como uma sessão de preenchimento automático.

<label for="address">Endereço de entrega</label>
<input id="address" placeholder="Rua, código postal ou lugar" />
<script type="module">
  import { attachAutocomplete, createMap } from 'https://nways.ng/sdk/v1/nways-maps.standalone.js'

  const key = 'A_SUA_CHAVE_API'
  const map = createMap({ container: 'map', key })
  attachAutocomplete(document.getElementById('address'), {
    key,
    near: { lat: 6.5244, lng: 3.3792 },
    onSelect: (place) => map.flyTo({ center: place.location.coordinates, zoom: 17 }),
  })
</script>

Mude o seu aspeto com variáveis CSS na página: --nways-ac-bg, --nways-ac-fg, --nways-ac-border, --nways-ac-active, --nways-ac-muted.

O seu próprio estilo

buildStyle({ key, theme, lang }) devolve o estilo integrado do SDK como um objeto de estilo MapLibre simples. Mude as cores ou acrescente camadas antes de o passar diretamente ao MapLibre, ou comece do zero com a API de Mosaicos.

import { buildStyle, createMap } from '@nways/maps'

const style = buildStyle({ key: 'A_SUA_CHAVE_API' })
style.layers.find((l) => l.id === 'water').paint['fill-color'] = '#5aa9d6'
createMap({ container: 'map', key: 'A_SUA_CHAVE_API', style, center: [-0.187, 5.6037], zoom: 12 })

Atribuição

O canto do mapa mostra N-Ways · © OpenStreetMap contributors · Protomaps. Deixe-o visível: a licença do OpenStreetMap exige a menção em todo o lado onde os seus dados são mostrados. Pode torná-la compacta (o botão ⓘ do MapLibre), mas não a esconda nem a tape. Se passar o seu próprio estilo sem a menção, o SDK acrescenta-a. Regras de atribuição

Android e iOS

Para as aplicações nativas, use os SDK Maps para Android e iOS: os mesmos estilos alojados sobre o MapLibre Native, com a identidade da sua aplicação enviada para a restrição da respetiva chave.

Licenças

O @nways/maps é de código aberto sob a licença Apache 2.0 (Apache-2.0), Copyright 2026 N-WAYS LIMITED; o pacote inclui os ficheiros LICENSE e NOTICE. 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.

A versão autónoma inclui o MapLibre GL JS (BSD 3-Clause), o pmtiles (BSD 3-Clause) e o fflate (MIT); as respetivas licenças estão em LICENSES.txt, ao lado.