Postal API

A postal or ZIP, city, state, coordinates, population. Readable names plus native siblings when they differ.

Look up a postal or ZIP code. Country is required. Place, coordinates, population, timezone, elevation in feet and meters, and a short list of neighboring ZIPs come back in core. 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}?country={iso2}

Postal lookup. ?country= required

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",
  "latitude": 25.7823,
  "longitude": -80.1375,
  "elevation": 1,
  "elevation_ft": 3,
  "population": 38000,
  "timezone": "America/New_York",
  "currency": "USD",
  "neighbors": [
    "33140",
    "33141",
    "33154",
    "33160",
    "33109"
  ]
}

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
latitude: Approximate latitude
longitude: Approximate longitude
elevation: Elevation in meters
elevation_ft: Elevation in feet
population: Population estimate
timezone: Timezone identifier
currency: ISO currency code for the country
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}?country={iso2}

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?country={iso2}&radius={n}

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