Can I choose an Australian suburb?

Yes. Pass country=AU to get localities with suburb and state choices. city is filled only when the evidence is unambiguous. Otherwise offer the choices and keep manual entry available, even when there is only one suggestion. The August 2026 reference supports geographic lookup; it does not verify a mailing address.

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

Australia: Suburb choices for 2,634 geographic postcodes from August 2026. 694 have an unambiguous city for autofill; other codes keep city null. Each choice includes its state. Coordinates remain approximate postal-area locations.
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: 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.
Portugal: Locality names where the published postal name agrees. Geographic coordinates. Special and newly issued codes may be missing.
Spain: Locality and administrative names where unambiguous.
United Kingdom: England, Scotland, and Wales, plus Northern Ireland postcodes with observed premises locations.
Uruguay: 121 postal areas with coordinates. Locality and department names where the address records agree.

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/10001?country=US" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0"

// Example response · 200
{
  "postal": "10001",
  "city": "New York",
  "district": "36061",
  "district_name": "New York",
  "state": "NY",
  "state_name": "New York",
  "country": "US",
  "country_name": "United States",
  "latitude": 40.750649,
  "longitude": -73.997298,
  "timezone": "America/New_York"
}

API reference SDKs Keys and authentication

Every response field

Response fields

postalstring: Postal or ZIP code
citystring or null: Primary city name (English or romanized when available, native otherwise)
city_localstring or null: Native city name (null when absent or same as city). Read city_local ?? city for the original-script form
localitiesarray or null: Australian suburb choices from August 2026. Null outside the reviewed reference; [] when reviewed with no eligible choices. Use city for autofill; a single choice can still require selection
localities[].citystring: Source suburb or locality name
localities[].statestring: State or territory abbreviation for this option; may differ from the postcode state
localities[].state_namestring: English state or territory name for this option; independent of lang
districtstring or null: 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_namestring or null: District / ADM2 name (English or romanized when available, native otherwise)
district_name_localstring or null: Native district name (null when absent or same as district_name)
statestring or null: State or province code
state_namestring or null: State or province name (English or romanized when available, native otherwise)
state_name_localstring or null: Native state or province name (null when absent or same as state_name)
countrystring: ISO2 country code
country_namestring or null: Country name
latitudenumber or null: Approximate latitude
longitudenumber or null: Approximate longitude
timezonestring or null: Timezone identifier

Deep fields

deep.elevationnumber or null: Elevation in meters
deep.elevation_ftnumber or null: Elevation in feet
deep.populationinteger or null: Population estimate
deep.population_periodstring or null: 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.areanumber or null: Total area in km² (null when the source has no water split)
deep.land_areanumber or null: Land area in km² (null where the source has none)
deep.water_areanumber or null: Water area in km² (null where the source has none)
deep.currencystring or null: ISO currency code for the country
deep.taxstring or null: 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_ratenumber or null: 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_statenumber or null: State piece of the combined rate, percent. Null when unavailable or not applicable
deep.tax_rate_countynumber or null: County piece of the combined rate, percent. Null when unavailable or not applicable
deep.tax_rate_citynumber or null: City piece of the combined rate, percent. Null when unavailable or not applicable
deep.tax_rate_specialnumber or null: Special district piece of the combined rate, percent. Null when unavailable or not applicable
deep.neighborsarray or null: Short list of surrounding postal codes (like country borders)
deep.metrosarray or null: 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[].codestring: Five-digit CBSA code
deep.metros[].namestring: Metropolitan or micropolitan statistical area name
deep.metros[].typestring: metropolitan or micropolitan
deep.metros[].sharenumber or null: Fraction of all addresses in the ZIP associated with this area, from 0 to 1; null when unknown
deep.metros[].residential_sharenumber or null: 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_sharenumber or null: 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_sharenumber or null: 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_taxobject or null: 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_medianinteger: Median annual amount in currency. Dollars adjusted to the final year of period
deep.property_tax.currencystring: USD
deep.property_tax.periodstring: 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.

38ms

41ms

APAC

132ms

LatAm

46ms

138ms

See live status →

Build with Postal

All tutorials →

QUESTIONS

Can I choose an Australian suburb?: Yes. Pass country=AU to get localities with suburb and state choices. city is filled only when the evidence is unambiguous. Otherwise offer the choices and keep manual entry available, even when there is only one suggestion. The August 2026 reference supports geographic lookup; it does not verify a mailing address.
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.

Ready for busy moments.Start includes 1,800 requests per minute, with extra capacity for bursts. Rate limits

Get started Compare plans Read the docs