N-Ways
Documentação para programadoresGeocodificação

Está a desenvolver com o N-Ways?

Obter uma chave de API

Geocodificação

Encontre qualquer endereço, código postal ou lugar na Nigéria, no Gana, no Benim, no Togo, no Gabão, na Costa do Marfim, na Libéria, na Guiné, na Serra Leoa, na Guiné-Bissau, no Senegal, nos Camarões, no Burkina Faso, em Cabo Verde e na Gâmbia, ou diga o que se encontra num ponto do mapa.

Nesta página

O que encontra

A geocodificação compreende o que as pessoas escrevem, tal como o escrevem, na Nigéria, no Gana, no Benim, no Togo, no Gabão, na Costa do Marfim, na Libéria, na Guiné, na Serra Leoa, na Guiné-Bissau, no Senegal, nos Camarões, no Burkina Faso, em Cabo Verde e na Gâmbia:

  • Lugares e bairros: Osogbo, Oshogbo (um erro de escrita), Unilag (uma alcunha), Wuse 2.
  • Endereços e ruas: 12 Allen Avenue, Ikeja, Rue des Cheminots, Lomé.
  • Comércios e pontos de referência: Shoprite Ikeja, Kejetia station, gare de Dantokpa.
  • Códigos postais NIPOST (Nigéria), até ao edifício quando o N-Ways o conhece.
  • Códigos de casa N-Ways, o nome de um bairro ou aldeia e um número, em qualquer das suas formas (por país).
  • Endereços GhanaPost GPS como GA-183-8164, e Plus Codes como 6FR5J975+P4W.

Endereço base: https://nways.ng/maps/v1. Envie a sua chave no cabeçalho X-NWays-Api-Key, ou como key= numa página web. Cada resposta está descrita na referência.

Encontrar um lugar

GET /maps/v1/geocode

ParâmetroDescrição
qObrigatório. O que procurar, até 200 caracteres.
nearlat,lng: onde a pessoa está, ou o centro do mapa. Os resultados mais próximos aparecem primeiro, e as categorias (pharmacy, fuel) são procuradas à volta desse ponto.
countryApenas nestes países: NG, GH, BJ, TG, GA, CI, LR, GN, SL, GW, SN, CM, BF, CV, separados por vírgulas.
limitDe 1 a 20 resultados; 8 se não for indicado.
langen ou fr.
fieldsApenas estes campos de cada resultado, separados por vírgulas: name,location. Respostas mais leves em redes lentas.
cURL
curl "https://nways.ng/maps/v1/geocode?q=Ikeja+City+Mall&near=6.5244,3.3792&limit=3" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"
JavaScript
import { createClient } from '@nways/maps'

const nways = createClient({ key: process.env.NWAYS_API_KEY })
const { results } = await nways.geocode('Ikeja City Mall', { near: { lat: 6.5244, lng: 3.3792 }, limit: 3 })
const [lng, lat] = results[0].location.coordinates
Python
import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/geocode",
    params={"q": "Ikeja City Mall", "near": "6.5244,3.3792", "limit": 3},
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
results = res.json()["results"]
200 OK
{
  "results": [
    {
      "id": "osm:w568367632",
      "name": "Ikeja City Mall",
      "type": "landmark",
      "category": "shopping",
      "location": { "type": "Point", "coordinates": [3.357831, 6.61437] },
      "formattedAddress": "Ikeja, Lagos",
      "plusCode": "6FR5J975+P4W",
      "country": "NG",
      "attribution": "© OpenStreetMap contributors, N-Ways"
    }
  ],
  "attribution": "© OpenStreetMap contributors, N-Ways"
}

Campos de um resultado

CampoDescrição
idO identificador do resultado. Estável: pode guardá-lo e procurar o lugar de novo.
nameO seu nome, ou o endereço ou o código tal como foi escrito.
typeO que é: country, state, city, town, suburb, street, address, landmark, business, building, postcode…
categoryPara um comércio ou um ponto de referência: pharmacy, petrol, bank… (as categorias de Lugares).
locationUm ponto GeoJSON: coordinates é [longitude, latitude].
formattedAddressOnde fica, para distinguir os lugares: Ikeja, Lagos.
postcode, ghanaPost, plusCodeO seu código postal NIPOST, o seu endereço GhanaPost GPS e o seu Plus Code, quando se aplicam. Cada resultado tem um Plus Code.
countryNG, GH, BJ, TG, GA, CI, LR, GN, SL, GW, SN, CM, BF ou CV.
bboxPara as zonas: [west, south, east, north], para ajustar o mapa a elas.
distanceMA partir de near, em linha reta.
estimated, accuracyMO ponto é uma estimativa (um código postal colocado a partir dos códigos vizinhos), com uma precisão de cerca de accuracyM metros.
placeIdPara um comércio: o seu identificador para os detalhes do lugar.
attributionA menção a mostrar com este resultado.

