Postal API

A ZIP or postal code to its city, state, coordinates, and timezone.

Look up a postal or ZIP code. A code that exists in exactly one covered country resolves bare: /postal/SW1A 1AA. Use /postal/100-0001?country=JP for Japan; its seven digits also occur in Portugal. Shared codes return a 404 asking for ?country=, never a guessed US ZIP. ?country= takes ISO2, ISO3, or a name.

Every plan gives place identity, coordinates and timezone. Paid plans automatically include available population, area, elevation, nearby codes, metro areas and tax references. city, state_name, and county_name read in English or an official romanization when a trusted source has one. Native siblings (city_local, state_name_local, county_name_local) ship when they differ.

US and qualified territory ZIPs also include optional type: standard, po_box, unique, military, or null when unknown. This is a recorded ZIP classification, not address or delivery verification. Military ZIPs describe USPS routing; recipient geography stays unavailable.

LookupCopy link

GET /postal/{code}API Explorer ↗

Postal lookup. ?country= when the code collides

Parameters

codestring · path · required

Postal or ZIP code. Unique codes resolve bare (SW1A 1AA). Use ?country=JP for 100-0001, whose digits also occur in Portugal.

countrystring · query · optional

ISO2, ISO3, or a country name. Optional when the code exists in exactly one covered country. Both five-digit and seven-digit codes can collide.

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

Length: 2 to 64 characters

Example

Request

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("10001", { country: "US" });
console.log(result);
Example responsePaid plan
{
  "postal": "10001",
  "city": "New York",
  "city_local": null,
  "county": "36061",
  "county_name": "New York",
  "county_name_local": null,
  "state": "NY",
  "state_name": "New York",
  "state_name_local": null,
  "country": "US",
  "country_name": "United States",
  "latitude": 40.750649,
  "longitude": -73.997298,
  "timezone": "America/New_York",
  "type": "standard",
  "elevation": 20,
  "elevation_ft": 66,
  "population": 30511,
  "area": 1.62,
  "land_area": 1.62,
  "water_area": 0,
  "currency": "USD",
  "tax": {
    "name": "Sales tax",
    "rate": 8.875,
    "rate_state": 4,
    "rate_county": null,
    "rate_city": 4.5,
    "rate_special": 0.375
  },
  "property_tax": {
    "annual_median": 7937
  },
  "neighbors": [
    "10199",
    "10119",
    "10018",
    "10011",
    "10036",
    "10110",
    "10173",
    "10165"
  ],
  "metros": [
    {
      "code": "35620",
      "name": "New York-Newark-Jersey City, NY-NJ",
      "type": "metropolitan",
      "share_percent": 100
    }
  ],
  "localities": null
}

More examples

Some postal codes cover several localities. These examples use Australian postcodes to show a choice list and a single city. Optional tax details use a US ZIP.

Example

Request

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("2000", { country: "AU" });
console.log(result);
Example responsePaid plan
{
  "postal": "2000",
  "city": null,
  "city_local": null,
  "county": null,
  "county_name": null,
  "county_name_local": null,
  "state": "NSW",
  "state_name": "New South Wales",
  "state_name_local": null,
  "country": "AU",
  "country_name": "Australia",
  "latitude": -33.864482,
  "longitude": 151.211546,
  "timezone": "Australia/Sydney",
  "elevation": 69,
  "elevation_ft": 226,
  "population": 27936,
  "area": null,
  "land_area": 4.29,
  "water_area": null,
  "currency": "AUD",
  "tax": {
    "name": null,
    "rate": null,
    "rate_state": null,
    "rate_county": null,
    "rate_city": null,
    "rate_special": null
  },
  "property_tax": null,
  "neighbors": [
    "2011",
    "2061",
    "2009",
    "2010",
    "2007",
    "2060",
    "2027",
    "2041"
  ],
  "metros": null,
  "localities": [
    {
      "city": "BARANGAROO",
      "state": "NSW",
      "state_name": "New South Wales"
    },
    {
      "city": "DAWES POINT",
      "state": "NSW",
      "state_name": "New South Wales"
    },
    {
      "city": "HAYMARKET",
      "state": "NSW",
      "state_name": "New South Wales"
    },
    {
      "city": "MILLERS POINT",
      "state": "NSW",
      "state_name": "New South Wales"
    },
    {
      "city": "SYDNEY",
      "state": "NSW",
      "state_name": "New South Wales"
    },
    {
      "city": "THE ROCKS",
      "state": "NSW",
      "state_name": "New South Wales"
    }
  ]
}

Response fields

