One code for the place. /nearby for the codes around it. /distance for miles between two.

48 countries and territories, plus Åland and Svalbard/Jan Mayen. See the Coverage section for the full list and country details.

City, state, district, country, coordinates, and timezone. Paid deep adds elevation, population, area, tax references, neighbors, and US metropolitan associations where known.

Does it include sales tax?

Paid deep adds a US ZIP combined reference rate and local components where known. Country and state detail use deep.tax and deep.tax_rate for their own scopes. The exact address rate can differ.

Not when the code exists in exactly one covered country. SW1A 1AA resolves bare. Pass ?country=JP for 100-0001, whose digits also occur in Portugal. Codes shared by multiple countries return a 404 asking for ?country=, never a guessed US ZIP. Country takes ISO2, ISO3, or a name.

The layer under the state. A US county FIPS, a French INSEE department, a GB GSS code. /district turns that code into a name.

Paid deep.neighbors lists surrounding postal codes. Use the nearby operation for a radius search with distances on every plan.

Do nearby and distance ship?

Yes, in miles and kilometers, on every plan where we have coordinates.

GET /postal/{code} · /nearby · /distance/{other}

ZIP code API

Pass a ZIP or postcode. City, state, district, coordinates, and timezone.

You have a ZIP or postcode. City, district, tax.

Example response/postal/SW1A%201AA

{
  "postal": "SW1A1AA",
  "city": "City of Westminster",
  "city_local": null,
  "district": "E09000033",
  "district_name": "City of Westminster",
  "district_name_local": null,
  "state": "ENG",
  "state_name": "England",
  "state_name_local": null,
  "country": "GB",
  "country_name": "United Kingdom",
  "latitude": 51.501009,
  "longitude": -0.141588,
  "timezone": "Europe/London",
  ?deep=true
}

1M requests · $20/mo. Get started

Coverage

48 countries and territories, plus Åland and Svalbard/Jan Mayen.

United States
Mexico
United Kingdom
France
Switzerland
Liechtenstein
Denmark
Japan
Australia
Austria
Norway
Finland
Luxembourg
Czechia
Belgium
Netherlands
Slovenia
Latvia
Hungary
Iceland
Estonia
Lithuania
Malaysia
Cyprus
Mauritius
Slovakia
South Korea
Colombia
Uruguay
Spain
Italy
Portugal
Croatia
Bulgaria
Costa Rica
Sri Lanka
Nepal
Brazil
Faroe Islands
Monaco
Morocco
Peru
North Macedonia
Moldova
Albania
Guernsey
Jersey
Isle of Man
Åland
Svalbard and Jan Mayen

See Country details for fields and editions. Missing values return null. Distance and nearby require coordinates.

Country details

Albania: 532 published codes. Postal destination names where unambiguous. Approximate postal-area coordinates for 383 codes.
Brazil: Codes recorded in the 2022 census, with approximate coordinates from address locations.
Colombia: Coordinates describe postal areas published in 2013.
Croatia and Bulgaria: Selected geographic postal codes with coordinates. Locality names return null.
Faroe Islands: Approximate village centres for mapped postal codes.
Guernsey, Jersey, and Isle of Man: 11,106 active codes from August 2026, with country, timezone, and currency. Names are unavailable. Jersey has approximate coordinates for 42 codes, from facility locations recorded in 2018; other codes have no coordinates.
Italy, Portugal, and Uruguay: Geographic postal points without locality names. Special and newly issued codes may be missing.
Lithuania: Eight counties, excluding Vilnius and Utena in the current edition.
Malaysia, South Korea, Costa Rica, Sri Lanka, and Slovenia: Names without coordinates.
Mauritius: Main island only. Names without coordinates.
Mexico: Available coordinates describe matched business locations.
Moldova: 1,063 ordinary office codes. Locality and region names where the served areas agree. No coordinates.
Monaco: The ordinary code 98000. Names without coordinates.
Morocco: 1,666 locality codes from September 2018, with city and province names. Neighborhood codes and southern postal regions are excluded. No coordinates.
Nepal: Current five-digit municipality and seven-digit ward codes. Names without coordinates.
Netherlands: 468,408 codes covering geographic postal areas and address codes recorded on September 5, 2026. Locality names where unambiguous. The 2,473 additional address codes have approximate coordinates derived from their address locations.
North Macedonia: 202 corroborated codes. Postal destination names where the published names agree. No coordinates.
Peru: 2,669 published codes from March 2018. Locality, province, and department names where unambiguous. Approximate locality-based coordinates for 2,129 codes; several urban codes may share a point.
Spain: Locality and administrative names where unambiguous.
United Kingdom: England, Scotland, and Wales, plus Northern Ireland postcodes with observed premises locations.

