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

Geocodificação

Pesquisa de locais e endereços, o que está num ponto e consultas NIPOST, GhanaPost e Plus Code.

Nesta página
Nota:

Envie a sua chave com key=A_SUA_CHAVE_API no endereço, ou no cabeçalho X-NWays-Api-Key. Chaves de API

Endereço base: https://nways.ng/maps/v1

Pesquisar locais, endereços e códigos

GET https://nways.ng/maps/v1/geocode

Locais, ruas, endereços, pontos de referência, negócios e zonas em todos os países cobertos, com erros de escrita e alcunhas locais; um código postal NIPOST encontra o seu edifício, um endereço GhanaPost GPS o seu ponto. Resultados mais próximos primeiro quando near é indicado. Motivos: QUERY_REQUIRED, QUERY_TOO_LONG, NEAR_INVALID, COUNTRY_INVALID, LIMIT_INVALID, LANG_INVALID.

Parâmetros

NomeOndeTipoDescrição
qconsultastringObrigatório. Até 200 caracteres.
nearconsultastringlat,lng: ordenar e escolher resultados perto deste ponto.
countryconsultastringLista separada por vírgulas de NG, GH, BJ, TG, GA, CI, LR, GN, SL, GW, SN, CM, BF, CV, GM.
limitconsultaintegerPredefinição: 8. ≥ 1, ≤ 20.
langconsultastringUm de: en, fr, pt. Predefinição: en.
fieldsconsultastringLista separada por vírgulas dos campos a manter em cada resultado (a.b entra em objetos; id é sempre mantido; * = todos).
cURL
curl "https://nways.ng/maps/v1/geocode?q=Ikeja+City+Mall" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"
JavaScript
const res = await fetch('https://nways.ng/maps/v1/geocode?q=Ikeja+City+Mall', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()
Python
import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/geocode?q=Ikeja+City+Mall",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

Resultados

CampoTipoDescrição
resultsResult[]Obrigatório.
results[].idstringObrigatório.
results[].namestringObrigatório.
results[].typestringObrigatório. address, street, business, landmark, building, postcode, ghanapost, ou uma zona: neighbourhood, suburb, village, town, city, state…
results[].categorystring
results[].locationPointObrigatório.
results[].location.typestringObrigatório.
results[].location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
results[].bboxnumber[]oeste, sul, este, norte (zonas) Pelo menos 4 elementos, no máximo 4 elementos.
results[].formattedAddressstring
results[].postcodestringCódigo postal NIPOST, compacto
results[].ghanaPoststring
results[].plusCodestringObrigatório.
results[].countrystring
results[].distanceMnumberA partir de near (ou do ponto consultado).
results[].estimatedbooleanO ponto é uma estimativa, dentro de accuracyM.
results[].accuracyMnumber
results[].placeIdstringUm negócio: o seu id para /places/{id}.
results[].attributionstring
didYouMeanstring
attributionstringObrigatório.
200 OK
{
  "results": [
    {
      "id": "osm:w568367632",
      "name": "Ikeja City Mall",
      "type": "landmark",
      "category": "shopping",
      "location": {
        "type": "string",
        "coordinates": [
          0
        ]
      },
      "bbox": [
        0
      ],
      "formattedAddress": "Ikeja, Lagos",
      "postcode": "LA08A09DB09",
      "ghanaPost": "GA-183-8164",
      "plusCode": "6FR5J975+P4W",
      "country": "NG",
      "distanceM": 0,
      "estimated": true,
      "accuracyM": 0,
      "placeId": "string",
      "attribution": "string"
    }
  ],
  "didYouMean": "string",
  "attribution": "string"
}

Erros

  • default Erro

O que está num ponto

GET https://nways.ng/maps/v1/reverse

Uma só forma em todos os países cobertos: o país e a região, o Plus Code, o código postal NIPOST da Nigéria (o edifício ao alcance), o endereço GhanaPost GPS conhecido mais próximo no Gana e o endereço, rua ou ponto de referência com nome mais próximo (senão a zona), com um endereço numa linha. Motivos: LAT_LNG_REQUIRED, RADIUS_INVALID, LANG_INVALID.

Parâmetros

NomeOndeTipoDescrição
latconsultanumberObrigatório.
lngconsultanumberObrigatório.
radiusconsultanumberAté onde procurar um endereço, rua ou ponto de referência (metros). Predefinição: 200. ≥ 10, ≤ 1000.
langconsultastringUm de: en, fr, pt. Predefinição: en.
fieldsconsultastringLista separada por vírgulas dos campos a manter em cada resultado (a.b entra em objetos; id é sempre mantido; * = todos).
cURL
curl "https://nways.ng/maps/v1/reverse?lat=6.4474&lng=3.472" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"
JavaScript
const res = await fetch('https://nways.ng/maps/v1/reverse?lat=6.4474&lng=3.472', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()
Python
import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/reverse?lat=6.4474&lng=3.472",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

O que lá está

CampoTipoDescrição
locationPointObrigatório.
location.typestringObrigatório.
location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
plusCodestringObrigatório.
countryArea | nullObrigatório.
regionArea | nullObrigatório.
formattedAddressstring
postcodePostcode | nullObrigatório. Nigéria: o código postal NIPOST do edifício, quando há um ao alcance.
ghanaPoststring | nullObrigatório. Gana: o endereço GhanaPost GPS conhecido mais próximo (a menos de 100 m).
nearestResult | nullObrigatório.
attributionstringObrigatório.
200 OK
{
  "location": {
    "type": "string",
    "coordinates": [
      0
    ]
  },
  "plusCode": "string",
  "country": {
    "code": "NG-LA",
    "name": "Lagos State",
    "nameFr": "string",
    "namePt": "string"
  },
  "region": {
    "code": "NG-LA",
    "name": "Lagos State",
    "nameFr": "string",
    "namePt": "string"
  },
  "formattedAddress": "12 Admiralty Way, Lekki, Lagos State, Nigeria",
  "postcode": {
    "code": "LA08A09DB09",
    "display": "LA 08 A09 DB 09",
    "components": {
      "state": "LA",
      "stateName": "Lagos",
      "lga": "08",
      "lgaName": "Eti-Osa",
      "district": "A09",
      "area": "DB",
      "building": "09"
    },
    "location": {
      "type": "string",
      "coordinates": [
        0
      ]
    },
    "name": "string",
    "address": "string",
    "buildingType": "string",
    "entrances": [
      {
        "location": {
          "type": "string",
          "coordinates": []
        },
        "kind": "main",
        "verified": true
      }
    ],
    "plusCode": "string",
    "country": "string",
    "source": "nipost",
    "estimated": true,
    "accuracyM": 0,
    "distanceM": 0,
    "attribution": "string"
  },
  "ghanaPost": "string",
  "nearest": {
    "id": "osm:w568367632",
    "name": "Ikeja City Mall",
    "type": "landmark",
    "category": "shopping",
    "location": {
      "type": "string",
      "coordinates": [
        0
      ]
    },
    "bbox": [
      0
    ],
    "formattedAddress": "Ikeja, Lagos",
    "postcode": "LA08A09DB09",
    "ghanaPost": "GA-183-8164",
    "plusCode": "6FR5J975+P4W",
    "country": "NG",
    "distanceM": 0,
    "estimated": true,
    "accuracyM": 0,
    "placeId": "string",
    "attribution": "string"
  },
  "attribution": "string"
}

Erros

  • default Erro

Um código postal NIPOST

GET https://nways.ng/maps/v1/postcodes/{code}

O edifício que um código postal NIPOST designa (qualquer forma escrita: LA 08 A09 DB 09, la-08-a09-db-09), as suas entradas (percurso para a primeira), as suas partes e os respetivos nomes; ou, para um código que ainda não localizámos, onde se estima que esteja a partir dos códigos à volta (estimated, accuracyM). Motivos: POSTCODE_INVALID, POSTCODE_NOT_FOUND_CHECK, POSTCODE_NOT_NIPOST.

Parâmetros

NomeOndeTipoDescrição
codecaminhostringObrigatório.
fieldsconsultastringLista separada por vírgulas dos campos a manter em cada resultado (a.b entra em objetos; id é sempre mantido; * = todos).
cURL
curl "https://nways.ng/maps/v1/postcodes/LA08A09DB09" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"
JavaScript
const res = await fetch('https://nways.ng/maps/v1/postcodes/LA08A09DB09', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()
Python
import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/postcodes/LA08A09DB09",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

O código postal

CampoTipoDescrição
codestringObrigatório.
displaystringObrigatório.
componentsPostcodeComponentsObrigatório.
components.statestringObrigatório.
components.stateNamestring
components.lgastringObrigatório.
components.lgaNamestring
components.districtstringObrigatório.
components.areastringObrigatório.
components.buildingstringObrigatório.
locationPointObrigatório.
location.typestringObrigatório.
location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
namestring
addressstring
buildingTypestring
entrancesEntrance[]Obrigatório. Verificadas primeiro, a principal primeiro: percurso para a primeira.
entrances[].locationPointObrigatório.
entrances[].location.typestringObrigatório.
entrances[].location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
entrances[].kindstringObrigatório. Um de: main, gate, pedestrian, service.
entrances[].verifiedbooleanObrigatório.
plusCodestringObrigatório.
countrystringObrigatório.
sourcestringObrigatório. Um de: nipost, osm, user, estimate.
estimatedbooleanObrigatório.
accuracyMnumber
distanceMnumberGeocodificação inversa: a partir do ponto consultado.
attributionstringObrigatório.
200 OK
{
  "code": "LA08A09DB09",
  "display": "LA 08 A09 DB 09",
  "components": {
    "state": "LA",
    "stateName": "Lagos",
    "lga": "08",
    "lgaName": "Eti-Osa",
    "district": "A09",
    "area": "DB",
    "building": "09"
  },
  "location": {
    "type": "string",
    "coordinates": [
      0
    ]
  },
  "name": "string",
  "address": "string",
  "buildingType": "string",
  "entrances": [
    {
      "location": {
        "type": "string",
        "coordinates": [
          0
        ]
      },
      "kind": "main",
      "verified": true
    }
  ],
  "plusCode": "string",
  "country": "string",
  "source": "nipost",
  "estimated": true,
  "accuracyM": 0,
  "distanceM": 0,
  "attribution": "string"
}

Erros

  • default Erro

Até 100 códigos postais NIPOST de uma vez

POST https://nways.ng/maps/v1/postcodes/batch

Cada código conta como uma chamada de geocodificação. Uma resposta por código, por ordem, com o seu próprio erro quando o tem. Motivos (chamada inteira) CODES_INVALID.

Parâmetros

NomeOndeTipoDescrição
fieldsconsultastringLista separada por vírgulas dos campos a manter em cada resultado (a.b entra em objetos; id é sempre mantido; * = todos).

Corpo do pedido

CampoTipoDescrição
codesstring[]Obrigatório. Pelo menos 1 elementos, no máximo 100 elementos.
cURL
curl -X POST "https://nways.ng/maps/v1/postcodes/batch" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"codes":["LA08A09DB09","FC 02 A09 DB 09"]}'
JavaScript
const res = await fetch('https://nways.ng/maps/v1/postcodes/batch', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "codes": [
      "LA08A09DB09",
      "FC 02 A09 DB 09"
    ]
  }),
})
const data = await res.json()
Python
import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/postcodes/batch",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"codes": ["LA08A09DB09", "FC 02 A09 DB 09"]},
    timeout=10,
)
data = res.json()

