Skip to content

ZIP9 Data API

Complete API reference for querying CMS ZIP Code to Carrier Locality mappings.

Overview

The ZIP9 Data API provides access to the CMS ZIP Code to Carrier Locality files. This data is essential for determining the correct Medicare pricing locality for a specific geographic location (ZIP code).

Base Path: /api/v1/zip9-data

Authentication: Required for all endpoints (Bearer token or API Key)

Key Concepts

Carrier & Locality

Medicare pricing is based on Carrier Localities. A single state may be divided into multiple localities, or an entire state may be a single locality. - Carrier: The Medicare Administrative Contractor (MAC) code. - Pricing Locality: The specific geographic area code within the carrier's jurisdiction.

Rural Indicators

Some areas receive bonus payments or different treatments based on rural status: - Blank: Urban / Non-Rural - R: Rural - B: Super Rural (Bonus area)

Endpoints

Search ZIP9 Data

Search and filter ZIP code mappings with pagination.

Endpoint: GET /zip9-data/search

Query Parameters:

Parameter Type Required Description
zip_code string No Filter by ZIP code (partial match supported, e.g., "902")
state string No Filter by 2-letter state code (e.g., "CA")
carrier string No Filter by carrier code
pricing_locality string No Filter by pricing locality code
rural_indicator string No Filter by indicator (R, B, or leave blank for urban)
effective_date string No Filter records active on date (YYYY-MM-DD)
skip integer No Number of records to skip (default: 0)
limit integer No Maximum records to return (default: 50)

Response:

{
  "data": [
    {
      "id": 54321,
      "zip_code": "90210",
      "state": "CA",
      "carrier": "01112",
      "pricing_locality": "01",
      "rural_indicator": "",
      "effective_date": "2025-01-01",
      "end_date": "2025-03-31",
      "record_hash": "abc123hash..."
    }
  ],
  "count": 1
}

Example Requests:

# Search for specific ZIP code
curl -H "Authorization: YOUR_API_KEY" \
  "https://api.example.com/api/v1/zip9-data/search?zip_code=90210"

# Find all Rural areas in Texas
curl -H "Authorization: YOUR_API_KEY" \
  "https://api.example.com/api/v1/zip9-data/search?state=TX&rural_indicator=R"

Use Cases: - Pricing Determination: Map a patient's ZIP code to the correct carrier and pricing_locality to look up GPCI values. - Service Area Validation: Verify if a ZIP code falls within a specific MAC jurisdiction.

Get Record by ID

Retrieve a single ZIP9 data record by its unique database ID.

Endpoint: GET /zip9-data/{record_id}

Path Parameters:

Parameter Type Required Description
record_id integer Yes Unique record ID

Response:

{
  "id": 54321,
  "zip_code": "90210",
  "state": "CA",
  "carrier": "01112",
  "pricing_locality": "01",
  "rural_indicator": "",
  "effective_date": "2025-01-01",
  "end_date": "2025-03-31",
  "record_hash": "abc123hash...",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Lookup Helpers

Helper endpoints to retrieve available values for dropdowns and filters.

Get Available States

Endpoint: GET /zip9-data/lookup/states

Response:

{
  "states": ["AK", "AL", "AR", "AZ", "CA", ...]
}

Get Available Carriers

Get list of carrier codes, optionally filtered by state.

Endpoint: GET /zip9-data/lookup/carriers

Query Parameters:

Parameter Type Required Description
state string No Filter carriers by state

Response:

{
  "carriers": ["01112", "01182", ...]
}

Get Available Localities

Get list of pricing locality codes, optionally filtered by state and carrier.

Endpoint: GET /zip9-data/lookup/localities

Query Parameters:

Parameter Type Required Description
state string No Filter by state
carrier string No Filter by carrier

Response:

{
  "localities": ["01", "02", "99"]
}

Get Statistics

Get summary statistics about the ZIP9 database.

Endpoint: GET /zip9-data/stats/summary

Response:

{
  "total_records": 45000,
  "unique_zip_codes": 32000,
  "unique_states": 53,
  "unique_carriers": 15,
  "unique_localities": 95
}

Common Patterns

ZIP Code Matching

The API supports partial matching on ZIP codes. - Input: 902 -> Returns all ZIPs starting with 902 (e.g., 90210, 90211). - Input: 90210 -> Returns exact matches (and potentially 9-digit extensions if loaded).

Determining Pricing Locality

To find the correct GPCI values for a location: 1. Query GET /zip9-data/search?zip_code=XXXXX. 2. Extract the carrier and pricing_locality from the response. 3. Construct the full locality code: Carrier + Pricing Locality (e.g., 01112 + 01 = 0111201). 4. Use this code to query the PFS Localities API.

Error Handling

Status Code Description
200 Success
400 Invalid parameters
401 Unauthorized
404 Record not found
500 Server error