postalLink to postalstring
Postal or ZIP code
cityLink to citystring or null
Primary city name (English or romanized when available, native otherwise)
city_localLink to city_localstring or null
Native city name (null when absent or same as city). Read city_local ?? city for the original-script form
countyLink to countystring or null
County code when /district can resolve it for this country (US FIPS, FR INSEE, GB GSS). Null where County lookup is unsupported
county_nameLink to county_namestring or null
County or equivalent area name (English or romanized when available, native otherwise)
county_name_localLink to county_name_localstring or null
Native county name (null when absent or same as county_name)
stateLink to statestring or null
State or province code
state_nameLink to state_namestring or null
State or province name (English or romanized when available, native otherwise)
state_name_localLink to state_name_localstring or null
Native state or province name (null when absent or same as state_name)
countryLink to countrystring
ISO2 country code
country_nameLink to country_namestring or null
Country name
latitudeLink to latitudenumber or null
Approximate latitude
longitudeLink to longitudenumber or null
Approximate longitude
timezoneLink to timezonestring or null
Timezone identifier
typeLink to typestring or null
US or qualified territory/FAS ZIP type: standard, po_box, unique, military or null
localitiesLink to 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[].cityLink to localities[].citystring
Source suburb or locality name
localities[].stateLink to localities[].statestring
State or territory abbreviation for this option; may differ from the postcode state
localities[].state_nameLink to localities[].state_namestring
English state or territory name for this option; independent of lang

Metro areasCopy link

metros lists the metropolitan and micropolitan statistical areas associated with a US ZIP. Each entry has a five-digit code, name, type, and share_percent. A ZIP may be associated with several areas.

share_percent is the percentage of all ZIP addresses associated with this area, from 0 to 100. Decimal values are supported; null means unknown. A zero is known zero. Entries sort by descending percentage, unknown values last, then code. Percentages are not renormalized when some addresses lie outside these areas.

metros: null means unsupported or unverified coverage. metros: [] means complete observations place the ZIP outside all metro and micro areas. When deep is requested, distance responses put metros in from and to; nearby responses put it in each postal record.

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

DistanceCopy link

How far is one ZIP from another? Pass two codes and get straight-line miles and km back. Handy for shipping estimates, store radius checks, and "is this close enough?"

GET /postal/{code}/distance/{other}API Explorer ↗

Straight-line distance in miles and km

Parameters

codestring · path · required

First postal or ZIP code

otherstring · path · required

Second postal or ZIP code

countrystring · query · optional

ISO2, ISO3, or a country name. Optional when the first code is unique.

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

Length: 2 to 64 characters

Request

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal.distance("28202", "10001", { country: "US" });
console.log(result);
Example responsePaid plan
{
  "country": "US",
  "from": {
    "postal": "28202",
    "city": "Charlotte",
    "metros": [
      {
        "code": "16740",
        "name": "Charlotte-Concord-Gastonia, NC-SC",
        "type": "metropolitan",
        "share_percent": 100
      }
    ]
  },
  "to": {
    "postal": "10001",
    "city": "New York",
    "metros": [
      {
        "code": "35620",
        "name": "New York-Newark-Jersey City, NY-NJ",
        "type": "metropolitan",
        "share_percent": 100
      }
    ]
  },
  "distance": 858.08,
  "distance_mi": 533.19
}

Response fields

countryLink to countrystring
ISO2 country code
fromLink to fromobject
Origin postal code and city
toLink to toobject
Destination postal code and city
distanceLink to distancenumber
Straight-line distance in km
distance_miLink to distance_minumber
Straight-line distance in miles

NearbyCopy link

Find other postal codes within a radius, with km and miles. Paid postal lookups also include a short neighbors list. Use nearby when you need a search radius and distances. Default unit=km (radius 40); pass unit=mi for miles.

GET /postal/{code}/nearbyAPI Explorer ↗

Nearby postal codes. Default unit=km

Parameters

codestring · path · required

Postal or ZIP code to search around

countrystring · query · optional

ISO2, ISO3, or a country name. Optional when the code is unique.

radiusnumber · query · optional

Search radius (default 40 km)

unitstring · query · optional

Radius unit, km (default) or mi

Values: km, mi

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

Length: 2 to 64 characters

