Consulta de código postal

Entra um código postal, sai o lugar a que ele pertence. Cobre 160 países.

GEThttps://api.mygeocode.com/v1/postcode

Parâmetros

Parâmetro	Tipo	Descrição
`code`obrigatório	string	O código postal. Espaços, hifens e maiúsculas e minúsculas são normalizados.
`country`opcional	string	Código ISO 3166-1 alfa-2. Altamente recomendado; códigos postais não são únicos entre países. Sem ele, são retornados resultados de todos os países correspondentes, da maior população para a menor.
`lang`opcional	string	Código ISO 639-1 para nomes de lugares e regiões. Padrão `en`.
`key`opcional	string	Chave de API, se não for enviada como cabeçalho.

Exemplo

curlJavaScriptPython

$ curl -H "X-API-Key: YOUR_KEY" "https://api.mygeocode.com/v1/postcode?code=75008&country=fr"

const url = new URL("https://api.mygeocode.com/v1/postcode");
url.searchParams.set("code", "75008");
url.searchParams.set("country", "fr");

const { results } = await (await fetch(url, { headers: { "X-API-Key": "YOUR_KEY" } })).json();
console.log(results[0].place, results[0].lat, results[0].lon);

import requests

r = requests.get("https://api.mygeocode.com/v1/postcode", params={"code": "75008", "country": "fr"}, headers={"X-API-Key": "YOUR_KEY"}, timeout=5)
first = r.json()["results"][0]
print(first["place"], first["lat"], first["lon"])

Resposta

{
  "status": "ok",
  "postcode": "75008",
  "country_code": "FR",
  "results": [
    {
      "postcode": "75008",
      "place": "Paris 8e Arrondissement",
      "region": "Ile-de-France",
      "region_code": "IDF",
      "country": "France",
      "country_code": "FR",
      "lat": 48.8727,
      "lon": 2.3125
    }
  ]
}

Campos da resposta

Campo	Tipo	Descrição
`postcode`	string	O código após a normalização.
`country_code`	string ou null	O filtro de país aplicado, se houver.
`results`	array	Lugares que o código cobre. Normalmente um; vários para códigos rurais que abrangem povoados. Vazio se o código for desconhecido.
`results[].place`	string	Nome da localidade conforme usado pela autoridade postal.
`results[].region`, `region_code`	string	Divisão de primeiro nível e o seu sufixo ISO 3166-2.
`results[].lat`, `lon`	número	O ponto da autoridade postal, quando publicado; caso contrário, o centroide dos endereços do código.

Observações

Códigos parciais funcionam onde o sistema do país é hierárquico: SW1A para o Reino Unido retorna o distrito; 750 para a França não retorna nada, porque os códigos franceses não são prefixos.
Países sem códigos postais (a Irlanda antes do Eircode, vários na África e no Oriente Médio) retornam um array results vazio com status: ok.
Para um endereço completo com número de casa, use a geocodificação direta; o código postal também ajuda nela.

Erros

400 invalid_request quando code está vazio ou tem mais de 16 caracteres, ou quando country não é um código alfa-2 válido.