API Documentation

ZipCodeFacts API

Complete reference for integrating US ZIP code demographics, housing data, and location information into your applications.

Quick Start

Get API Key

Add to Header

Include your API key in the Authorization header.

Authorization: Bearer zcf_xxx

Make Requests

Start fetching ZIP code data from our endpoints.

/api/v1/zip/90210

Authentication

All API requests require authentication via an API key. Include your key in the request header:

curl -X GET "https://zipcodefacts.com/api/v1/zip/90210"   -H "Authorization: Bearer zcf_your_api_key_here"

Alternatively, pass the key as a query parameter (not recommended for production):

GET /api/v1/zip/90210?api_key=zcf_your_api_key_here

Endpoints

GET

/api/v1/zip/{zipCode}

Get detailed information for a specific ZIP code.

Parameters

Name	Type	Description
`zipCode`	string	5-digit US ZIP code (e.g., "90210")

Example Response

{
  "zipCode": "90210",
  "city": "Beverly Hills",
  "state": "CA",
  "county": "Los Angeles",
  "location": {
    "latitude": 34.0901,
    "longitude": -118.4065
  },
  "demographics": {
    "population": 21741,
    "medianHouseholdIncome": 153042,
    "medianHomeValue": 2500000,
    "areaClassification": "Urban",
    "landAreaSqMiles": 5.71
  },
  "housing": {
    "zillowHomeValueIndex": 3250000,
    "appreciation1Year": 4.2,
    "appreciation5Year": 45.3,
    "marketTrend": "Stable"
  },
  "metadata": {
    "dataSource": "US Census Bureau ACS 2023",
    "lastUpdated": "2024-01-15T00:00:00Z"
  }
}

GET

/api/v1/city/{cityStateKey}

Get city data with all associated ZIP codes.

Parameters

Name	Type	Description
`cityStateKey`	string	City and state in format "city-name-st" (e.g., "los-angeles-ca")

GET

/api/v1/search

Search for ZIP codes and cities.

Query Parameters

Name	Type	Description
`q`	string	Search query (min 2 characters)
`limit`	integer	Max results (1-100, default 20)
`state`	string	Filter by state (2-letter code)

POST

/api/v1/bulk

Pro+

Bulk lookup for multiple ZIP codes (up to 100 per request).

Request Body

{
  "zipCodes": ["90210", "10001", "60601"]
}

Rate Limits

Tier	Daily Limit	Monthly Limit
Free	100	3,000
Starter	1,000	10,000
Pro	10,000	100,000
Enterprise	Custom	Custom

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining

Error Codes

Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Tier doesn't have access to endpoint
`404`	Not Found - ZIP code or city not found
`429`	Rate Limit Exceeded

Ready to Start?

Get your free API key and start building.