Get city, state, district, timezone, and coordinates from a ZIP or postal code. Add ?country= when a code exists in more than one country.

Make your first request.

One key works across the APIs. Copy a request in your language and get JSON back.

curl "https://api.parseapi.com/postal/33139?country=US" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0"

// Example response · 200
{
  "postal": "33139",
  "city": "Miami Beach",
  "city_local": null,
  "district": "12086",
  "district_name": "Miami-Dade",
  "district_name_local": null,
  "state": "FL",
  "state_name": "Florida",
  "state_name_local": null,
  "country": "US",
  "country_name": "United States",
  "latitude": 25.779391,
  "longitude": -80.151566,
  "timezone": "America/New_York"
}

API reference SDKs Keys and authentication

Every response field

Response fields

postal: Postal or ZIP code
city: Primary city name (English or romanized when available, native otherwise)
city_local: Native city name (null when absent or same as city). Read city_local ?? city for the original-script form
district: District code when /district can resolve it for this country (US FIPS, FR INSEE, GB GSS). Null for Japan until JP districts are seeded
district_name: District / ADM2 name (English or romanized when available, native otherwise)
district_name_local: Native district name (null when absent or same as district_name)
state: State or province code
state_name: State or province name (English or romanized when available, native otherwise)
state_name_local: Native state or province name (null when absent or same as state_name)
country: ISO2 country code
country_name: Country name
latitude: Approximate latitude
longitude: Approximate longitude
timezone: Timezone identifier

Deep fields

deep.elevation: Elevation in meters
deep.elevation_ft: Elevation in feet
deep.population: Population estimate
deep.population_period: Observation year or multi-year period for this population estimate (YYYY or YYYY-YYYY). Null when the record has no verified period or population. Never the import date.
deep.area: Total area in km² (null when the source has no water split)
deep.land_area: Land area in km² (null where the source has none)
deep.water_area: Water area in km² (null where the source has none)
deep.currency: ISO currency code for the country
deep.tax: US ZIP levy name (Sales tax, General excise tax). A local levy can apply where the state has none. Null when unavailable or no levy is named
deep.tax_rate: Combined ZIP sales tax reference in percent. 0 is known zero; null is unavailable. An exact address can have a different rate
deep.tax_rate_state: State piece of the combined rate, percent. Null when unavailable or not applicable
deep.tax_rate_county: County piece of the combined rate, percent. Null when unavailable or not applicable
deep.tax_rate_city: City piece of the combined rate, percent. Null when unavailable or not applicable
deep.tax_rate_special: Special district piece of the combined rate, percent. Null when unavailable or not applicable
deep.neighbors: Short list of surrounding postal codes (like country borders)
deep.metros: US ZIP metropolitan and micropolitan area associations. Null when unsupported or unverified; [] only when complete observations place the ZIP outside every CBSA. Sorted by descending share (null last), then code. Shares are address fractions and are not renormalized.
deep.metros[].code: Five-digit CBSA code
deep.metros[].name: Metropolitan or micropolitan statistical area name
deep.metros[].type: metropolitan or micropolitan
deep.metros[].share: Fraction of all addresses in the ZIP associated with this area, from 0 to 1; null when unknown
deep.metros[].residential_share: Fraction of residential addresses in the ZIP associated with this area, from 0 to 1; null when unknown or the ZIP has no residential addresses
deep.metros[].business_share: Fraction of business addresses in the ZIP associated with this area, from 0 to 1; null when unknown or the ZIP has no business addresses
deep.metros[].other_share: Fraction of other addresses in the ZIP associated with this area, from 0 to 1; null when unknown or the ZIP has no other addresses
deep.property_tax: Median annual real-estate tax payable on owner-occupied housing, in US dollars adjusted to the final year of period. Available US ZIP-area and county estimates only. Not a percentage or an individual property bill. Null when missing, censored or unsupported.
deep.property_tax.annual_median: Median annual amount in currency. Dollars adjusted to the final year of period
deep.property_tax.currency: USD
deep.property_tax.period: Observation period, such as 2020-2024

