API Documentation

Simple REST API. JSON responses. Pass your API key via header or query parameter.

✓ JSON ✓ REST ✓ Rate Limited ✓ Cached

🔑 Authentication

All API requests require an API key. Pass it in one of two ways:

Header (Recommended)

X-API-Key: tzc_your_api_key

Query Parameter

?api_key=tzc_your_api_key

Base URL

https://api.thezipcodes.com/api/v1/

GET /api/v1/zipcode/{zip_code}/ ZIP Code Lookup

Returns city, state, state code, country codes, latitude, and longitude for a ZIP code. Results are cached in Redis for 1 hour.

Path Parameters

Name	Type	Required	Description
zip_code	string	Yes	ZIP or postal code

Query Parameters

Name	Default	Description
country	US	ISO 3166-1 alpha-2 country code

Response Fields

Field	Description
zip_code	The ZIP / postal code
city	City name
state	Full state / province name
state_code	ISO 3166-2 state code (e.g. `NY`)
country	ISO 3166-1 alpha-2 (e.g. `US`)
country_code_2	ISO 3166-1 alpha-2 country code
country_code_3	ISO 3166-1 alpha-3 country code (e.g. `USA`)
latitude	Decimal degrees, WGS84
longitude	Decimal degrees, WGS84

Example Response 200 OK

{
  "success": true,
  "data": {
    "zip_code":        "10001",
    "city":            "New York",
    "state":           "New York",
    "state_code":      "NY",
    "country":         "US",
    "country_code_2":  "US",
    "country_code_3":  "USA",
    "latitude":        40.748817,
    "longitude":       -73.985428
  }
}

cURL Example

curl -X GET "https://api.thezipcodes.com/api/v1/zipcode/10001/?country=US" \
     -H "X-API-Key: tzc_your_api_key_here"

GET /api/v1/distance/ Distance Calculation

Calculate the great-circle distance (Haversine formula) between two ZIP codes. Returns distance in both kilometres and miles.

Query Parameters

Name	Required	Description
source_zip	Yes	Origin ZIP code
destination_zip	Yes	Destination ZIP code
country	No	ISO country code (default: US)

Example Response 200 OK

{
  "success": true,
  "data": {
    "source_zip":             "10001",
    "source_city":            "New York",
    "source_state":           "New York",
    "source_state_code":      "NY",
    "destination_zip":        "90210",
    "destination_city":       "Beverly Hills",
    "destination_state":      "California",
    "destination_state_code": "CA",
    "distance_km":            3940.3672,
    "distance_miles":         2448.3821,
    "country":                "US",
    "country_code_2":         "US",
    "country_code_3":         "USA"
  }
}

cURL Example

curl -X GET "https://api.thezipcodes.com/api/v1/distance/?source_zip=10001&destination_zip=90210" \
     -H "X-API-Key: tzc_your_api_key_here"

Error Responses

All errors return a consistent JSON envelope:

{
  "success": false,
  "error": {
    "code":    "error_code",
    "message": "Human-readable description"
  }
}

HTTP Status	Code	Meaning
401	missing_api_key	No API key provided
401	invalid_api_key	API key is invalid or revoked
404	zipcode_not_found	ZIP code not in our database
429	rate_limit_exceeded	Monthly request limit reached
500	internal_server_error	Unexpected server error

📊 Rate Limit Headers

Every API response includes these headers so you can monitor your usage:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset:     2024-01-15