API Documentation

The ZipCodesToGo API gives you instant access to 42,000+ US ZIP codes — city, state, county, lat/lng, timezone and more. Every request is served from memory with sub-millisecond response times.

Overview

Base URL: https://api.zipcodestogo.com
Format: All responses are JSON · Version: v1

Authentication

All endpoints require an API key passed in the X-Api-Key request header.

Example request

curl https://api.zipcodestogo.com/v1/zip/90210 \
     -H "X-Api-Key: zcg_your_key_here"

Don't have a key? Get one free →

Plans & Rate Limits

Daily call limits reset at midnight UTC. Exceeding your limit returns a 429 response.

Plan	Daily Limit	Price	Radius Search	Bulk Export
Free	100 calls	$0	—	—
Basic	5,000 calls	$19/mo	✓	—
Pro	50,000 calls	$39/mo	✓	—
Enterprise	Unlimited	$89/mo	✓	✓

Subscribe or upgrade your plan →

Endpoints

GET /v1/zip/{zipcode} Look up a ZIP code All plans

Returns all data for a single US ZIP code including city, state, county, coordinates, timezone, FIPS codes, and area code.

Parameters

Name	Type	Required	Description
zipcode	string	required	5-digit US ZIP code (e.g. `90210`). Leading zeros are handled automatically.

Request

curl https://api.zipcodestogo.com/v1/zip/90210 \
     -H "X-Api-Key: zcg_your_key_here"

Response

{
  "zip": "90210",
  "data": {
    "city":        "Beverly Hills",
    "state":       "CA",
    "county":      "Los Angeles",
    "lat":         34.0901,
    "lng":         -118.4065,
    "timezone":    "8",
    "dst":         "Y",
    "county_fips": "037",
    "state_fips":  "06",
    "area_code":   "310/424"
  }
}

GET /v1/city/{state}/{city} Find ZIP codes by city All plans

Returns all ZIP codes for a given city and state. Many cities have multiple ZIP codes — this endpoint returns all of them.

Parameters

Name	Type	Required	Description
state	string	required	2-letter state abbreviation (case-insensitive). E.g. `CA`, `TN`, `NY`
city	string	required	City name (case-insensitive). Use URL encoding for spaces: `Beverly%20Hills`

Request

curl https://api.zipcodestogo.com/v1/city/CA/Beverly%20Hills \
     -H "X-Api-Key: zcg_your_key_here"

Response

{
  "count": 1,
  "results": [
    {
      "zip":    "90210",
      "city":   "Beverly Hills",
      "state":  "CA",
      "county": "Los Angeles",
      "lat":    34.0901,
      "lng":    -118.4065
    }
  ]
}

GET /v1/radius Find ZIP codes within a radius Basic+

Returns all ZIP codes within a given radius of a lat/lng point. Results are sorted by distance, nearest first. Useful for dealer locators, delivery zones, and proximity searches.

⚠️ Requires Basic plan or above. Free plan users will receive a 403 error.

Parameters

Name	Type	Required	Description
lat	float	required	Latitude of center point (e.g. `36.1627`)
lng	float	required	Longitude of center point (e.g. `-86.7816`)
miles	float	optional	Search radius in miles. Default: `10`. Maximum: `100`

Request

curl "https://api.zipcodestogo.com/v1/radius?lat=36.1627&lng=-86.7816&miles=25" \
     -H "X-Api-Key: zcg_your_key_here"

Response

{
  "count": 42,
  "center": { "lat": 36.1627, "lng": -86.7816 },
  "radius_miles": 25,
  "results": [
    {
      "zip":            "37201",
      "distance_miles": 0.84,
      "city":           "Nashville",
      "state":          "TN",
      "county":         "Davidson",
      "lat":            36.1748,
      "lng":            -86.7816
    }
  ]
}

GET /v1/bulk/export Export full database Enterprise only

Download the complete ZIP code database as a CSV or JSON file. Optionally filter by state. The response is a file attachment.

⚠️ Requires Enterprise plan. Returns a 403 error on all other plans.

Parameters

Name	Type	Required	Description
format	string	optional	Output format: `csv` (default) or `json`
state	string	optional	Filter by 2-letter state code (e.g. `TN`). Omit for all states.

Examples

# Full CSV export (all 42,000+ ZIPs)
curl "https://api.zipcodestogo.com/v1/bulk/export" \
     -H "X-Api-Key: zcg_your_key_here" \
     -o zipcodes.csv

# Tennessee only, JSON format
curl "https://api.zipcodestogo.com/v1/bulk/export?state=TN&format=json" \
     -H "X-Api-Key: zcg_your_key_here" \
     -o zipcodes_tn.json

GET /v1/me Check API key & usage All plans

Returns your current plan, daily call limit, and usage count for today. Call limits reset at midnight UTC.

Request

curl https://api.zipcodestogo.com/v1/me \
     -H "X-Api-Key: zcg_your_key_here"

Response

{
  "email":       "[email protected]",
  "plan":        "pro",
  "daily_limit": 50000,
  "usage_today": 1247,
  "key_prefix":  "zcg_abc123",
  "member_since":"2026-04-14"
}

Response Fields

Field	Type	Description
city	string	Primary city name in mixed case
state	string	2-letter state abbreviation (e.g. `CA`)
county	string	County name in mixed case
lat	float	Latitude in decimal degrees
lng	float	Longitude in decimal degrees
timezone	string	GMT offset (e.g. `5` = UTC-5 = Eastern)
dst	string	Daylight saving observed: `Y` or `N`
county_fips	string	3-digit county FIPS code
state_fips	string	2-digit state FIPS code
area_code	string	Phone area code(s). Multiple codes separated by `/`

Error Codes

Status	Meaning
200	Success
400	Bad request — invalid parameters
401	Missing or invalid API key
403	Your plan doesn't include this endpoint
404	ZIP code or city not found
409	Email already has a free key
429	Daily rate limit exceeded — resets at midnight UTC
500	Server error — contact support

Coverage

The ZipCodesToGo database covers 42,000+ ZIP codes across all 50 US states, Washington DC, Puerto Rico, US Virgin Islands, Guam, American Samoa, and military addresses (APO/FPO). Data is updated regularly to reflect USPS changes.

Need the raw database in Excel, CSV, or Access format? Download it as a one-time purchase →