Resposta

Um resultado por código

CampoTipoDescrição
resultsobject[]Obrigatório.
results[].querystringObrigatório.
results[].postcodePostcode
results[].postcode.codestringObrigatório.
results[].postcode.displaystringObrigatório.
results[].postcode.componentsPostcodeComponentsObrigatório.
results[].postcode.components.statestringObrigatório.
results[].postcode.components.stateNamestring
results[].postcode.components.lgastringObrigatório.
results[].postcode.components.lgaNamestring
results[].postcode.components.districtstringObrigatório.
results[].postcode.components.areastringObrigatório.
results[].postcode.components.buildingstringObrigatório.
results[].postcode.locationPointObrigatório.
results[].postcode.location.typestringObrigatório.
results[].postcode.location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
results[].postcode.namestring
results[].postcode.addressstring
results[].postcode.buildingTypestring
results[].postcode.entrancesEntrance[]Obrigatório. Verificadas primeiro, a principal primeiro: percurso para a primeira.
results[].postcode.entrances[].locationPointObrigatório.
results[].postcode.entrances[].kindstringObrigatório. Um de: main, gate, pedestrian, service.
results[].postcode.entrances[].verifiedbooleanObrigatório.
results[].postcode.plusCodestringObrigatório.
results[].postcode.countrystringObrigatório.
results[].postcode.sourcestringObrigatório. Um de: nipost, osm, user, estimate.
results[].postcode.estimatedbooleanObrigatório.
results[].postcode.accuracyMnumber
results[].postcode.distanceMnumberGeocodificação inversa: a partir do ponto consultado.
results[].postcode.attributionstringObrigatório.
results[].errorItemError
results[].error.codeintegerObrigatório.
results[].error.reasonstringObrigatório.
results[].error.messagestringObrigatório.
attributionstringObrigatório.
200 OK
{
  "results": [
    {
      "query": "string",
      "postcode": {
        "code": "LA08A09DB09",
        "display": "LA 08 A09 DB 09",
        "components": {
          "state": "LA",
          "stateName": "Lagos",
          "lga": "08",
          "lgaName": "Eti-Osa",
          "district": "A09",
          "area": "DB",
          "building": "09"
        },
        "location": {
          "type": "string",
          "coordinates": []
        },
        "name": "string",
        "address": "string",
        "buildingType": "string",
        "entrances": [
          {}
        ],
        "plusCode": "string",
        "country": "string",
        "source": "nipost",
        "estimated": true,
        "accuracyM": 0,
        "distanceM": 0,
        "attribution": "string"
      },
      "error": {
        "code": 0,
        "reason": "string",
        "message": "string"
      }
    }
  ],
  "attribution": "string"
}

