Primeiros passos

1. Obter uma chave

Uma chave de API diz ao N-Ways de que projeto vem um pedido, para aplicar as restrições e as quotas desse projeto e contar a sua utilização. As chaves pertencem a um projeto: um por aplicação ou por cliente é um bom começo, para que a utilização e os limites de cada um fiquem separados.

As chaves criam-se na consola de parceiros N-Ways. Registe-se com Google, Apple ou e-mail e obtenha a sua chave num minuto. Utilização gratuita todos os meses.

1. Inicie sessão com a sua conta Google ou Apple ou um e-mail profissional.
2. Indique o nome da sua empresa. É a única pergunta: a sua organização, um primeiro projeto e uma chave são criados de imediato, e funcionam logo.
3. Copie a chave: a consola só a mostra uma vez. Trate-a como uma palavra-passe. O mesmo ecrã dá os três passos para a integrar num site, numa aplicação Android ou iOS, ou no seu servidor.

Cada API tem chamadas gratuitas todos os meses. Para além delas, adicione crédito em Faturação (PalmPay: pagamento online, ou transferência para o número de conta próprio da sua organização) e pague só o que usa; sem crédito, as chamadas para além das gratuitas recebem um 402 BILLING_DISABLED até voltar a adicionar. Mais projetos, mais chaves e as API permitidas a cada uma gerem-se em Projetos e chaves.

2. Restringi-la

Uma chave numa página web ou numa aplicação pode ser lida por qualquer pessoa. As restrições tornam uma chave copiada inútil noutro lado. Dê a cada chave um só tipo de restrição de aplicação e apenas as API de que precisa:

Depois, limite a chave às API que a aplicação chama: uma página web que só mostra um mapa precisa de Mapas, não de Percursos. Mais sobre as restrições

3. Mostrar um mapa

Cole isto num ficheiro HTML e abra-o. Carrega o SDK Maps do N-Ways (MapLibre GL JS incluído) e mostra Lagos.

<link rel="stylesheet" href="https://nways.ng/sdk/v1/maplibre-gl.css" />
<div id="map" style="height: 480px"></div>
<script type="module">
  import { createMap } from 'https://nways.ng/sdk/v1/nways-maps.standalone.js'
  createMap({ container: 'map', key: 'A_SUA_CHAVE_API', center: [3.3792, 6.5244], zoom: 12 })
</script>

As coordenadas escrevem-se primeiro a longitude e depois a latitude, como em GeoJSON: [3.3792, 6.5244] é o centro de Lagos (Yaba). O guia do SDK Maps explica os mapas escuros, os nomes em francês, os marcadores e o traçado de um percurso.

4. Encontrar um lugar

A geocodificação aceita o que as pessoas escrevem, incluindo os códigos postais NIPOST e os endereços GhanaPost GPS:

curl "https://nways.ng/maps/v1/geocode?q=GA-183-8164" -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

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

const nways = createClient({ key: 'A_SUA_CHAVE_API' })
const { results } = await nways.geocode('Allen Avenue, Ikeja', { near: { lat: 6.6, lng: 3.35 } })
console.log(results[0].name, results[0].location.coordinates) // [lng, lat]

5. Obter um percurso

Peça um percurso entre dois pontos (ou até um código postal NIPOST) e indique como se desloca:

curl -X POST "https://nways.ng/maps/v1/routes/compute" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API" -H "Content-Type: application/json" \
  -d '{"origin": {"lat": 6.6018, "lng": 3.3515}, "destination": {"lat": 6.4541, "lng": 3.3947}, "mode": "okada"}'

const { routes } = await nways.route({
  origin: { lat: 6.6018, lng: 3.3515 },
  destination: { lat: 6.4541, lng: 3.3947 },
  mode: 'okada',
})
console.log(Math.round(routes[0].durationS / 60), 'min,', (routes[0].distanceM / 1000).toFixed(1), 'km')

O guia de percursos explica os kekes, os danfos, os barcos, as portagens, as paragens intermédias e as tarifas.

A seguir