Examples

Request Examples

Ready-to-run snippets for every endpoint. Replace YOUR_API_KEY with your key from the dashboard.

ZIP Code Lookup

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

cURL
curl https://apibarn.com/v1/zipcode/api/zip/90210 \
  -H "x-api-key: YOUR_API_KEY"
JavaScript
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.

cURL
# 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.

cURL
# 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.

cURL
# 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.

cURL
# 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 (requests)

Look up a ZIP and find nearby ZIPs using the requests library.

Python
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
curl https://apibarn.com/v1/zipcode/api/stats \
  -H "x-api-key: YOUR_API_KEY"