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
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("10001", { country: "US" });
console.log(result);{
"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.
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("2000", { country: "AU" });
console.log(result);{
"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
import { parseAPI } from '@parseapi/sdk';
const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal.distance("28202", "10001", { country: "US" });
console.log(result);{
"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
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);{
"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
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
- 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 tag | Language |
|---|---|
| en | English |
| ar | العربية |
| ca | català |
| hr | hrvatski |
| cs | čeština |
| da | dansk |
| nl | Nederlands |
| fi | suomi |
| fr | français |
| de | Deutsch |
| el | Ελληνικά |
| he | עברית |
| hi | हिन्दी |
| hu | magyar |
| id | Indonesia |
| it | italiano |
| ja | 日本語 |
| ko | 한국어 |
| ms | Melayu |
| nb | norsk bokmål |
| pl | polski |
| pt | português |
| ro | română |
| ru | русский |
| zh-Hans | 简体中文 |
| sk | slovenčina |
| es | español |
| sv | svenska |
| th | ไทย |
| zh-Hant | 繁體中文 |
| tr | Türkçe |
| uk | українська |
| vi | Tiếng Việt |