Request

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal.nearby("28202", { country: "US", radius: 3 });
console.log(result);
Example responsePaid plan
{
  "postal": "28202",
  "country": "US",
  "radius": 3,
  "unit": "km",
  "nearby": [
    {
      "postal": "28280",
      "city": "Charlotte",
      "state": "NC",
      "country": "US",
      "distance": 0.1,
      "distance_mi": 0.1,
      "metros": [
        {
          "code": "16740",
          "name": "Charlotte-Concord-Gastonia, NC-SC",
          "type": "metropolitan",
          "share_percent": 100
        }
      ]
    },
    {
      "postal": "28282",
      "city": "Charlotte",
      "state": "NC",
      "country": "US",
      "distance": 0.3,
      "distance_mi": 0.2,
      "metros": [
        {
          "code": "16740",
          "name": "Charlotte-Concord-Gastonia, NC-SC",
          "type": "metropolitan",
          "share_percent": 100
        }
      ]
    },
    {
      "postal": "28244",
      "city": "Charlotte",
      "state": "NC",
      "country": "US",
      "distance": 0.3,
      "distance_mi": 0.2,
      "metros": [
        {
          "code": "16740",
          "name": "Charlotte-Concord-Gastonia, NC-SC",
          "type": "metropolitan",
          "share_percent": 100
        }
      ]
    },
    {
      "postal": "28204",
      "city": "Charlotte",
      "state": "NC",
      "country": "US",
      "distance": 2.1,
      "distance_mi": 1.3,
      "metros": [
        {
          "code": "16740",
          "name": "Charlotte-Concord-Gastonia, NC-SC",
          "type": "metropolitan",
          "share_percent": 100
        }
      ]
    },
    {
      "postal": "28203",
      "city": "Charlotte",
      "state": "NC",
      "country": "US",
      "distance": 2.4,
      "distance_mi": 1.5,
      "metros": [
        {
          "code": "16740",
          "name": "Charlotte-Concord-Gastonia, NC-SC",
          "type": "metropolitan",
          "share_percent": 100
        }
      ]
    }
  ],
  "metros": [
    {
      "code": "16740",
      "name": "Charlotte-Concord-Gastonia, NC-SC",
      "type": "metropolitan",
      "share_percent": 100
    }
  ]
}

Response fields

postalLink to postalstring
Origin postal code
countryLink to countrystring
ISO2 country code
radiusLink to radiusnumber
Search radius
unitLink to unitstring
km or mi
nearbyLink to nearbyarray
Postal codes within the radius, with distance and distance_mi

Included dataCopy link

Population, area, elevation, tax references, nearby postal codes and metropolitan areas. Included automatically on paid plans in API 2.2.

Paid plan fields

elevationLink to elevationnumber or null
Elevation in meters
elevation_ftLink to elevation_ftnumber or null
Elevation in feet
populationLink to populationinteger or null
Population estimate
areaLink to areanumber or null
Total area in km² (null when the source has no water split)
land_areaLink to land_areanumber or null
Land area in km² (null where the source has none)
water_areaLink to water_areanumber or null
Water area in km² (null where the source has none)
currencyLink to currencystring or null
ISO currency code for the country
tax.nameLink to tax.namestring 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
tax.rateLink to 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
tax.rate_stateLink to tax.rate_statenumber or null
State piece of the combined rate, percent. Null when unavailable or not applicable
tax.rate_countyLink to tax.rate_countynumber or null
County piece of the combined rate, percent. Null when unavailable or not applicable
tax.rate_cityLink to tax.rate_citynumber or null
City piece of the combined rate, percent. Null when unavailable or not applicable
tax.rate_specialLink to tax.rate_specialnumber or null
Special district piece of the combined rate, percent. Null when unavailable or not applicable
neighborsLink to neighborsarray
Short list of surrounding postal codes (like country borders)
metrosLink to 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_percent (null last), then code. Percentages are not renormalized.
metros[].codeLink to metros[].codestring
Five-digit CBSA code
metros[].nameLink to metros[].namestring
Metropolitan or micropolitan statistical area name
metros[].typeLink to metros[].typestring
metropolitan or micropolitan
metros[].share_percentLink to metros[].share_percentnumber or null
Percentage of all addresses in the ZIP associated with this area, from 0 to 100; 100 means all addresses. Decimal values are supported; null when unknown
property_taxLink to property_taxobject or null
Current median annual real-estate tax payable on owner-occupied housing; null when missing, censored or unsupported. An area estimate, not a percentage or individual property bill
property_tax.annual_medianLink to property_tax.annual_medianinteger
Median annual amount in currency

Display languageCopy link

Pass lang with a language tag such as fr, pt-BR, or zh-Hant. Existing country_name and separately sourced state or county names when available, including nested results. Postal city text keeps its source spelling.

Omitting lang preserves the original response. Codes, IDs, numeric facts and native-name fields stay unchanged. Missing translations keep their existing source value; unknown values stay null. A preserved name_local may equal the translated name.

Send a chosen browser preference explicitly, for example { lang: navigator.language } in your JavaScript SDK options. The API does not read Accept-Language automatically. Unsupported regions fall back to their supported base language; unsupported languages or scripts use English. Empty, invalid or repeated tags return 400.

Content-Language identifies languages used in translated display fields and known English fallbacks. Display language is available on API 2.1.0; requests selecting frozen 1.0.0 retain their original contract. See API versions.

33 display language choices

Language tagLanguage
enEnglish
arالعربية
cacatalà
hrhrvatski
csčeština
dadansk
nlNederlands
fisuomi
frfrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
humagyar
idIndonesia
ititaliano
ja日本語
ko한국어
msMelayu
nbnorsk bokmål
plpolski
ptportuguês
roromână
ruрусский
zh-Hans简体中文
skslovenčina
esespañol
svsvenska
thไทย
zh-Hant繁體中文
trTürkçe
ukукраїнська
viTiếng Việt