N-Ways
Documentação para programadoresCodes

Está a desenvolver com o N-Ways?

Obter uma chave de API

Codes

Códigos postais NIPOST, endereços GhanaPost GPS, Plus Codes e códigos de casa N-Ways, numa só consulta.

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

Qualquer código que as pessoas escrevem como endereço

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

Um código postal NIPOST (LA 08 A09 DB 09, em qualquer forma escrita), um endereço GhanaPost GPS (GA-183-8164), um Plus Code (6FR5J975+P4W, ou um curto com near= ou uma localidade a seguir: J975+P4 Ikeja) ou um código de casa N-Ways (o nome de um local e um número, Fréau-Jardin 10 58, em todos os países onde a N-Ways os emite), codificado para URL. O tipo é detetado (type= impõe um); a resposta indica o tipo, onde fica, um endereço numa linha e o detalhe próprio do tipo (postcode, ghanaPost, plusCode ou homeCode). Um texto que não é nenhum tipo de código responde CODE_UNRECOGNISED e não é contado. Para códigos de casa, country= e near= escolhem entre os países onde existem o mesmo nome e número. Motivos: CODE_REQUIRED, CODE_UNRECOGNISED, TYPE_INVALID, NEAR_INVALID, COUNTRY_INVALID, LANG_INVALID, POSTCODE_INVALID, POSTCODE_NOT_FOUND_CHECK, POSTCODE_NOT_NIPOST, GHANAPOST_INVALID, GHANAPOST_UNKNOWN, PLUSCODE_INVALID, PLUSCODE_SHORT, LOCALITY_NOT_FOUND, HOMECODE_UNKNOWN, HOMECODE_FORMAT (apenas type=homecode), HOMECODE_OUTSIDE.

Parâmetros

