A free postal & ZIP code lookup API

Asking a user to type their city and state when they've already typed a ZIP code is busywork. A postal code already implies the place — you just need to resolve it.

Look up a postal code

The path is /postal/{country}/{code} — an ISO alpha-2 country code and the postal/ZIP code:

curl https://countries.dev/postal/US/90210

[
  {
    "countryCode": "US",
    "postalCode": "90210",
    "placeName": "Beverly Hills",
    "admin1": { "name": "California", "code": "CA" },
    "admin2": { "name": "Los Angeles", "code": "037" },
    "latitude": 34.0901,
    "longitude": -118.4065,
    "accuracy": 4
  }
]

Autofill a checkout

Resolve the city and state the moment someone finishes the ZIP field:

const [place] = await fetch(`https://countries.dev/postal/US/${zip}`).then((r) => r.json());
if (place) {
  cityInput.value = place.placeName;
  stateInput.value = place.admin1.name;
}

Coverage

Postal data comes from GeoNames, which covers roughly 120 countries — strong for the US, UK, Germany, France, Japan and most of Europe, thinner or absent for a few (Ireland and Israel, for example). Check which countries are covered:

curl https://countries.dev/postal/countries

A code with no match returns a 404, so treat that as "unknown postal code" rather than an error.

Postal code docs →