Postal API

A postal or ZIP. City, state, area, coordinates. Country when the code collides.

Look up a postal or ZIP code. A code that exists in exactly one covered country resolves bare: /postal/SW1A 1AA, /postal/100-0001. Five-digit codes often collide across the US, France, and Mexico. That is a 404 asking for ?country=, never a guessed US ZIP. ?country= takes ISO2, ISO3, or a name.

Place, coordinates, population, land and water area, timezone, elevation in feet and meters, and a short list of neighboring ZIPs come back in core. US rows also carry combined sales tax when the state is sourced. 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

curl "https://api.parseapi.com/postal/33139?country=US" \
  -H "X-API-Key: YOUR_API_KEY"

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

curl "https://api.parseapi.com/postal/53202?country=US" \
  -H "X-API-Key: YOUR_API_KEY"

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

curl "https://api.parseapi.com/postal/SW1A 1AA" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "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,
  "elevation": 17,
  "elevation_ft": 56,
  "population": 4,
  "area": null,
  "land_area": null,
  "water_area": null,
  "timezone": "Europe/London",
  "currency": "GBP",
  "tax": null,
  "tax_rate": null,
  "tax_rate_state": null,
  "tax_rate_county": null,
  "tax_rate_city": null,
  "tax_rate_special": null,
  "neighbors": [
    "SW1E6LA",
    "SW1E6AY",
    "SW1E6NR",
    "SW1E6JP",
    "SW1E6LD",
    "SW1E6LB",
    "SW1E6NP",
    "SW1E6DU"
  ]
}

curl "https://api.parseapi.com/postal/100-0001" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "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,
  "elevation": 28,
  "elevation_ft": 92,
  "population": null,
  "area": null,
  "land_area": null,
  "water_area": null,
  "timezone": "Asia/Tokyo",
  "currency": "JPY",
  "tax": null,
  "tax_rate": null,
  "tax_rate_state": null,
  "tax_rate_county": null,
  "tax_rate_city": null,
  "tax_rate_special": null,
  "neighbors": [
    "1000004",
    "1000000",
    "1020072",
    "1000011",
    "1010032",
    "1020082",
    "1010047",
    "1006890"
  ]
}

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
elevation: Elevation in meters
elevation_ft: Elevation in feet
population: Population estimate
area: Total area in km² (null when the source has no water split)
land_area: Land area in km² (null where the source has none)
water_area: Water area in km² (null where the source has none)
timezone: Timezone identifier
currency: ISO currency code for the country
tax: Levy name from the state (Sales tax, General excise tax). Null when the state levies none, or outside the US
tax_rate: Combined highest sales tax rate in this ZIP, percent. 0 where the state levies none. Null when unsourced
tax_rate_state: State piece of the combined rate, percent. Null when that level does not apply
tax_rate_county: County piece of the combined rate, percent. Null when that level does not apply
tax_rate_city: City piece of the combined rate, percent. Null when that level does not apply
tax_rate_special: Special district piece of the combined rate, percent. Null when that level does not apply
neighbors: Short list of surrounding postal codes (like country borders)

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

curl "https://api.parseapi.com/postal/28202/distance/10001?country=US" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "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. The core lookup already includes a short neighbors list. Use this 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

curl "https://api.parseapi.com/postal/28202/nearby?country=US&radius=40" \
  -H "X-API-Key: YOUR_API_KEY"

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

Questions? Email