NomeOndeTipoDescrição
codecaminhostringObrigatório. Até 120 caracteres.
typeconsultastringImpõe um tipo (por omissão: detetado). Um de: postcode, ghanapost, pluscode, homecode.
nearconsultastringlat,lng: ordenar e escolher resultados perto deste ponto.
countryconsultastringCódigos de casa: o país onde procurar.
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/codes/LA%2008%20A09%20DB%2009" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API"
JavaScript
const res = await fetch('https://nways.ng/maps/v1/codes/LA%2008%20A09%20DB%2009', {
  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/codes/LA%2008%20A09%20DB%2009",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    timeout=10,
)
data = res.json()

Resposta

O código

CampoTipoDescrição
querystringObrigatório.
typestringObrigatório. Um de: postcode, ghanapost, pluscode, homecode.
codestringObrigatório. Tal como está escrito: LA 08 A09 DB 09, GA-183-8164, 6FR5J975+P4W, Fréau-Jardin 10 58.
locationPointObrigatório.
location.typestringObrigatório.
location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
countrystring
formattedAddressstring
estimatedboolean
accuracyMnumber
postcodePostcode
postcode.codestringObrigatório.
postcode.displaystringObrigatório.
postcode.componentsPostcodeComponentsObrigatório.
postcode.components.statestringObrigatório.
postcode.components.stateNamestring
postcode.components.lgastringObrigatório.
postcode.components.lgaNamestring
postcode.components.districtstringObrigatório.
postcode.components.areastringObrigatório.
postcode.components.buildingstringObrigatório.
postcode.locationPointObrigatório.
postcode.location.typestringObrigatório.
postcode.location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
postcode.namestring
postcode.addressstring
postcode.buildingTypestring
postcode.entrancesEntrance[]Obrigatório. Verificadas primeiro, a principal primeiro: percurso para a primeira.
postcode.entrances[].locationPointObrigatório.
postcode.entrances[].location.typestringObrigatório.
postcode.entrances[].location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
postcode.entrances[].kindstringObrigatório. Um de: main, gate, pedestrian, service.
postcode.entrances[].verifiedbooleanObrigatório.
postcode.plusCodestringObrigatório.
postcode.countrystringObrigatório.
postcode.sourcestringObrigatório. Um de: nipost, osm, user, estimate.
postcode.estimatedbooleanObrigatório.
postcode.accuracyMnumber
postcode.distanceMnumberGeocodificação inversa: a partir do ponto consultado.
postcode.attributionstringObrigatório.
ghanaPostResult
ghanaPost.idstringObrigatório.
ghanaPost.namestringObrigatório.
ghanaPost.typestringObrigatório. address, street, business, landmark, building, postcode, ghanapost, ou uma zona: neighbourhood, suburb, village, town, city, state…
ghanaPost.categorystring
ghanaPost.locationPointObrigatório.
ghanaPost.location.typestringObrigatório.
ghanaPost.location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
ghanaPost.bboxnumber[]oeste, sul, este, norte (zonas) Pelo menos 4 elementos, no máximo 4 elementos.
ghanaPost.formattedAddressstring
ghanaPost.postcodestringCódigo postal NIPOST, compacto
ghanaPost.ghanaPoststring
ghanaPost.plusCodestringObrigatório.
ghanaPost.countrystring
ghanaPost.distanceMnumberA partir de near (ou do ponto consultado).
ghanaPost.estimatedbooleanO ponto é uma estimativa, dentro de accuracyM.
ghanaPost.accuracyMnumber
ghanaPost.placeIdstringUm negócio: o seu id para /places/{id}.
ghanaPost.attributionstring
plusCodePlusCodeResponse
plusCode.locationPointObrigatório.
plusCode.location.typestringObrigatório.
plusCode.location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
plusCode.plusCodestringObrigatório.
plusCode.countryArea | nullObrigatório.
plusCode.regionArea | nullObrigatório.
plusCode.formattedAddressstring
plusCode.postcodePostcode | nullObrigatório. Nigéria: o código postal NIPOST do edifício, quando há um ao alcance.
plusCode.ghanaPoststring | nullObrigatório. Gana: o endereço GhanaPost GPS conhecido mais próximo (a menos de 100 m).
plusCode.nearestResult | nullObrigatório.
plusCode.attributionstringObrigatório.
plusCode.boundsnumber[]Obrigatório. oeste, sul, este, norte Pelo menos 4 elementos, no máximo 4 elementos.
homeCodeHomeCodeUm código de casa N-Ways: o endereço de um edifício em forma de nome e número. As pessoas escrevem code; machine traz o dígito de controlo para os sistemas.
homeCode.codestringObrigatório.
homeCode.machinestringObrigatório. Com o dígito de controlo (apenas sistemas; nunca mostrado às pessoas).
homeCode.countrystringObrigatório.
homeCode.namestringObrigatório.
homeCode.officialNamestring
homeCode.coveragestringOnde existe um endereço oficial (officialAddress primeiro). Um de: official, official-pending.
homeCode.officialAddressstring
homeCode.nameProvisionalbooleanObrigatório.
homeCode.nearstring
homeCode.municipalitystringObrigatório.
homeCode.islandstring
homeCode.postcodestring
homeCode.fullLinestringObrigatório.
homeCode.spokenstringObrigatório.
homeCode.statusstringObrigatório.
homeCode.locationPointObrigatório.
homeCode.location.typestringObrigatório.
homeCode.location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
homeCode.entranceobject
homeCode.entrance.locationPointObrigatório.
homeCode.entrance.location.typestringObrigatório.
homeCode.entrance.location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
homeCode.entrance.kindstringObrigatório. portão, porta ou centro
homeCode.entrance.verifiedbooleanObrigatório. Colocado por pessoas no local.
homeCode.plusCodestringObrigatório.
homeCode.creditstringObrigatório.
homeCode.creditUrlstring (uri)Obrigatório.
attributionstringObrigatório.
200 OK
{
  "query": "string",
  "type": "postcode",
  "code": "string",
  "location": {
    "type": "string",
    "coordinates": [
      0
    ]
  },
  "country": "string",
  "formattedAddress": "string",
  "estimated": true,
  "accuracyM": 0,
  "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": {
    "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"
  },
  "plusCode": {
    "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": {},
          "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
    ]
  },
  "homeCode": {
    "code": "Fréau-Jardin 10 58",
    "machine": "string",
    "country": "CV",
    "name": "string",
    "officialName": "string",
    "coverage": "official",
    "officialAddress": "string",
    "nameProvisional": true,
    "near": "string",
    "municipality": "string",
    "island": "string",
    "postcode": "string",
    "fullLine": "string",
    "spoken": "string",
    "status": "string",
    "location": {
      "type": "string",
      "coordinates": [
        0
      ]
    },
    "entrance": {
      "location": {
        "type": "string",
        "coordinates": [
          0
        ]
      },
      "kind": "string",
      "verified": true
    },
    "plusCode": "string",
    "credit": "Home code by N-Ways Addressing",
    "creditUrl": "string"
  },
  "attribution": "string"
}

Erros

  • default Erro

Até 100 códigos de qualquer tipo de uma vez

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

Cada código é uma unidade do SKU codes. Uma resposta por código, por ordem (result, como em /codes/{code}), com o seu próprio erro quando o tem. type, near, country e lang aplicam-se a todos os códigos. Motivos (chamada inteira): CODES_INVALID, TYPE_INVALID, NEAR_INVALID, COUNTRY_INVALID, LANG_INVALID.

Corpo do pedido

