API Documentation
All endpoints are free, read-only, and return JSON. Base URL: https://easyzipcodes.com
ZIP Code Lookup
GET /api/v1/zip/<zipcode>
Returns data for a single 5-digit ZIP code.
Example
curl https://easyzipcodes.com/api/v1/zip/90210Response fields
| Field | Type | Description |
|---|---|---|
| zip | string | 5-digit ZIP code |
| city | string | Primary city name |
| state | string | 2-letter state abbreviation |
| state_name | string | Full state name |
| county | string|null | County name |
| lat | number | Centroid latitude |
| lng | number | Centroid longitude |
| bbox | object|null | Bounding box (north/south/east/west) |
| poi | object | POI category counts (coffee, grocery, gas, etc.) |
| brands | object | National-chain counts (up to 25), properly cased and variant-merged — e.g. {"Starbucks": 7, "McDonald's": 3}. Local one-offs are omitted. For the full raw dataset, use the CSV download. |
| key_places | array | Up to 10 notable named places (parks, museums, historic sites, …) in and around the ZIP, from OpenStreetMap. Each entry has name, category, lat, lng, wikidata, wikipedia_url. Each entry also has in_zip (true when confirmed inside the ZIP; false for nearby places). |
| about | object|null | Wikipedia lead extract for the ZIP’s city: title, extract, source_url, license, attribution. |
Licensing: everything except about is unencumbered (ODbL facts / public domain / CC0 Wikidata ids). The about object’s text comes from Wikipedia and is licensed CC BY-SA 4.0 — consumers redistributing it must attribute Wikipedia contributors.
Search
GET /api/v1/search?q=<query>
Search by ZIP prefix, city, county, or state — e.g. 90210,
Beverly Hills, Cook County, IL, or Illinois.
Tolerant of minor typos. Returns up to 20 results.
Example
curl "https://easyzipcodes.com/api/v1/search?q=Beverly+Hills"Response
Array of objects with zip, city, state.
Nearby ZIP Codes
GET /api/v1/near?lat=<lat>&lng=<lng>&radius_km=<km>
Returns ZIP codes whose centroid lies within radius_km of the
point, nearest first. Distance is the great-circle (haversine) distance in
kilometers; for miles, multiply by 0.621371.
Example
curl "https://easyzipcodes.com/api/v1/near?lat=34.09&lng=-118.41&radius_km=10"Parameters
| Param | Type | Description |
|---|---|---|
| lat | number | Required. Latitude, -90 to 90. |
| lng | number | Required. Longitude, -180 to 180. |
| radius_km | number | Required. Search radius in km (> 0, capped at 100). |
| limit | number | Optional. Max results, 1–100 (default 20). |
Response
Array of objects with zip, city, state,
and distance_km (rounded to 2 decimals), sorted nearest-first.
Returns [] when nothing is in range, and 400 with
{"error", "code": "invalid_params"} for missing / out-of-range params.
Rate Limits
60 requests per minute per IP. The X-RateLimit-* headers are present on rate-limited responses.