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.

Core gives place identity, coordinates and timezone. Paid deep adds population, area, elevation, nearby codes, metro areas and available tax references. city, state_name, and district_name read in English or an official romanization when a trusted source has one. Native siblings (city_local, state_name_local, district_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.

Lookup

GET

api.parseapi.com/postal/{code}

Postal lookup. ?country= when the code collides

Explore

Parameters 4

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

deepboolean · query · optional

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

Example

SDK quickstart

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("10001", { country: "US", deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "postal": "10001",
  "city": "New York",
  "city_local": null,
  "district": "36061",
  "district_name": "New York",
  "district_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",
  "localities": null,
  "deep": {
    "elevation": 20,
    "elevation_ft": 66,
    "population": 30511,
    "area": 1.62,
    "land_area": 1.62,
    "water_area": 0,
    "currency": "USD",
    "tax": "Sales tax",
    "tax_rate": 8.875,
    "tax_rate_state": 4,
    "tax_rate_county": null,
    "tax_rate_city": 4.5,
    "tax_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
      }
    ]
  }
}

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

SDK quickstart

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("2000", { country: "AU", deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "postal": "2000",
  "city": null,
  "city_local": null,
  "district": null,
  "district_name": null,
  "district_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",
  "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"
    }
  ],
  "deep": {
    "elevation": 69,
    "elevation_ft": 226,
    "population": 27936,
    "area": null,
    "land_area": 4.29,
    "water_area": null,
    "currency": "AUD",
    "tax": null,
    "tax_rate": null,
    "tax_rate_state": null,
    "tax_rate_county": null,
    "tax_rate_city": null,
    "tax_rate_special": null,
    "property_tax": null,
    "neighbors": [
      "2011",
      "2061",
      "2009",
      "2010",
      "2007",
      "2060",
      "2027",
      "2041"
    ],
    "metros": null
  }
}

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
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
typestring or null: US or qualified territory/FAS ZIP type: standard, po_box, unique, military or null
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

Metro areas

deep.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.

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

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

Distance

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

api.parseapi.com/postal/{code}/distance/{other}

Straight-line distance in miles and km

Explore

Parameters 5

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

Length: 2 to 64 characters

deepboolean · query · optional

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

SDK quickstart

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal.distance("28202", "10001", { country: "US", deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "country": "US",
  "from": {
    "postal": "28202",
    "city": "Charlotte",
    "deep": {
      "metros": [
        {
          "code": "16740",
          "name": "Charlotte-Concord-Gastonia, NC-SC",
          "type": "metropolitan",
          "share_percent": 100
        }
      ]
    }
  },
  "to": {
    "postal": "10001",
    "city": "New York",
    "deep": {
      "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

countrystring: ISO2 country code
fromobject: Origin postal code and city
toobject: Destination postal code and city
distancenumber: Straight-line distance in km
distance_minumber: Straight-line distance in miles

Nearby

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

GET

api.parseapi.com/postal/{code}/nearby

Nearby postal codes. Default unit=km

Explore

Parameters 6

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

Length: 2 to 64 characters

deepboolean · query · optional

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

SDK quickstart

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal.nearby("28202", { country: "US", radius: 3, deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "postal": "28202",
  "country": "US",
  "radius": 3,
  "unit": "km",
  "nearby": [
    {
      "postal": "28280",
      "city": "Charlotte",
      "state": "NC",
      "country": "US",
      "distance": 0.1,
      "distance_mi": 0.1,
      "deep": {
        "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,
      "deep": {
        "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,
      "deep": {
        "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,
      "deep": {
        "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,
      "deep": {
        "metros": [
          {
            "code": "16740",
            "name": "Charlotte-Concord-Gastonia, NC-SC",
            "type": "metropolitan",
            "share_percent": 100
          }
        ]
      }
    }
  ],
  "deep": {
    "metros": [
      {
        "code": "16740",
        "name": "Charlotte-Concord-Gastonia, NC-SC",
        "type": "metropolitan",
        "share_percent": 100
      }
    ]
  }
}

Response fields

postalstring: Origin postal code
countrystring: ISO2 country code
radiusnumber: Search radius
unitstring: km or mi
nearbyarray: Postal codes within the radius, with distance and distance_mi

Deep

?deep=true Population, area, elevation, tax references, nearby postal codes and metropolitan areas. Included on paid plans.

SDK quickstart

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("10001", { country: "US", deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response

{
  "postal": "10001",
  "city": "New York",
  "city_local": null,
  "district": "36061",
  "district_name": "New York",
  "district_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",
  "localities": null,
  "deep": {
    "elevation": 20,
    "elevation_ft": 66,
    "population": 30511,
    "area": 1.62,
    "land_area": 1.62,
    "water_area": 0,
    "currency": "USD",
    "tax": "Sales tax",
    "tax_rate": 8.875,
    "tax_rate_state": 4,
    "tax_rate_county": null,
    "tax_rate_city": 4.5,
    "tax_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
      }
    ]
  }
}

Deep fields

deep.elevationnumber or null: Elevation in meters
deep.elevation_ftnumber or null: Elevation in feet
deep.populationinteger or null: Population estimate
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_percent (null last), then code. Percentages 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[].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
deep.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
deep.property_tax.annual_medianinteger: Median annual amount in currency

Display language

Pass lang with a language tag such as fr, pt-BR, or zh-Hant. Existing country_name and separately sourced state or district 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. This option follows the current API contract. Requests selecting frozen 1.0.0 retain that contract. Select API 2.0.0 to use display language.

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

Build with Postal

All tutorials →

Questions? Email

Postal API

Lookup#

Metro areas#

Distance#

Nearby#

Deep#

Display language#

Build with Postal

Lookup

Metro areas

Distance

Nearby

Deep

Display language