CampoTipoDescrição
codesstring[]Obrigatório. Pelo menos 1 elementos, no máximo 100 elementos.
typestringUm de: postcode, ghanapost, pluscode, homecode.
nearLatLng
near.latnumberObrigatório. ≥ -90, ≤ 90.
near.lngnumberObrigatório. ≥ -180, ≤ 180.
countrystring
langstringUm de: en, fr, pt.
cURL
curl -X POST "https://nways.ng/maps/v1/codes/batch" \
  -H "X-NWays-Api-Key: A_SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '{"codes":["LA08A09DB09","GA-183-8164","6FR5J975+P4W","Fréau-Jardin 10 58"]}'
JavaScript
const res = await fetch('https://nways.ng/maps/v1/codes/batch', {
  method: 'POST',
  headers: { 'X-NWays-Api-Key': process.env.NWAYS_API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "codes": [
      "LA08A09DB09",
      "GA-183-8164",
      "6FR5J975+P4W",
      "Fréau-Jardin 10 58"
    ]
  }),
})
const data = await res.json()
Python
import os
import requests

res = requests.post(
    "https://nways.ng/maps/v1/codes/batch",
    headers={"X-NWays-Api-Key": os.environ["NWAYS_API_KEY"]},
    json={"codes": ["LA08A09DB09", "GA-183-8164", "6FR5J975+P4W", "Fréau-Jardin 10 58"]},
    timeout=10,
)
data = res.json()

Resposta

Um resultado por código

