Postal code lookup

A postal code in, the place it belongs to out. Covers 160 countries.

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

Parameters

Parameter	Type	Description
`code`required	string	The postal code. Spaces, hyphens and case are normalised.
`country`optional	string	ISO 3166-1 alpha-2 code. Strongly recommended; postal codes are not unique across countries. Without it, results from every matching country are returned, largest population first.
`lang`optional	string	ISO 639-1 code for place and region names. Default `en`.
`key`optional	string	API key, if not sent as a header.

Example

curlJavaScriptPython

$ curl "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)).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"}, timeout=5)
first = r.json()["results"][0]
print(first["place"], first["lat"], first["lon"])

Response

{
  "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
    }
  ]
}

Response fields

Field	Type	Description
`postcode`	string	The code after normalisation.
`country_code`	string or null	The country filter applied, if any.
`results`	array	Places the code covers. Usually one; several for rural codes that span villages. Empty if the code is unknown.
`results[].place`	string	Locality name as used by the postal authority.
`results[].region`, `region_code`	string	First-level division and its ISO 3166-2 suffix.
`results[].lat`, `lon`	number	The postal authority's point where published, otherwise the centroid of addresses in the code.

Notes

Partial codes work where the country's system is hierarchical: SW1A for the UK returns the district; 750 for France returns nothing, because French codes are not prefixes.
Countries without postal codes (Ireland before Eircode, several in Africa and the Middle East) return an empty results array with status: ok.
For a full address with a house number, use forward geocoding; the postcode helps it too.

Errors

400 invalid_request when code is empty or longer than 16 characters, or country is not a valid alpha-2 code.