US ZIP Code API — Endpoints Reference

Authentication

Pass your API key in the x-api-key request header on every call. Keys are provisioned instantly at signup — no credit card required for the free tier.

Request header

x-api-key: YOUR_API_KEY

Don't have a key? Sign up free — 10,000 requests/month included.

Stats

Returns high-level dataset statistics: total ZIP codes loaded and number of distinct states covered.

GET/api/statsDataset statistics — total ZIPs and state coverage.

cURL

curl https://apibarn.com/v1/zipcode/api/stats \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "totalZips": 42129,
  "totalStates": 51
}

ZIP Lookup

Returns full detail for a single US ZIP code: city, state, county, FIPS code, and precise latitude/longitude.

GET/api/zip/:zipSingle ZIP code lookup.

Parameter	In	Type	Description
`zip`	path	string	5-digit US ZIP code

cURL

curl https://apibarn.com/v1/zipcode/api/zip/90210 \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "zip": "90210",
  "city": "Beverly Hills",
  "stateCode": "CA",
  "stateName": "California",
  "county": "Los Angeles",
  "countyFips": "06037",
  "lat": 34.0901,
  "lng": -118.4065,
  "lastUpdated": "2026-01-01T00:00:00.000Z"
}

Nearby ZIPs

Returns ZIP codes within a radius of the given ZIP code, sorted by distance ascending. Uses haversine distance for accurate geodesic calculations.

GET/api/zip/:zip/nearbyZIPs within a given radius of a center ZIP.

Parameter	In	Type	Default	Description
`zip`	path	string	—	Center ZIP code
`radiusMiles`	query	number	25	Search radius in miles (max 200)
`limit`	query	number	50	Max results to return (max 200)

cURL

curl "https://apibarn.com/v1/zipcode/api/zip/90210/nearby?radiusMiles=10&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "center": { "zip": "90210", "lat": 34.0901, "lng": -118.4065 },
  "radiusMiles": 10,
  "results": [
    {
      "zip": "90211",
      "city": "Beverly Hills",
      "stateCode": "CA",
      "county": "Los Angeles",
      "lat": 34.0635,
      "lng": -118.3964,
      "distanceMiles": 2.1
    }
  ]
}

Search

Full-text search across city, county, and state. Supports field-specific filters and pagination.

GET/api/searchSearch by city, county, state, or keyword.

Parameter	In	Type	Description
`q`	query	string	General keyword (matches city, county, or state name)
`city`	query	string	Filter by city name (case-insensitive)
`state`	query	string	Filter by 2-letter state code (e.g. `CA`)
`county`	query	string	Filter by county name
`limit`	query	number	Max results per page (default 20, max 100)
`offset`	query	number	Pagination offset (default 0)

cURL

curl "https://apibarn.com/v1/zipcode/api/search?city=Spring&state=TX" \
  -H "x-api-key: YOUR_API_KEY"

States

Returns all 50 US states (plus DC) with the count of ZIP codes per state. Useful for populating dropdowns and coverage maps.

GET/api/statesAll states with ZIP code count.

cURL

curl https://apibarn.com/v1/zipcode/api/states \
  -H "x-api-key: YOUR_API_KEY"

Response

[
  { "stateCode": "CA", "stateName": "California", "zipCount": 2647 },
  { "stateCode": "TX", "stateName": "Texas",      "zipCount": 2148 }
]

State ZIPs

Returns all ZIP codes for a given 2-letter US state code. Results are paginated.

GET/api/states/:state/zipcodesPaginated ZIP codes for a given state.

Parameter	In	Type	Default	Description
`state`	path	string	—	2-letter state code (e.g. `NY`)
`limit`	query	number	100	Max results per page
`offset`	query	number	0	Pagination offset

cURL

curl "https://apibarn.com/v1/zipcode/api/states/CA/zipcodes?limit=50&offset=0" \
  -H "x-api-key: YOUR_API_KEY"

City ZIPs

Returns all ZIP codes for a given city name. Optionally restrict to a single state to disambiguate common names like Portland or Springfield.

GET/api/city/:cityAll ZIPs for a city, optionally filtered by state.

Parameter	In	Type	Description
`city`	path	string	City name (URL-encoded, case-insensitive)
`state`	query	string	Optional 2-letter state code to narrow results

cURL

curl "https://apibarn.com/v1/zipcode/api/city/Portland?state=OR" \
  -H "x-api-key: YOUR_API_KEY"