Erros

  • default Erro

Um endereço GhanaPost GPS

GET https://nways.ng/maps/v1/ghanapost/{code}

Onde fica um endereço digital GhanaPost GPS: mapeado no OpenStreetMap ou publicado pelo seu dono, senão (nos distritos onde o método foi verificado) estimado a partir dos códigos mapeados à volta (estimated, accuracyM). Nunca chama a Ghana Post. Motivos: GHANAPOST_INVALID, GHANAPOST_UNKNOWN.

Parâmetros

NomeOndeTipoDescrição
codecaminhostringObrigatório.
fieldsconsultastringLista separada por vírgulas dos campos a manter em cada resultado (a.b entra em objetos; id é sempre mantido; * = todos).
cURL
curl "https://nways.ng/maps/v1/ghanapost/GA-183-8164" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"
JavaScript
const res = await fetch('https://nways.ng/maps/v1/ghanapost/GA-183-8164', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()
Python
import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/ghanapost/GA-183-8164",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

O endereço

CampoTipoDescrição
idstringObrigatório.
namestringObrigatório.
typestringObrigatório. address, street, business, landmark, building, postcode, ghanapost, ou uma zona: neighbourhood, suburb, village, town, city, state…
categorystring
locationPointObrigatório.
location.typestringObrigatório.
location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
bboxnumber[]oeste, sul, este, norte (zonas) Pelo menos 4 elementos, no máximo 4 elementos.
formattedAddressstring
postcodestringCódigo postal NIPOST, compacto
ghanaPoststring
plusCodestringObrigatório.
countrystring
distanceMnumberA partir de near (ou do ponto consultado).
estimatedbooleanO ponto é uma estimativa, dentro de accuracyM.
accuracyMnumber
placeIdstringUm negócio: o seu id para /places/{id}.
attributionstring
200 OK
{
  "id": "osm:w568367632",
  "name": "Ikeja City Mall",
  "type": "landmark",
  "category": "shopping",
  "location": {
    "type": "string",
    "coordinates": [
      0
    ]
  },
  "bbox": [
    0
  ],
  "formattedAddress": "Ikeja, Lagos",
  "postcode": "LA08A09DB09",
  "ghanaPost": "GA-183-8164",
  "plusCode": "6FR5J975+P4W",
  "country": "NG",
  "distanceM": 0,
  "estimated": true,
  "accuracyM": 0,
  "placeId": "string",
  "attribution": "string"
}

Erros

  • default Erro

A área de um Plus Code e o que lá está

GET https://nways.ng/maps/v1/pluscodes/{code}

Um Plus Code completo (6FR5J975+P4W), ou um curto com uma referência: near=lat,lng, ou uma localidade a seguir (J975+P4 Ikeja, codificado para URL). A resposta é a geocodificação inversa do centro do código, com o código completo e os seus limites. Motivos: PLUSCODE_INVALID, PLUSCODE_SHORT, LOCALITY_NOT_FOUND, NEAR_INVALID.

Parâmetros

NomeOndeTipoDescrição
codecaminhostringObrigatório.
nearconsultastringlat,lng: ordenar e escolher resultados perto deste ponto.
langconsultastringUm de: en, fr, pt. Predefinição: en.
fieldsconsultastringLista separada por vírgulas dos campos a manter em cada resultado (a.b entra em objetos; id é sempre mantido; * = todos).
cURL
curl "https://nways.ng/maps/v1/pluscodes/6FR5J975%2BP4W" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"
JavaScript
const res = await fetch('https://nways.ng/maps/v1/pluscodes/6FR5J975%2BP4W', {
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY },
})
const data = await res.json()
Python
import os
import requests