CampoTipoDescrição
resultsobject[]Obrigatório.
results[].querystringObrigatório.
results[].resultCodeResponse
results[].result.querystringObrigatório.
results[].result.typestringObrigatório. Um de: postcode, ghanapost, pluscode, homecode.
results[].result.codestringObrigatório. Tal como está escrito: LA 08 A09 DB 09, GA-183-8164, 6FR5J975+P4W, Fréau-Jardin 10 58.
results[].result.locationPointObrigatório.
results[].result.location.typestringObrigatório.
results[].result.location.coordinatesnumber[]Obrigatório. [lng, lat] Pelo menos 2 elementos, no máximo 2 elementos.
results[].result.countrystring
results[].result.formattedAddressstring
results[].result.estimatedboolean
results[].result.accuracyMnumber
results[].result.postcodePostcode
results[].result.postcode.codestringObrigatório.
results[].result.postcode.displaystringObrigatório.
results[].result.postcode.componentsPostcodeComponentsObrigatório.
results[].result.postcode.locationPointObrigatório.
results[].result.postcode.namestring
results[].result.postcode.addressstring
results[].result.postcode.buildingTypestring
results[].result.postcode.entrancesEntrance[]Obrigatório. Verificadas primeiro, a principal primeiro: percurso para a primeira.
results[].result.postcode.plusCodestringObrigatório.
results[].result.postcode.countrystringObrigatório.
results[].result.postcode.sourcestringObrigatório. Um de: nipost, osm, user, estimate.
results[].result.postcode.estimatedbooleanObrigatório.
results[].result.postcode.accuracyMnumber
results[].result.postcode.distanceMnumberGeocodificação inversa: a partir do ponto consultado.
results[].result.postcode.attributionstringObrigatório.
results[].result.ghanaPostResult
results[].result.ghanaPost.idstringObrigatório.
results[].result.ghanaPost.namestringObrigatório.
results[].result.ghanaPost.typestringObrigatório. address, street, business, landmark, building, postcode, ghanapost, ou uma zona: neighbourhood, suburb, village, town, city, state…
results[].result.ghanaPost.categorystring
results[].result.ghanaPost.locationPointObrigatório.
results[].result.ghanaPost.bboxnumber[]oeste, sul, este, norte (zonas) Pelo menos 4 elementos, no máximo 4 elementos.
results[].result.ghanaPost.formattedAddressstring
results[].result.ghanaPost.postcodestringCódigo postal NIPOST, compacto
results[].result.ghanaPost.ghanaPoststring
results[].result.ghanaPost.plusCodestringObrigatório.
results[].result.ghanaPost.countrystring
results[].result.ghanaPost.distanceMnumberA partir de near (ou do ponto consultado).
results[].result.ghanaPost.estimatedbooleanO ponto é uma estimativa, dentro de accuracyM.
results[].result.ghanaPost.accuracyMnumber
results[].result.ghanaPost.placeIdstringUm negócio: o seu id para /places/{id}.
results[].result.ghanaPost.attributionstring
results[].result.plusCodePlusCodeResponse
results[].result.plusCode.locationPointObrigatório.
results[].result.plusCode.plusCodestringObrigatório.
results[].result.plusCode.countryArea | nullObrigatório.
results[].result.plusCode.regionArea | nullObrigatório.
results[].result.plusCode.formattedAddressstring
results[].result.plusCode.postcodePostcode | nullObrigatório. Nigéria: o código postal NIPOST do edifício, quando há um ao alcance.
results[].result.plusCode.ghanaPoststring | nullObrigatório. Gana: o endereço GhanaPost GPS conhecido mais próximo (a menos de 100 m).
results[].result.plusCode.nearestResult | nullObrigatório.
results[].result.plusCode.attributionstringObrigatório.
results[].result.plusCode.boundsnumber[]Obrigatório. oeste, sul, este, norte Pelo menos 4 elementos, no máximo 4 elementos.
results[].result.homeCodeHomeCodeUm código de casa N-Ways: o endereço de um edifício em forma de nome e número. As pessoas escrevem code; machine traz o dígito de controlo para os sistemas.
results[].result.homeCode.codestringObrigatório.
results[].result.homeCode.machinestringObrigatório. Com o dígito de controlo (apenas sistemas; nunca mostrado às pessoas).
results[].result.homeCode.countrystringObrigatório.
results[].result.homeCode.namestringObrigatório.
results[].result.homeCode.officialNamestring
results[].result.homeCode.coveragestringOnde existe um endereço oficial (officialAddress primeiro). Um de: official, official-pending.
results[].result.homeCode.officialAddressstring
results[].result.homeCode.nameProvisionalbooleanObrigatório.
results[].result.homeCode.nearstring
results[].result.homeCode.municipalitystringObrigatório.
results[].result.homeCode.islandstring
results[].result.homeCode.postcodestring
results[].result.homeCode.fullLinestringObrigatório.
results[].result.homeCode.spokenstringObrigatório.
results[].result.homeCode.statusstringObrigatório.
results[].result.homeCode.locationPointObrigatório.
results[].result.homeCode.entranceobject
results[].result.homeCode.plusCodestringObrigatório.
results[].result.homeCode.creditstringObrigatório.
results[].result.homeCode.creditUrlstring (uri)Obrigatório.
results[].result.attributionstringObrigatório.
results[].errorItemError
results[].error.codeintegerObrigatório.
results[].error.reasonstringObrigatório.
results[].error.messagestringObrigatório.
attributionstringObrigatório.
200 OK
{
  "results": [
    {
      "query": "string",
      "result": {
        "query": "string",
        "type": "postcode",
        "code": "string",
        "location": {
          "type": "string",
          "coordinates": []
        },
        "country": "string",
        "formattedAddress": "string",
        "estimated": true,
        "accuracyM": 0,
        "postcode": {
          "code": "LA08A09DB09",
          "display": "LA 08 A09 DB 09",
          "components": {},
          "location": {},
          "name": "string",
          "address": "string",
          "buildingType": "string",
          "entrances": [],
          "plusCode": "string",
          "country": "string",
          "source": "nipost",
          "estimated": true,
          "accuracyM": 0,
          "distanceM": 0,
          "attribution": "string"
        },
        "ghanaPost": {
          "id": "osm:w568367632",
          "name": "Ikeja City Mall",
          "type": "landmark",
          "category": "shopping",
          "location": {},
          "bbox": [],
          "formattedAddress": "Ikeja, Lagos",
          "postcode": "LA08A09DB09",
          "ghanaPost": "GA-183-8164",
          "plusCode": "6FR5J975+P4W",
          "country": "NG",
          "distanceM": 0,
          "estimated": true,
          "accuracyM": 0,
          "placeId": "string",
          "attribution": "string"
        },
        "plusCode": {
          "location": {},
          "plusCode": "string",
          "country": {},
          "region": {},
          "formattedAddress": "12 Admiralty Way, Lekki, Lagos State, Nigeria",
          "postcode": {},
          "ghanaPost": "string",
          "nearest": {},
          "attribution": "string",
          "bounds": []
        },
        "homeCode": {
          "code": "Fréau-Jardin 10 58",
          "machine": "string",
          "country": "CV",
          "name": "string",
          "officialName": "string",
          "coverage": "official",
          "officialAddress": "string",
          "nameProvisional": true,
          "near": "string",
          "municipality": "string",
          "island": "string",
          "postcode": "string",
          "fullLine": "string",
          "spoken": "string",
          "status": "string",
          "location": {},
          "entrance": {},
          "plusCode": "string",
          "credit": "Home code by N-Ways Addressing",
          "creditUrl": "string"
        },
        "attribution": "string"
      },
      "error": {
        "code": 0,
        "reason": "string",
        "message": "string"
      }
    }
  ],
  "attribution": "string"
}

Erros

  • default Erro