Postal code lookup

A postal code in, the place it belongs to out. Covers 121 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.
`key`optional	string	API key, if not sent as a header.

Example

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"])

Response

{
  "status": "ok",
  "postcode": "75008",
  "country_code": "FR",
  "results": [
    {
      "postcode": "75008",
      "place": "Paris",
      "region": "Île-de-France",
      "region_code": null,
      "country": "France",
      "country_code": "FR",
      "lat": 48.853402,
      "lon": 2.348799
    },
    {
      "postcode": "75008",
      "place": "Paris 08",
      "region": "Île-de-France",
      "region_code": null,
      "country": "France",
      "country_code": "FR",
      "lat": 48.876299,
      "lon": 2.318299
    }
  ]
}

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[].postcode`	string	The code as the country writes it: `K1A 0B1`.
`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 (`region_code` is `null` where there is none).
`results[].country`, `country_code`	string	Country name and upper-case ISO 3166-1 alpha-2 code.
`results[].lat`, `lon`	number	The postal authority's point where published, otherwise the centroid of addresses in the code.

Notes

A partial code returns the area of every code that begins with it: SW1A for the UK returns the postcode district, K1A for Canada the forward sortation area, and with country set, the start of any country's code (750 for France) the area its codes cover.
Countries without postal codes (Ireland before Eircode, several in Africa and the Middle East) return an empty results array with status: ok.
Canada answers full six-character postcodes (K1A 0B1) as well as the first three (K1A), and Canadian addresses carry their full postcode.
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.