res = requests.get(
    "https://nways.ng/maps/v1/pluscodes/6FR5J975%2BP4W",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

A área do código

CampoTipoDescrição
locationPointObrigatório.
location.typestringObrigatório.
location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
plusCodestringObrigatório.
countryArea | nullObrigatório.
regionArea | nullObrigatório.
formattedAddressstring
postcodePostcode | nullObrigatório. Nigéria: o código postal NIPOST do edifício, quando há um ao alcance.
ghanaPoststring | nullObrigatório. Gana: o endereço GhanaPost GPS conhecido mais próximo (a menos de 100 m).
nearestResult | nullObrigatório.
attributionstringObrigatório.
boundsnumber[]Obrigatório. oeste, sul, este, norte Pelo menos 4 elementos, no máximo 4 elementos.
200 OK
{
  "location": {
    "type": "string",
    "coordinates": [
      0
    ]
  },
  "plusCode": "string",
  "country": {
    "code": "NG-LA",
    "name": "Lagos State",
    "nameFr": "string",
    "namePt": "string"
  },
  "region": {
    "code": "NG-LA",
    "name": "Lagos State",
    "nameFr": "string",
    "namePt": "string"
  },
  "formattedAddress": "12 Admiralty Way, Lekki, Lagos State, Nigeria",
  "postcode": {
    "code": "LA08A09DB09",
    "display": "LA 08 A09 DB 09",
    "components": {
      "state": "LA",
      "stateName": "Lagos",
      "lga": "08",
      "lgaName": "Eti-Osa",
      "district": "A09",
      "area": "DB",
      "building": "09"
    },
    "location": {
      "type": "string",
      "coordinates": [
        0
      ]
    },
    "name": "string",
    "address": "string",
    "buildingType": "string",
    "entrances": [
      {
        "location": {
          "type": "string",
          "coordinates": []
        },
        "kind": "main",
        "verified": true
      }
    ],
    "plusCode": "string",
    "country": "string",
    "source": "nipost",
    "estimated": true,
    "accuracyM": 0,
    "distanceM": 0,
    "attribution": "string"
  },
  "ghanaPost": "string",
  "nearest": {
    "id": "osm:w568367632",
    "name": "Ikeja City Mall",
    "type": "landmark",
    "category": "shopping",
    "location": {
      "type": "string",
      "coordinates": [
        0
      ]
    },
    "bbox": [
      0
    ],
    "formattedAddress": "Ikeja, Lagos",
    "postcode": "LA08A09DB09",
    "ghanaPost": "GA-183-8164",
    "plusCode": "6FR5J975+P4W",
    "country": "NG",
    "distanceM": 0,
    "estimated": true,
    "accuracyM": 0,
    "placeId": "string",
    "attribution": "string"
  },
  "attribution": "string",
  "bounds": [
    0
  ]
}

Erros

  • default Erro