Os campos sem nada a dizer são omitidos, e podem ser acrescentados novos campos: ignore os que não conhece. Quando nada corresponde mas existe algo parecido, a resposta contém didYouMean.

O que está aqui (geocodificação inversa)

GET /maps/v1/reverse?lat=…&lng=… responde com a mesma forma nos quinze países: o country e a region (com os nomes em francês), o plusCode do ponto, um formattedAddress numa linha, na Nigéria o postcode NIPOST do edifício ao alcance, no Gana o endereço ghanaPost conhecido mais próximo, e o endereço, a rua ou o ponto de referência com nome mais próximo (nearest) num raio de radius metros (200 por omissão, de 10 a 1 000).

cURL
curl "https://nways.ng/maps/v1/reverse?lat=6.4474&lng=3.4720" -H "X-NWays-Api-Key: A_SUA_CHAVE_API"
200 OK (abreviado)
{
  "location": { "type": "Point", "coordinates": [3.472, 6.4474] },
  "plusCode": "6FR5CFWC+XR6",
  "country": { "code": "NG", "name": "Nigeria", "nameFr": "Nigéria" },
  "region": { "code": "NG-LA", "name": "Lagos State", "nameFr": "État de Lagos" },
  "formattedAddress": "12 Admiralty Way, Lekki, Lagos State, Nigeria",
  "postcode": { "code": "LA08A09DB09", "display": "LA 08 A09 DB 09", "entrances": ["…"] },
  "ghanaPost": null,
  "nearest": { "name": "…", "type": "landmark", "distanceM": 6 }
}

Códigos postais NIPOST

Os códigos postais de edifício da Nigéria designam um edifício, não apenas uma zona. GET /maps/v1/postcodes/{code} aceita todas as formas de o escrever (LA 08 A09 DB 09, la-08-a09-db-09):

cURL
curl "https://nways.ng/maps/v1/postcodes/LA08A09DB09" -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

A resposta dá a location do edifício, o seu address quando é conhecido, a forma de apresentação do código (display) e os seus components (estado, LGA, distrito, zona, edifício, com os nomes do estado e da LGA), bem como as suas entrances: os portões e as portas que as pessoas usam de facto, as verified primeiro. Leve o percurso até à primeira entrada, não ao meio do edifício; ou dê { "postcode": "…" } aos Percursos, que o fazem por si. Um código válido que o N-Ways ainda não colocou volta como estimated, a partir dos códigos vizinhos, com accuracyM.

POST /maps/v1/postcodes/batch procura até 100 códigos de uma vez (cada um conta como uma chamada), para limpar uma lista de clientes.

Endereços GhanaPost GPS e Plus Codes

cURL
curl "https://nways.ng/maps/v1/ghanapost/GA-183-8164" -H "X-NWays-Api-Key: A_SUA_CHAVE_API"
curl "https://nways.ng/maps/v1/pluscodes/6FR5J975+P4W" -H "X-NWays-Api-Key: A_SUA_CHAVE_API"

Um endereço GhanaPost GPS vem do OpenStreetMap ou do seu proprietário, ou, nos distritos onde isso foi verificado, é estimado a partir dos códigos cartografados à volta (estimated). O N-Ways nunca chama a Ghana Post. Um endereço que não consegue colocar responde 404 GHANAPOST_UNKNOWN: peça antes um ponto de referência ou um Plus Code.

Os Plus Codes funcionam em todo o lado, mesmo onde não há endereço. Um código curto precisa de uma referência: near=lat,lng, ou uma cidade a seguir (J975+P4 Ikeja).

Códigos de casa

Cada lote destes 12 países tem um código de casa N-Ways: o nome do seu bairro ou aldeia e um número curto, como os que se seguem. A chamada de geocodificação aceita-os tal como se escrevem, e o guia de cada país cobre a consulta, o código de um ponto e a descodificação offline. Os códigos, o motor e um servidor pronto a usar estão abertos no GitHub, por isso também os pode alojar você mesmo.

Ver também

Os endereços antigos

Para os parceiros que começaram com https://nways.ng/v1/geocode, /v1/reverse, /v1/postcodes e /v1/ghanapost: esses endereços continuam a funcionar durante pelo menos 12 meses, mas as suas respostas podem mudar com a aplicação N-Ways. Passe para /maps/v1, cujas respostas apenas ganham campos. Registo de alterações