Request Examples

ZIP Code Lookup

Instant detail for any US ZIP — city, state, county, FIPS, and coordinates.

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

# JavaScript (fetch)
const res = await fetch('https://apibarn.com/v1/zipcode/api/zip/90210', {
  headers: { 'x-api-key': 'YOUR_API_KEY' }
});
const data = await res.json();
console.log(data.city, data.stateCode); // Beverly Hills, CA

Radius Search

Find every ZIP code within a given radius, sorted nearest-first.

# ZIPs within 15 miles of 10001 (Midtown Manhattan)
curl "https://apibarn.com/v1/zipcode/api/zip/10001/nearby?radiusMiles=15&limit=30" \
  -H "x-api-key: YOUR_API_KEY"

Full-Text Search

Search city name, county, and state simultaneously. Supports pagination.

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

# General keyword search with pagination
curl "https://apibarn.com/v1/zipcode/api/search?q=Orange&limit=20&offset=20" \
  -H "x-api-key: YOUR_API_KEY"

State Explorer

List all states or pull every ZIP for a specific state — great for dropdowns and maps.

# All states with ZIP counts
curl https://apibarn.com/v1/zipcode/api/states \
  -H "x-api-key: YOUR_API_KEY"

# All ZIP codes in Florida (first 50)
curl "https://apibarn.com/v1/zipcode/api/states/FL/zipcodes?limit=50&offset=0" \
  -H "x-api-key: YOUR_API_KEY"

City ZIP Codes

Retrieve all ZIPs for a city name. Add a state filter to handle ambiguous names.

# All ZIPs for "Portland" (OR and ME combined)
curl "https://apibarn.com/v1/zipcode/api/city/Portland" \
  -H "x-api-key: YOUR_API_KEY"

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

Python Example

Using the requests library to look up a ZIP and find nearby ZIPs.

import requests

BASE    = "https://apibarn.com/v1/zipcode"
HEADERS = {"x-api-key": "YOUR_API_KEY"}

# Lookup a single ZIP
r = requests.get(f"{BASE}/api/zip/94102", headers=HEADERS)
z = r.json()
print(z["city"], z["stateCode"], z["lat"], z["lng"])
# San Francisco CA 37.7749 -122.4194

# Find nearby ZIPs within 5 miles
r2 = requests.get(f"{BASE}/api/zip/94102/nearby",
                  params={"radiusMiles": 5, "limit": 10},
                  headers=HEADERS)
for item in r2.json()["results"]:
    print(item["zip"], item["distanceMiles"])

Dataset Stats

Check total ZIP codes loaded and state coverage. No parameters required.

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