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.

Lookup

GET

api.parseapi.com/postal/{code}

Postal lookup. ?country= when the code collides

Explore

Parameters 3

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.
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("33139", { country: "US" });
console.log(result);

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

Example response

{
  "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"
}

Deep examples run with your own key. Check this API’s included units and pricing before running.

SDK quickstart

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

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

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

Example response

{
  "postal": "53202",
  "city": "Milwaukee",
  "state": "WI",
  "state_name": "Wisconsin",
  "deep": {
    "tax": "Sales tax",
    "tax_rate": 7.9,
    "tax_rate_state": 5,
    "tax_rate_county": 0.9,
    "tax_rate_city": 2,
    "tax_rate_special": null,
    "property_tax": null
  }
}

SDK quickstart

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("SW1A 1AA");
console.log(result);

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

Example response

{
  "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"
}

SDK quickstart

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.postal("100-0001", { country: "JP" });
console.log(result);

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

Example response

{
  "postal": "1000001",
  "city": "Chiyoda Ku",
  "city_local": "千代田区",
  "district": null,
  "district_name": "Chiyoda",
  "district_name_local": "千代田",
  "state": "13",
  "state_name": "Tokyo To",
  "state_name_local": "東京都",
  "country": "JP",
  "country_name": "Japan",
  "latitude": 35.694,
  "longitude": 139.7536,
  "timezone": "Asia/Tokyo"
}

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

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 four address shares. A ZIP may be associated with several areas.

share is the fraction of all addresses in the ZIP. residential_share, business_share, and other_share each use that address category as their denominator. Fractions range from 0 to 1 and stay null when unknown or the ZIP has no addresses in that category. A zero means the category has addresses, with none associated with this area. Entries sort by descending share, unknown shares last, then code. Shares 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 4

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.
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" });
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"
  },
  "to": {
    "postal": "10001",
    "city": "New York"
  },
  "distance": 875.8,
  "distance_mi": 544.2
}

Response fields

country: ISO2 country code
from: Origin postal code and city
to: Destination postal code and city
distance: Straight-line distance in km
distance_mi: 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 5

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

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: 40 });
console.log(result);

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

Example response

{
  "postal": "28202",
  "country": "US",
  "radius": 40,
  "unit": "km",
  "nearby": [
    {
      "postal": "28203",
      "city": "Charlotte",
      "state": "NC",
      "country": "US",
      "distance": 2.3,
      "distance_mi": 1.4
    },
    {
      "postal": "28204",
      "city": "Charlotte",
      "state": "NC",
      "country": "US",
      "distance": 3.4,
      "distance_mi": 2.1
    },
    {
      "postal": "28205",
      "city": "Charlotte",
      "state": "NC",
      "country": "US",
      "distance": 4.8,
      "distance_mi": 3
    },
    // ... 64 more
  ]
}

Response fields

postal: Origin postal code
country: ISO2 country code
radius: Search radius
unit: km or mi
nearby: 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.

Deep examples run with your own key. Check this API’s included units and pricing before running.

SDK quickstart

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

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

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

Example response

{
  "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",
  "deep": {
    "elevation": 6,
    "elevation_ft": 20,
    "population": 33753,
    "population_period": null,
    "area": 15.3,
    "land_area": 7.21,
    "water_area": 8.09,
    "currency": "USD",
    "tax": "Sales tax",
    "tax_rate": null,
    "tax_rate_state": null,
    "tax_rate_county": null,
    "tax_rate_city": null,
    "tax_rate_special": null,
    "property_tax": null,
    "neighbors": [
      "33132",
      "33109",
      "33131",
      "33137",
      "33140",
      "33101",
      "33128",
      "33130"
    ]
  }
}

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

Build with Postal

All tutorials →

Questions? Email

Postal API

Lookup#

Metro areas#

Distance#

Nearby#

Deep#

Build with Postal

Lookup

Metro areas

Distance

Nearby

Deep