More than a city name

Fill in the city, state, and district from a ZIP or postal code. Coordinates put the place on a map, and timezone helps you schedule in local time.

Paid deep adds elevation, population, and land and water area where available. US ZIP detail also includes a combined sales tax reference rate where available. The rate at an exact address can differ. Fields vary by country, and missing values return null.

A country when you need one

A unique code like SW1A 1AA resolves on its own. For 100-0001, pass ?country=JP because the same digits also occur in Portugal.

If a code is shared across countries, the API returns a 404 asking for the country. It accepts a two-letter code, a three-letter code, or a country name.

Postal lookup requests

GET /postal/SW1A%201AA
GET /postal/100-0001?country=JP

Names in both scripts

city uses English or an official romanization when available. Otherwise, it keeps the native name. Japanese postcodes also return city_local in the native script, so you can display the name that fits your audience. Unknown or ambiguous names stay null.

Native-name example

A Tokyo postcode pairs Chiyoda Ku with 千代田区.

100-0001, Japan · response excerpt

{
  "city": "Chiyoda Ku",
  "city_local": "千代田区"
}

Nearby codes and distances

Use nearby to find postal codes within a radius, or distance to measure between two codes. Results include miles and kilometers on every plan.

Both need coordinates for the codes you pass. Distances are straight-line measurements between postal locations, useful for a store locator or an initial delivery-area check.

The larger area around a ZIP

Add deep=true on a paid plan to read deep.metros, the metropolitan and micropolitan areas associated with a US ZIP. A ZIP can span several areas, helping you group locations across a wider region.

Metro shares and missing values

Each share is a fraction of addresses, with separate residential, business, and other shares. A category share is null when unknown or the ZIP has no addresses in that category. For deep.metros itself, null means no verified association data. An empty array, [], means complete data places the ZIP outside every metro or micro area.

28202 US · GET /postal/28202?country=US&deep=true · response excerpt

{
  "deep": {
    "metros": [
      {
        "code": "16740",
        "name": "Charlotte-Concord-Gastonia, NC-SC",
        "type": "metropolitan",
        "share": 1
      }
    ]
  }
}

This product uses the HUD User Data API but is not endorsed or certified by HUD User.

SPEED

How long /postal takes.

Median time to first byte over the last seven days. Warm requests, measured every 30 minutes. Live verification and other request variants can take longer.

29ms

APAC

56ms

LatAm

46ms

97ms

See live status →

Build with Postal

All tutorials →

QUESTIONS

When do I use which?: One code for the place. /nearby for the codes around it. /distance for miles between two.
Which countries?: 48 countries and territories, plus Åland and Svalbard/Jan Mayen. See the Coverage section for the full list and country details.
What comes back?: City, state, district, country, coordinates, and timezone. Paid deep adds elevation, population, area, tax references, neighbors, and US metropolitan associations where known.
Which language are city names in?: city uses English or an official romanization when available. Otherwise it keeps the native name. Japanese postcodes also return city_local in the native script. For example, Chiyoda Ku pairs with 千代田区. Unknown or ambiguous names return null.
Does it include sales tax?: Paid deep adds a US ZIP combined reference rate and local components where known. Country and state detail use deep.tax and deep.tax_rate for their own scopes. The exact address rate can differ.
Do I need a country?: Not when the code exists in exactly one covered country. SW1A 1AA resolves bare. Pass ?country=JP for 100-0001, whose digits also occur in Portugal. Codes shared by multiple countries return a 404 asking for ?country=, never a guessed US ZIP. Country takes ISO2, ISO3, or a name.
What is a district?: The layer under the state. A US county FIPS, a French INSEE department, a GB GSS code. /district turns that code into a name.
What are neighbors?: Paid deep.neighbors lists surrounding postal codes. Use the nearby operation for a radius search with distances on every plan.
Do nearby and distance ship?: Yes, in miles and kilometers, on every plan where we have coordinates.

Look up a ZIP, every ZIP in a radius, or the distance between two.

More than a code.

Postal codes and coordinates on every plan. Place details on paid plans.

Start includes 1M API requests a month for $20/mo.

Get started Compare plans Read the docs