API Documentation

Introduction

The ZIP Codes API v2 provides comprehensive postal code data for the United States and Canada. Look up ZIP codes, calculate distances, search by radius, and enrich results with census demographics, political districts, school districts, and more.

Base URL: https://api.zip-codes.com. All API endpoints live under the /v2/ prefix. Responses use a consistent JSON envelope with built-in error handling and credit tracking.

Key Features

• US ZIP & ZIP+4 lookups with demographics, delivery points, and business data
• Canadian FSA & postal code lookups with province-level data
• Radius search with cross-border support (US + Canada)
• Distance calculation between any combination of ZIP codes, FSAs, postal codes, and coordinates
• Opt-in enrichments including ACS demographics, census boundaries, political districts, school districts, timezone, and more
• Five batch routes: up to 250 addresses or 100 items on each other route

Authentication

Get a key and review plans at API pricing. Lookup requests require a valid API key. Health, documentation, OpenAPI, Swagger and Postman are public. Send it in the X-Api-Key header or as Authorization: Bearer:

X-Api-Key header (recommended)

X-Api-Key: your_api_key

Authorization: Bearer

Authorization: Bearer your_api_key

Query parameter (convenience only, e.g. testing in a browser)

GET /v2/quick-zip?code=90210&key=your_api_key

Request & Response Format

Code inputs (including distance from/to) are strings of at most 50 characters: 5-digit ZIP, ZIP+4 with or without a dash, FSA, full Canadian postal code with an optional space, or lat,lon (latitude -90..90, longitude -180..180). Include flags are split on commas, trimmed, lowercased, normalized from hyphens to underscores, and de-duplicated. Single POST include fields are strings. Authorization: Bearer followed by your key is accepted as well as X-Api-Key; two different keys in one request are refused.

Quick Start

Make your first API call in seconds:

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/quick-zip?code=90210"

import requests

resp = requests.get(
    "https://api.zip-codes.com/v2/quick-zip",
    params={"code": "90210"},
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(data["results"][0]["city"])  # Beverly Hills

const resp = await fetch(
  "https://api.zip-codes.com/v2/quick-zip?code=90210",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log(data.results[0].city); // Beverly Hills

Your Dashboard

The API Portal dashboard gives you full control over your account:

• API Keys — Create, rotate, and configure keys with per-key IP whitelisting and CORS origin restrictions.
• Usage Analytics — Daily and monthly usage charts, per-key breakdowns, and CSV export for your records.
• Billing — Manage your subscription tier, purchase credit packs, and download invoices.
• Settings — Update account details and notification preferences.

Free tier accounts start with 2,500 credits/day. Sign in to get started →

Fields the schema marks nullable are always present and null when they have no value (for example postal_info on a US ZIP, zip_info on a Canadian code, an empty census layer, a suppressed ACS value); every other field is omitted when it has no value (an enrichment that was not requested, an empty notice list). Postal, radius, distance and suggest items are flattened: {success,input?,error?,notices?,...fields}, with no data wrapper. Address retains data; health uses a top-level data object. A well-formed lookup with no match returns HTTP 200 and a per-item error. Single address no-match uses top-level success:false and an error inside results[0].

Response Format

Every API response follows a consistent envelope structure:

{
  "success": true,
  "request": {
    "code": "90210",
    "include": [
      "timezone"
    ]
  },
  "results": [
    "..."
  ],
  "meta": {
    "request_id": "01M3SX2V9NY9MRRAMWVJG0C09E",
    "version": "2.0.0",
    "timing_ms": 45,
    "credits": {
      "used": 2,
      "remaining": 74998,
      "breakdown": {
        "base": 1,
        "enrichments": {
          "timezone": 1
        }
      },
      "source": "subscription"
    }
  }
}

Notices

The meta.notices array contains non-error informational messages about request processing. Notices may also appear on result items. Only FREE_TIER_LIMIT_CAPPED includes an optional url, linking to pricing; all other notices omit it:

Address Matching

Parse and validate a raw US street address against USPS ZIP+4 delivery-point data. Returns the standardized address, ZIP+4 code, address components, and delivery metadata. Handles partial input — with a ZIP code, the city and state are optional; without one, give the city and state.

Parameters

Credit Cost

Base 1 credit per request, whether or not a match is found. Requesting coordinates adds 1 credit when a location is returned. Each boundary flag and each tract ACS profile and year adds 1 credit only when delivered. Credit availability is checked against the requested enrichments before matching.

Include Flags

Paths below are relative to results[0].data for single calls and results[i].data for batch. GET takes a comma-separated list; POST /v2/address requires a string (an array returns HTTP 400); batch accepts a string or array. All flags are optional; the default is no enrichments.

Boundary Enrichments

Use census for counties, county subdivisions, places, tracts, block groups, metro/micro statistical areas, and metropolitan divisions; cd for congressional districts; state_leg for upper and lower state legislative districts; and school_district for school districts. Add a year to census, cd or state_leg for that year’s boundaries (2010–2025, for example census_2022, cd_2012, state_leg_2020); the bare flags return the latest year (2026). Flags accept either dashes or underscores and are case-insensitive; duplicate flags count once.

All four flags use a spatial lookup for one point: the matched ZIP+4 record's centroid. You do not need to request coordinates; without that flag, data.location is omitted. With coordinates, it contains latitude and longitude rounded to 6 decimals.

Each flag fills its own family beside the others in data, in the same names and order as /v2/zip: census, congressional_district, state_legislative, and school_district. Each family holds its latest year under current, and census_YYYY, cd_YYYY and state_leg_YYYY add that year under its own "YYYY" key beside current, newest first (school_district serves current only and timezone the latest release: neither has year flags). A year flag naming the newest year (cd_2026 or census_2026 today) is answered under current, not under its own key; a requested family with nothing found is present with current: null, and an unrequested family is absent. data.census.current holds arrays county (with is_usps_primary), county_subdivision, place, tract, block_group, metro_micro_cbsa_statistical_area, and metropolitan_cbsa_division (an address lies in one of each, so each list has at most one row). data.congressional_district.current contains congress, districts, and primary:{geoid,state,district_number} with an integer district number. data.state_legislative.current contains legislative_year, upper, and lower arrays. Every spatial block on /v2/address (each census, congressional and state legislative period, school_district and timezone) opens with the same attribution fields in the same order: source, product, attribution. They come from the data file's provenance: the publisher, the data product, and the credit line the publisher asks for; each source's license, product page, vintages and refresh cadence are listed under Spatial layers: full provenance. Census, congressional and state legislative periods then give the TIGER/Line year and vintage. Show attribution wherever you display the data. Point rows carry pct_of_zip, pct_of_area and shared_area_sq_mi as null (a point has no area). details.congressional_district is a different field: the district USPS assigns to the ZIP+4, as USPS publishes it, independent of the cd flag. USPS’s assignment can be wrong; the cd flag’s districts are the districts whose legal boundaries (Census TIGER/Line) contain the matched location. In the newest year, primary is the USPS district when USPS assigns one (basis says so), so it can differ from the district containing the location; earlier years’ primary is always the district containing the location, so compare districts, not primary, across years.

A boundary flag costs one credit per year, only when a usable point exists and all its lookups complete. Empty lookups are null and still count as delivered. No match, a ZIP-level answer without a location, or a failed boundary read makes the affected flag unavailable and uncharged. One ENRICHMENT_UNAVAILABLE notice names all unavailable boundary and tract enrichments; the address answer is still returned.

Tract ACS Enrichments

Use acs_tract_demographic, acs_tract_social, acs_tract_economic, or acs_tract_housing. Unsuffixed flags select the latest ACS year (2024). Append a year, _2011 to _2023, for an earlier release (for example acs_tract_housing_2015); _2024 is also accepted. Supported years are 2011–2024. An unsuffixed flag and its latest-year alias count as one enrichment, for 56 distinct tract profile/year tags.

Profiles describe the census tract that contains the matched address's location. They appear under the geography level, results[].data.acs.tract: current for the latest year, and each earlier year asked for under its own "YYYY" key. Each year block uses the same ACS field names as /v2/zip, with geography_level: "tract" and geo_id of 1400000US followed by its 11-digit tract GEOID. The tract is looked up separately for each year, in that year's Census TIGER/Line tracts, the geography that ACS release is published on: tracts are renumbered and redrawn between releases (the 2020 Census tracts from 2020, Connecticut's planning regions from 2022), so geo_id can differ from year to year for the same address. Each block includes source, product, year, vintage ({year-4}-{year}), and tables.

If the address is unmatched, the match has no location, no tract contains it, or a requested profile has no row for that year, that enrichment is not charged. One ENRICHMENT_UNAVAILABLE notice in meta.notices names the unavailable flags and explains why. A missing profile may be null within a block; data.acs is omitted if no requested profile was delivered. Unsupported tract flags or years are ignored without charge and reported through VALIDATION_UNKNOWN_ENRICHMENT. Tract flags are only available on the address endpoints.

data.school_district.current contains the attribution fields (source, product, attribution), school_year, and districts:[{leaid,name,type,grade_low,grade_high,state_fips,land_area_sq_mi,water_area_sq_mi,centroid?,office?,locale?,nces_codes}]. ACS blocks identify source:"U.S. Census Bureau", product:"ACS 5-Year Estimates Data Profiles", and a five-year vintage. timezone adds data.timezone (after school_district): the same object /v2/zip returns, {source, zones:[{iana_name, name, abbreviation, abbreviation_dst, utc_offset, utc_offset_dst, observes_dst, pct_of_zip}]}, plus the attribution fields (source, product, attribution) from the time zone boundary file (timezone-boundary-builder, newest release; OpenStreetMap-derived, ODbL). The address point lies in one zone, so zones has one entry; its pct_of_zip is null (an address is a point; the key is kept so the shape matches /v2/zip). +1 credit when delivered; with no point, or no time zone data, it is ENRICHMENT_UNAVAILABLE and not charged. Unknown flags (including acs_demographic and unsupported tract years) are ignored free with VALIDATION_UNKNOWN_ENRICHMENT: Unknown enrichment flag(s) ignored: {flags}.

Batch Address Enrichment

POST /v2/address/batch accepts up to 250 addresses and the same flags in the body include (a comma-separated string or array). A paid plan or purchased credits are required. Credits are reserved for every requested enrichment, then unused credits are refunded. Each successfully processed item costs the base credit and only its delivered coordinates, boundary flags and tract profiles; rejected or failed items are not charged. Matched items carry data.census, data.congressional_district, data.state_legislative, data.school_district, data.timezone, and data.acs in the same shapes as the single endpoint. One envelope ENRICHMENT_UNAVAILABLE notice counts processed addresses missing requested enrichments, including unmatched addresses. Unknown flags are ignored without charge and named in VALIDATION_UNKNOWN_ENRICHMENT.

{
  "addresses": [
    "1600 Pennsylvania Ave NW, Washington DC 20500",
    "not a real address 99999"
  ],
  "include": [
    "coordinates",
    "acs_tract_economic"
  ]
}

Items are {success,input:{address},matched,data?,notices?}. An unmatched item is {success:true,input:{address},matched:false}, with no engine reason code; it counts in meta.batch.succeeded. Rejected or failed items have success:false, input, and error, and cost 0 credits. The batch timeout is 45 seconds, as for every request.

{
  "success": true,
  "request": {
    "addresses_count": 2
  },
  "results": [
    {
      "success": true,
      "input": {
        "address": "1600 Pennsylvania Ave NW, Washington DC 20500"
      },
      "matched": true,
      "data": {
        "confidence": "high",
        "formatted_address": "1600 PENNSYLVANIA AVE NW, WASHINGTON, DC 20500-0005",
        "location": {
          "latitude": 38.898704,
          "longitude": -77.036497
        },
        "acs": {
          "tract": {
            "current": {
              "source": "U.S. Census Bureau",
              "product": "ACS 5-Year Estimates Data Profiles",
              "year": 2024,
              "vintage": "2020-2024",
              "geo_id": "1400000US11001980000",
              "geography_level": "tract",
              "tables": {
                "economic": "DP03"
              },
              "economic": {
                "commuting": {
                  "drove_alone": {
                    "column": "DP03_0019",
                    "est": 12,
                    "moe": 18,
                    "pct": 70.6,
                    "pct_moe": 8.0
                  },
                  "public_transportation": {
                    "column": "DP03_0021",
                    "est": 5,
                    "moe": 8,
                    "pct": 29.4,
                    "pct_moe": 8.0
                  }
                }
              }
            }
          }
        }
      },
      "notices": [
        {
          "code": "MATCHED",
          "message": "Address matched.",
          "class": "match"
        }
      ]
    },
    {
      "success": true,
      "input": {
        "address": "not a real address 99999"
      },
      "matched": false
    }
  ],
  "meta": {
    "request_id": "01M3SX2VE1BEM6ACR6DME1GXK2",
    "version": "2.0.0",
    "timing_ms": 53,
    "credits": {
      "used": 5,
      "source": "subscription",
      "remaining": 1485722,
      "breakdown": {
        "base": 0,
        "enrichments": {},
        "note": "2 addresses x 1 base + 3 enrichment = 5 credits"
      }
    },
    "notices": [
      {
        "code": "ENRICHMENT_UNAVAILABLE",
        "message": "Enrichment(s) unavailable: acs_tract_economic for 1 of 2 processed addresses; matched location or requested enrichment data is unavailable; not charged."
      }
    ],
    "batch": {
      "requested": 2,
      "succeeded": 2,
      "failed": 0
    }
  }
}

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/address?address=9641+Sunset+Blvd%2C+Beverly+Hills%2C+CA+90210&include=coordinates,census,cd,state_leg,school_district,acs_tract_demographic,acs_tract_housing_2023"

Example Response

Captured response excerpt: fields and ACS profiles are trimmed; the original eight-credit charge is retained.

{
  "success": true,
  "request": {
    "address": "9641 Sunset Blvd, Beverly Hills, CA 90210",
    "include": "coordinates,census,cd,state_leg,school_district,acs_tract_demographic,acs_tract_housing_2023"
  },
  "results": [
    {
      "input": "9641 Sunset Blvd, Beverly Hills, CA 90210",
      "success": true,
      "data": {
        "confidence": "medium",
        "formatted_address": "9641 SUNSET BLVD, BEVERLY HILLS, CA 90210-2938",
        "address_line1": "9641 SUNSET BLVD",
        "address_line2": "BEVERLY HILLS, CA 90210-2938",
        "address_components": {
          "number": "9641",
          "street": "SUNSET",
          "suffix": "BLVD",
          "city": "BEVERLY HILLS",
          "state": "CA",
          "zip": "90210",
          "plus4": "2938",
          "country": "US"
        },
        "location": {
          "latitude": 34.081348,
          "longitude": -118.412499
        },
        "acs": {
          "tract": {
            "current": {
              "source": "U.S. Census Bureau",
              "product": "ACS 5-Year Estimates Data Profiles",
              "year": 2024,
              "vintage": "2020-2024",
              "geo_id": "1400000US06037700700",
              "geography_level": "tract",
              "tables": {
                "demographic": "DP05"
              },
              "demographic": {
                "sex_and_age": {
                  "total_population": {
                    "column": "DP05_0001",
                    "est": 2935,
                    "moe": 578,
                    "pct": 2935,
                    "pct_moe": null
                  },
                  "median_age": {
                    "column": "DP05_0018",
                    "est": 56.4,
                    "moe": 8.7
                  }
                }
              }
            },
            "2023": {
              "source": "U.S. Census Bureau",
              "product": "ACS 5-Year Estimates Data Profiles",
              "year": 2023,
              "vintage": "2019-2023",
              "geo_id": "1400000US06037700700",
              "geography_level": "tract",
              "tables": {
                "housing": "DP04"
              },
              "housing": {
                "occupancy": {
                  "total": {
                    "column": "DP04_0001",
                    "est": 1303,
                    "moe": 144,
                    "pct": 1303,
                    "pct_moe": null
                  },
                  "occupied": {
                    "column": "DP04_0002",
                    "est": 1170,
                    "moe": 149,
                    "pct": 89.8,
                    "pct_moe": 7.9
                  }
                }
              }
            }
          }
        },
        "census": {
          "current": {
            "source": "U.S. Census Bureau",
            "product": "TIGER/Line Shapefiles",
            "attribution": "Source: U.S. Census Bureau, TIGER/Line Shapefiles 2025",
            "year": 2025,
            "vintage": "2025",
            "county": [
              {
                "fips": "06037",
                "name": "Los Angeles",
                "is_usps_primary": true
              }
            ],
            "county_subdivision": [
              {
                "geoid": "0603791750",
                "name": "Los Angeles"
              }
            ],
            "place": [
              {
                "geoid": "0606308",
                "name": "Beverly Hills"
              }
            ],
            "tract": [
              {
                "geoid": "06037700700",
                "name": "7007"
              }
            ],
            "block_group": [
              {
                "geoid": "060377007002",
                "name": "2"
              }
            ],
            "metro_micro_cbsa_statistical_area": [
              {
                "cbsa_code": "31080",
                "name": "Los Angeles-Long Beach-Anaheim, CA"
              }
            ],
            "metropolitan_cbsa_division": [
              {
                "metdiv_code": "31084",
                "name": "Los Angeles-Long Beach-Glendale, CA",
                "cbsa_code": "31080"
              }
            ]
          }
        },
        "congressional_district": {
          "current": {
            "source": "U.S. Census Bureau",
            "product": "TIGER/Line Shapefiles",
            "attribution": "Source: U.S. Census Bureau, TIGER/Line Shapefiles 2025",
            "year": 2025,
            "vintage": "2025",
            "congress": 119,
            "districts": [
              {
                "geoid": "0636",
                "state": "CA",
                "district_number": 36,
                "name": "Congressional District 36",
                "land_area_sq_mi": 97.11,
                "water_area_sq_mi": 97.51
              }
            ],
            "primary": {
              "geoid": "0636",
              "state": "CA",
              "district_number": 36
            }
          }
        },
        "state_legislative": {
          "current": {
            "source": "U.S. Census Bureau",
            "product": "TIGER/Line Shapefiles",
            "attribution": "Source: U.S. Census Bureau, TIGER/Line Shapefiles 2025",
            "year": 2025,
            "vintage": "2025",
            "legislative_year": 2024,
            "upper": [
              {
                "geoid": "06024",
                "name": "24"
              }
            ],
            "lower": [
              {
                "geoid": "06051",
                "name": "51"
              }
            ]
          }
        },
        "school_district": {
          "current": {
            "source": "National Center for Education Statistics (NCES)",
            "product": "EDGE School District Boundaries",
            "attribution": "Source: U.S. Department of Education, National Center for Education Statistics (NCES), EDGE School District Boundaries, SY 2024-25 (TIGER 2025)",
            "school_year": "2024-2025",
            "districts": [
              {
                "leaid": "0604830",
                "name": "Beverly Hills Unified School District",
                "type": "unified",
                "grade_low": "KG",
                "grade_high": "12"
              }
            ]
          }
        }
      },
      "notices": [
        {
          "code": "PARTIAL_MATCH",
          "message": "Address matched; some details could not be confirmed.",
          "class": "match"
        }
      ]
    }
  ],
  "meta": {
    "request_id": "01M4CRKA0K3PCJ56G6GMA3BN34",
    "version": "2.0.0",
    "timing_ms": 24,
    "credits": {
      "used": 8,
      "source": "subscription",
      "remaining": 856921,
      "breakdown": {
        "base": 1,
        "enrichments": {
          "coordinates": 1,
          "acs_tract_demographic": 1,
          "acs_tract_housing_2023": 1,
          "census": 1,
          "cd": 1,
          "state_leg": 1,
          "school_district": 1
        }
      }
    }
  }
}

Result Fields

Matched Address Data

Address Components

Details (USPS Metadata)

Address item notices include class and codes MATCHED, PARTIAL_MATCH, ZIP_CORRECTED, CITY_CORRECTED, STATE_CORRECTED, HOUSE_NUMBER_CORRECTED, STREET_CORRECTED, NO_HOUSE_NUMBER, SECONDARY_NEEDED, SECONDARY_NOT_VERIFIED, UNIT_READ_AS_PMB, INPUT_NOT_USED, ZIP4_WITHHELD, and MILITARY_ADDRESS. HOUSE_NUMBER_CORRECTED means the house number was read differently from how it was written (37061/ read as 3706 1/2); its message names both, and the match is then PARTIAL_MATCH. UNIT_READ_AS_PMB (class correction): at a commercial mail receiving agency (a mail drop such as a UPS Store) a unit that does not confirm is the renter's private mailbox, printed as PMB n; the message names the unit as written and the box. MILITARY_ADDRESS (class info, last): an APO/FPO/DPO address, where address_components.street holds the unit (UNIT 2050) and number the box number (4190), USPS's values as they are; the message names both, or says no box number was supplied. Test keys accept only configured demo addresses.

No Match, Ambiguous, or Insufficient Input

HTTP 200, top-level success:false, no top-level error. results[0] contains input, success:false, and error:{code,message,url}. No candidate list is returned.

• INSUFFICIENT_INPUT: Not enough information to locate the address. Include a city and state, or a ZIP code.
• AMBIGUOUS: More than one address matches. Add detail such as a unit number, directional or ZIP code.
• NOT_FOUND: The address could not be matched.

No match costs 1 credit. Requested coordinates and boundary/tract flags produce one ENRICHMENT_UNAVAILABLE notice and are not charged. On a matched address, unavailable enrichment notices explain that the matched location or requested enrichment data is unavailable.

{
  "success": false,
  "request": {
    "address": "123 Nowhere Lane Faketown ZZ",
    "include": "coordinates,census"
  },
  "results": [
    {
      "input": "123 Nowhere Lane Faketown ZZ",
      "success": false,
      "error": {
        "code": "INSUFFICIENT_INPUT",
        "message": "Not enough information to locate the address. Include a city and state, or a ZIP code.",
        "url": "https://www.zip-codes.com/api/"
      }
    }
  ],
  "meta": {
    "request_id": "01M3SX2VHP0M9TXH8WFHW7ZM3G",
    "version": "2.0.0",
    "timing_ms": 5,
    "credits": {
      "used": 2,
      "source": "subscription",
      "remaining": 1485721,
      "breakdown": {
        "base": 1,
        "enrichments": {
          "coordinates": 1
        }
      }
    },
    "notices": [
      {
        "code": "ENRICHMENT_UNAVAILABLE",
        "message": "Enrichment(s) unavailable: census; address was not matched; not charged."
      }
    ]
  }
}

Geographic Suggest

Typeahead search for geographic entities. Returns ZIP codes, cities/places, counties, metro areas (CBSAs), states/provinces, and Canadian FSAs/postal codes, school districts and USPS city names matching a query. Results include authoritative identifiers (FIPS, GEOID), coordinates, bounding boxes, and population data.

Parameters

Entity Types

Credit Cost

Billing based on requested limit, not results returned: a search is charged even when it matches nothing (the search ran; the answer is no match). Free/test tier requests above 15 are clamped with a FREE_TIER_LIMIT_CAPPED notice. Validation errors (missing q, invalid include) cost 0 credits.

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/suggest?q=spring&limit=3"

Example: With proximity bias

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/suggest?q=spring&proximity=40.7128,-74.006&limit=3"

Example: Filtered by type and state

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/suggest?q=cook&include=county&state=IL&limit=3"

Example Response

{
  "success": true,
  "request": {
    "q": "cook",
    "limit": 3,
    "include": [
      "county"
    ],
    "state": "IL"
  },
  "results": [
    {
      "success": true,
      "total_matched": 5,
      "matches": [
        {
          "type": "county",
          "name": "Cook County",
          "state": "IL",
          "country": "US",
          "fips": "17031",
          "geoid": "17031",
          "population": 5182090,
          "location": {
            "lat": 41.8440477,
            "lon": -87.820797
          },
          "bbox": {
            "min_lat": 41.46971,
            "max_lat": 42.154265,
            "min_lon": -88.263641,
            "max_lon": -87.524165
          }
        },
        {
          "type": "county",
          "name": "Rock Island County",
          "state": "IL",
          "country": "US",
          "fips": "17161",
          "geoid": "17161",
          "population": 142757,
          "location": {
            "lat": 41.5511206,
            "lon": -90.4512621
          },
          "bbox": {
            "min_lat": 41.326838,
            "max_lat": 41.7829645,
            "min_lon": -91.0719555,
            "max_lon": -90.159878
          }
        },
        {
          "type": "county",
          "name": "Boone County",
          "state": "IL",
          "country": "US",
          "fips": "17007",
          "geoid": "17007",
          "population": 53230,
          "location": {
            "lat": 42.3297656,
            "lon": -88.849764
          },
          "bbox": {
            "min_lat": 42.15232,
            "max_lat": 42.495046,
            "min_lon": -88.940992,
            "max_lon": -88.70541
          }
        }
      ]
    }
  ],
  "meta": {
    "version": "2.0.0",
    "timing_ms": 2,
    "credits": {
      "used": 1,
      "remaining": 74999,
      "breakdown": {
        "base": 1,
        "enrichments": {}
      },
      "source": "subscription"
    },
    "request_id": "01M3SX2V9NY9MRRAMWVJG0C09E"
  }
}

Match Object Fields

Quick ZIP Lookup

Fast postal code lookup returning basic location data with optional timezone enrichment. Supports US ZIP codes (5-digit), US ZIP+4 codes, Canadian FSAs (3-character), full Canadian postal codes (6-character), and latitude/longitude coordinates for reverse geocoding.

Parameters

Supported Code Types

Available Enrichments

Timezone (October 2026, nothing removed): timezone stays one flat object with the fields it always had, and gains product and attribution; source now names the publisher of the time zone boundaries ("timezone-boundary-builder"), the same three values /v2/zip and /v2/address return. Field order: source, product, attribution, iana_name, name, abbreviation, abbreviation_dst, utc_offset, utc_offset_dst, observes_dst. A US ZIP (and a ZIP+4, by its parent ZIP) is answered from the ZIP's boundary: a ZIP crossing a zone line gives the zone covering the largest share of it (use /v2/zip for every zone with its share). Coordinates and ZIPs with only a centroid give the zone containing the point. Canadian codes keep their zone with the source /v2/zip gives Canadian codes; product and attribution are null. Show attribution wherever you display the data. Credits are unchanged.

Credit Cost

Quick ZIP credits = base × (1 + timezone + reverse_geocode). Base is 2 for ZIP+4 and 1 for ZIP, FSA, or Postal. Coordinates use the resolved type and add a reverse-geocode layer. ZIP+4 with timezone costs 4; coordinates resolving to ZIP+4 cost 4, or 6 with timezone. Unknown flags have no effect.

Response Fields

ZIP+4 Detail Fields

When a ZIP+4 code is looked up, the detail object is populated with delivery-point data:

Street Detail Fields

Street-level address range information within the detail.street object:

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/quick-zip?code=90210&include=timezone"

Example Response

{
  "success": true,
  "request": {
    "code": "90210",
    "include": [
      "timezone"
    ]
  },
  "results": [
    {
      "code": "90210",
      "code_type": "ZIP",
      "country": "US",
      "city": "Beverly Hills",
      "state": "CA",
      "state_name": "California",
      "state_fips": "06",
      "county": "Los Angeles",
      "county_fips": "06037",
      "classification": null,
      "classification_name": "Standard",
      "location": {
        "lat": 34.103131,
        "lon": -118.416253
      },
      "timezone": {
        "source": "timezone-boundary-builder",
        "product": "Time zone boundaries (with oceans)",
        "attribution": "Time zone boundaries © OpenStreetMap contributors, timezone-boundary-builder (ODbL); time zone rules: IANA tz database",
        "iana_name": "America/Los_Angeles",
        "name": "Pacific",
        "abbreviation": "PST",
        "abbreviation_dst": "PDT",
        "utc_offset": -8,
        "utc_offset_dst": -7,
        "observes_dst": true
      },
      "success": true
    }
  ],
  "meta": {
    "version": "2.0.0",
    "timing_ms": 8,
    "credits": {
      "used": 2,
      "remaining": 856919,
      "breakdown": {
        "base": 1,
        "enrichments": {
          "timezone": 1
        }
      },
      "source": "subscription"
    },
    "request_id": "01M4CRSJ0T2ZK0JDA9A0QFWJ8N"
  }
}

{
  "success": true,
  "request": {
    "code": "M5V",
    "include": [
      "timezone"
    ]
  },
  "results": [
    {
      "code": "M5V",
      "code_type": "FSA",
      "country": "CA",
      "city": "Toronto",
      "state": "ON",
      "state_name": "Ontario",
      "location": {
        "lat": 43.638388,
        "lon": -79.40428
      },
      "timezone": {
        "source": "IANA Time Zone Database / timezone-boundary-builder",
        "product": null,
        "attribution": null,
        "iana_name": "America/Toronto",
        "name": "Eastern",
        "abbreviation": "EST",
        "abbreviation_dst": "EDT",
        "utc_offset": -5,
        "utc_offset_dst": -4,
        "observes_dst": true
      },
      "success": true
    }
  ],
  "meta": {
    "version": "2.0.0",
    "timing_ms": 15,
    "credits": {
      "used": 2,
      "remaining": 74998,
      "breakdown": {
        "base": 1,
        "enrichments": {
          "timezone": 1
        }
      },
      "source": "subscription"
    },
    "request_id": "01M3SX2V9NY9MRRAMWVJG0C09E"
  }
}

{
  "success": true,
  "request": {
    "code": "99999"
  },
  "results": [
    {
      "success": false,
      "input": {
        "code": "99999"
      },
      "error": {
        "code": "NOT_FOUND_ZIP",
        "message": "ZIP code 99999 not found.",
        "url": "https://www.zip-codes.com/api/"
      }
    }
  ],
  "meta": {
    "version": "2.0.0",
    "timing_ms": 8,
    "credits": {
      "used": 1,
      "remaining": 74999,
      "breakdown": {
        "base": 0,
        "enrichments": {},
        "note": "Not found (1 credit charged)."
      },
      "source": "subscription"
    },
    "request_id": "01M3SX2V9NY9MRRAMWVJG0C09E"
  }
}

ZIP Code Details

Unknown include flags are ignored free with a VALIDATION_UNKNOWN_ENRICHMENT notice on this single endpoint. /v2/zip/batch ignores unknown flags without that notice.

Comprehensive postal code lookup with rich data including demographics, business statistics, delivery points, and optional enrichments and historical ACS profiles. Returns detailed information for US ZIP codes and Canadian postal codes.

Parameters

Available Enrichments

Credit Cost

ZIP Details credits = 1 + billable flags + reverse_geocode. Base is 1 for every code type, including ZIP+4 and Postal. Canadian unavailable flags cost 0 with a notice. Example: include=timezone,census,cd on a ZIP = 4 credits. On a Canadian code, include=statcan,statcan_2016,timezone = 4 credits; federal electoral districts are inside statcan at no extra charge, and census/cd there are one statcan charge.

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/zip?code=90210&include=timezone,demographics"

Example Response

{
  "success": true,
  "request": {
    "code": "90210",
    "include": [
      "timezone",
      "demographics"
    ]
  },
  "results": [
    {
      "country": "US",
      "code": "90210",
      "code_type": "ZIP",
      "city": "Beverly Hills",
      "state": "CA",
      "state_name": "California",
      "state_fips": "06",
      "county": "Los Angeles",
      "county_fips": "06037",
      "multi_county": false,
      "location": {
        "lat": 34.102787,
        "lon": -118.416019
      },
      "area_codes": [
        "310",
        "323",
        "424",
        "738"
      ],
      "elevation": {
        "ft": 719,
        "m": 219
      },
      "metro": {
        "region": "West",
        "division": "Pacific",
        "csa": "348",
        "csa_name": "Los Angeles-Long Beach, CA",
        "msa": "4472",
        "msa_name": "Los Angeles-Riverside-Orange County, CA"
      },
      "zip_info": {
        "classification": null,
        "classification_name": "Standard",
        "facility_code": "P",
        "city_delivery_indicator": "Y",
        "intro_date": "<2004-10",
        "land_area_sq_mi": 10.748,
        "water_area_sq_mi": 0.054,
        "zip4_count": 3516,
        "delivery_points": {
          "total_active": 10643,
          "business": 1472,
          "residential": 9301,
          "po_box": 0,
          "single_family": 6786,
          "multi_family": 2419
        }
      },
      "demographics": {
        "population": {
          "total": 21134,
          "estimate": 22973,
          "male": 10099,
          "female": 11035
        },
        "race": {
          "white": 17130,
          "black": 366,
          "hispanic": 1296,
          "asian": 1406,
          "american_indian": 25,
          "hawaiian_pacific_islander": 12,
          "other": 481
        },
        "age": {
          "median": 49.3,
          "median_male": 49.3,
          "median_female": 49.2
        },
        "households": {
          "total": 8553,
          "persons_per_household": 2.47,
          "average_family_size": 3.13,
          "median_income": 187801,
          "average_home_value": 2000001
        },
        "business": {
          "establishments": 2536,
          "employees": 32353,
          "payroll_q1": 648013000,
          "payroll_annual": 2653591000
        }
      },
      "timezone": {
        "source": "timezone-boundary-builder",
        "product": "Time zone boundaries (with oceans)",
        "attribution": "Time zone boundaries © OpenStreetMap contributors, timezone-boundary-builder (ODbL); time zone rules: IANA tz database",
        "zones": [
          {
            "iana_name": "America/Los_Angeles",
            "name": "Pacific",
            "abbreviation": "PST",
            "abbreviation_dst": "PDT",
            "utc_offset": -8,
            "utc_offset_dst": -7,
            "observes_dst": true,
            "pct_of_zip": 100
          }
        ]
      },
      "success": true
    }
  ],
  "meta": {
    "version": "2.0.0",
    "timing_ms": 10,
    "credits": {
      "used": 3,
      "remaining": 856905,
      "breakdown": {
        "base": 1,
        "enrichments": {
          "timezone": 1,
          "demographics": 1
        }
      },
      "source": "subscription"
    },
    "request_id": "01M4CRSKYEX0XGT5H4VGGYQN6B"
  }
}

Base Fields (no include flag required)

metro Sub-Fields (US only)

postal_info Sub-Fields (CA only)

Radius Search

Find all postal codes within a given radius of a center point. Specify the center via a single code parameter (ZIP, FSA, Postal Code, or lat,lon coordinates). Cross-border searches include Canadian postal codes in centroid mode and FSAs in spatial mode. Supports donut searches (min radius) and result limiting.

Parameters

Available Enrichments

Credit Cost

Centroid mode (default, faster): Wider bands — the first 100 miles costs 1 base credit, the next 100 costs 2, and so on up to 500 miles.

Spatial mode (precise boundaries): Narrower bands — the first 50 miles costs 1 base credit, the next 50 costs 2, and so on up to 250 miles.

Cost = base × (1 + distinct timezone/ACS flags + auto_radius); auto_radius is 1 for either auto option, otherwise 0.

Auto Radius

Instead of specifying a numeric radius, pass max=auto or max=auto-commute to let the API calculate an appropriate search radius for the center point. This accepts a ZIP, ZIP+4, FSA, Postal code, or lat/lon coordinate center.

Credit cost: Using auto-radius counts as one additional data layer in the cost calculation. Example: max=auto with include=timezone = base × 3 data layers = 3 credits for a short-range search.

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/radius?code=48226&max=25&include=timezone"

Example Response

{
  "success": true,
  "request": {
    "code": "48226",
    "max": "25",
    "include": [
      "timezone"
    ],
    "mode": "centroid"
  },
  "results": [
    {
      "search": {
        "center": {
          "code": "48226",
          "code_type": "ZIP",
          "city": "Detroit",
          "state": "MI",
          "location": {
            "lat": 42.331702,
            "lon": -83.04962
          }
        },
        "max": 25,
        "min": 0,
        "mode": "centroid"
      },
      "matches": [
        {
          "country": "US",
          "code": "48226",
          "code_type": "ZIP",
          "city": "Detroit",
          "state": "MI",
          "county": "Wayne",
          "county_fips": "26163",
          "classification": null,
          "classification_name": "Standard",
          "location": {
            "lat": 42.331654,
            "lon": -83.049581
          },
          "distance_miles": 0,
          "area_sq_mi": null,
          "timezone": {
            "source": "IANA Time Zone Database / timezone-boundary-builder",
            "iana_name": "America/Detroit",
            "name": "Eastern",
            "abbreviation": "EST",
            "abbreviation_dst": "EDT",
            "utc_offset": -5,
            "utc_offset_dst": -4,
            "observes_dst": true
          }
        },
        {
          "country": "US",
          "code": "48243",
          "code_type": "ZIP",
          "city": "Detroit",
          "state": "MI",
          "county": "Wayne",
          "county_fips": "26163",
          "classification": null,
          "classification_name": "Standard",
          "location": {
            "lat": 42.329064,
            "lon": -83.039647
          },
          "distance_miles": 0.54,
          "timezone": {
            "source": "IANA Time Zone Database / timezone-boundary-builder",
            "iana_name": "America/Detroit",
            "name": "Eastern",
            "abbreviation": "EST",
            "abbreviation_dst": "EDT",
            "utc_offset": -5,
            "utc_offset_dst": -4,
            "observes_dst": true
          }
        }
      ],
      "success": true
    }
  ],
  "meta": {
    "version": "2.0.0",
    "timing_ms": 31,
    "credits": {
      "used": 2,
      "remaining": 856903,
      "breakdown": {
        "base": 1,
        "enrichments": {
          "timezone": 1
        },
        "calculation": "1 x (1 + 1) = 2"
      },
      "source": "subscription"
    },
    "request_id": "01M4CRSM8HPQJ7ARP5Z92CMH4S"
  }
}

The radius summary contains total_count, us_zip_count, ca_fsa_count and ca_postal_count, which count the matches returned, and total_available, the number of matches in the radius, present when limit cut the list. ACS statistics (stats.acs) always cover every match in the radius, whatever the limit. They carry est and pct only, with no moe or column: Census publishes no margin of error for a combined area. For one ZIP Code’s estimate with its margin of error, use /v2/zip. A coverage_pct under 100 is normal (often 40–60 in cities): PO Box, unique and other point ZIP Codes have no area of their own, so Census publishes no ACS data for them (zips_without_acs_data), and their residents are counted in the surrounding ZIP Codes, so the totals are not short. Examples are trimmed.

Search Fields

Match Fields

Distance Calculation

Calculate the great-circle distance between two points. Supports any combination of ZIP codes, ZIP+4 codes, FSAs, full Canadian postal codes, and lat/lon coordinates. Timezone data is always included at no extra cost. Each endpoint in the response includes an input_type field ("code" or "coordinates") indicating how the point was resolved.

Timezone (October 2026, nothing removed): each point's timezone stays one flat object with the fields it always had, and gains product and attribution; source now names the publisher ("timezone-boundary-builder"), the same three values /v2/zip returns. Field order: source, product, attribution, iana_name, name, abbreviation, abbreviation_dst, utc_offset, utc_offset_dst, observes_dst. It is the zone containing the point, from the time zone boundary file (timezone-boundary-builder, newest release). Canadian points keep their zone with /v2/zip's Canadian source; product and attribution are null.

Parameters

Credit Cost

Fixed 1 credit per pair. Timezone is always included at no extra cost.

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/distance?from=90210&to=10001"

Example Response

{
  "success": true,
  "request": {
    "from": "90210",
    "to": "10001"
  },
  "results": [
    {
      "from": {
        "country": "US",
        "code": "90210",
        "code_type": "ZIP",
        "city": "Beverly Hills",
        "state": "CA",
        "county": "Los Angeles",
        "location": {
          "lat": 34.102776,
          "lon": -118.416124
        },
        "timezone": {
          "source": "timezone-boundary-builder",
          "product": "Time zone boundaries (with oceans)",
          "attribution": "Time zone boundaries © OpenStreetMap contributors, timezone-boundary-builder (ODbL); time zone rules: IANA tz database",
          "iana_name": "America/Los_Angeles",
          "name": "Pacific",
          "abbreviation": "PST",
          "abbreviation_dst": "PDT",
          "utc_offset": -8,
          "utc_offset_dst": -7,
          "observes_dst": true
        },
        "input_type": "code"
      },
      "to": {
        "country": "US",
        "code": "10001",
        "code_type": "ZIP",
        "city": "New York",
        "state": "NY",
        "county": "New York",
        "location": {
          "lat": 40.750189,
          "lon": -74.000337
        },
        "timezone": {
          "source": "timezone-boundary-builder",
          "product": "Time zone boundaries (with oceans)",
          "attribution": "Time zone boundaries © OpenStreetMap contributors, timezone-boundary-builder (ODbL); time zone rules: IANA tz database",
          "iana_name": "America/New_York",
          "name": "Eastern",
          "abbreviation": "EST",
          "abbreviation_dst": "EDT",
          "utc_offset": -5,
          "utc_offset_dst": -4,
          "observes_dst": true
        },
        "input_type": "code"
      },
      "distance": {
        "miles": 2453.3,
        "km": 3948.15
      },
      "bearing": 65.9,
      "success": true
    }
  ],
  "meta": {
    "version": "2.0.0",
    "timing_ms": 6,
    "credits": {
      "used": 1,
      "remaining": 856902,
      "breakdown": {
        "base": 1,
        "enrichments": {}
      },
      "source": "subscription"
    },
    "request_id": "01M4CRSMQEFVH34GD8XJPVPW0J"
  }
}

Health Check

Returns API and database health status. No authentication required.

Three-state health: healthy (normal), degraded (DB latency >500ms), unhealthy (DB unreachable, returns HTTP 503).

ready is true once the server has finished loading after a start or restart; until then loading lists what is still loading (radius_centroid, radius_spatial, suggest, acs_cache, address, coordinates) and /v2/radius, /v2/radius/batch and /v2/suggest answer 503 SERVICE_WARMING_UP until what they need has loaded. The status code stays 200 while loading.

{
  "success": true,
  "data": {
    "status": "healthy",
    "database": {
      "connected": true,
      "latencyMs": 3
    },
    "version": "2.0.0",
    "ready": true,
    "loading": []
  },
  "meta": {
    "version": "2.0.0",
    "timing_ms": 3
  }
}

Purchase Credits

Buys one credit pack, paid with an MPP wallet: for anyone with one, an agent or a person. With an API key the pack is added to that key's account, and a prepaid card's key reloads the card; sent without any key, it makes a new prepaid card. How paying works (the 402 challenge, the wallet, the Payment-Authorization header) is under Buying Credits with a Wallet (MPP).

Parameters

A JSON body naming one agent pack in pricing.json (its available_to lists agents; agent packs start at $5). Send at least one of the three fields; sent together they must name the same pack, and a value two packs share is refused with the matches listed.

Credit Cost

0 credits. The payment is the pack's price; a successful answer carries a Payment-Receipt header. Credits are added only after the payment completes (a card clears at once; some methods take longer), and purchased credits never expire.

Response Fields

results[0] is the purchase, in its current state. GET /v2/purchases/{id} answers the same object.

Answers and Errors

Example Request

First without a Payment-Authorization header, to get the challenge:

curl -X POST -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"pack":"Mini"}' "https://api.zip-codes.com/v2/purchase"

It answers 402 PAYMENT_REQUIRED with a WWW-Authenticate: Payment challenge header and the offer in error.payment:

{
  "success": false,
  "request": {
    "pack": "Mini"
  },
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Payment required: $5.00 buys the Mini pack (6,250 credits). Pay the MPP challenge in the WWW-Authenticate header and send this same request again with a Payment-Authorization header.",
    "payment": {
      "offer": {
        "name": "Mini",
        "credits": 6250,
        "price_usd": 5
      },
      "methods": [
        {
          "method": "stripe",
          "challenge_id": "...",
          "pays_with": [
            "card",
            "link"
          ],
          "expires": "2026-10-31T18:09:12Z"
        }
      ],
      "purchase_url": "https://api.zip-codes.com/v2/purchase",
      "packs": "https://api.zip-codes.com/pricing.json",
      "terms": "https://www.zip-codes.com/api/tos"
    }
  },
  "meta": {
    "version": "2.2.0",
    "timing_ms": 3
  }
}

Pay the challenge with your wallet, then send the same request again with the credential. The credential is Payment followed by the base64url (no padding) of this JSON: the challenge's parameters exactly as the WWW-Authenticate header gave them, and the wallet's shared payment token (spt_…, limited to the challenge's amount):

{
  "challenge": {
    "id": "from the challenge",
    "realm": "api.zip-codes.com",
    "method": "stripe",
    "intent": "charge",
    "request": "from the challenge, unchanged",
    "expires": "from the challenge"
  },
  "payload": {
    "spt": "spt_..."
  }
}

Send it in Payment-Authorization (the header the challenge names) or in Authorization. A new prepaid card's key starts pp_card_; account keys start zc_live_.

curl -X POST -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -H "Payment-Authorization: Payment eyJ..." \
  -d '{"pack":"Mini"}' "https://api.zip-codes.com/v2/purchase"

Example Response

{
  "success": true,
  "request": {
    "pack": "Mini"
  },
  "results": [
    {
      "purchase_id": "PP-G2TH5-EKHBD",
      "status": "succeeded",
      "pack": {
        "name": "Mini",
        "credits": 6250,
        "price_usd": 5
      },
      "charged": {
        "amount_usd": 5,
        "method": "stripe",
        "network": null,
        "asset": null,
        "reference": "pi_...",
        "transaction": null
      },
      "credits": {
        "added": 6250,
        "purchased_remaining": 6250
      },
      "receipt_url": "https://...",
      "created": "2026-10-31T18:04:12Z",
      "settled": "2026-10-31T18:04:13Z",
      "terms": "https://www.zip-codes.com/api/tos"
    }
  ],
  "meta": {
    "version": "2.2.0",
    "timing_ms": 912
  }
}

Balance

Reads the credit pools of this key's account or prepaid card: what it can spend now. A request draws on free or subscription first, then purchased.

Parameters

Credit Cost

0 credits. Limit: 10 a minute per key, shared with GET /v2/purchases/{id}.

Response Fields

results[0] = {free, subscription, purchased, purchase_url, packs}. The pool names are meta.credits.source's words.

Errors

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/balance"

Example Response

{
  "success": true,
  "results": [
    {
      "free": {
        "remaining": 2380,
        "limit": 2500,
        "resets": "2026-11-01T00:00:00Z"
      },
      "subscription": null,
      "purchased": {
        "remaining": 6250,
        "expires": null
      },
      "purchase_url": "https://api.zip-codes.com/v2/purchase",
      "packs": "https://api.zip-codes.com/pricing.json"
    }
  ],
  "meta": {
    "version": "2.2.0",
    "timing_ms": 4
  }
}

Purchase Lookup

Reads one purchase on this key's account or prepaid card by its order number, in its current state. Use it to follow a 202 from POST /v2/purchase until status reads succeeded.

Parameters

Credit Cost

0 credits. Limit: 10 a minute per key, shared with GET /v2/balance; after 20 unknown purchase ids in an hour, purchase lookups answer 429 until the hour ends.

Response Fields

results[0] is the purchase, the same object POST /v2/purchase answers (see its response fields); api_key is never included here.

Errors

Example Request

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://api.zip-codes.com/v2/purchases/PP-G2TH5-EKHBD"

Example Response

{
  "success": true,
  "results": [
    {
      "purchase_id": "PP-G2TH5-EKHBD",
      "status": "processing",
      "pack": {
        "name": "Mini",
        "credits": 6250,
        "price_usd": 5
      },
      "charged": {
        "amount_usd": 5,
        "method": "stripe",
        "network": null,
        "asset": null,
        "reference": "pi_...",
        "transaction": null
      },
      "credits": {
        "added": 0,
        "purchased_remaining": 0
      },
      "receipt_url": null,
      "created": "2026-10-31T18:04:12Z",
      "settled": null,
      "terms": "https://www.zip-codes.com/api/tos"
    }
  ],
  "meta": {
    "version": "2.2.0",
    "timing_ms": 5
  }
}

Batch Requests

Five routes support batch processing via POST: quick-zip, zip, radius, distance, and address. Address accepts 250 items; the other four accept 100 items. There is no suggest batch: POST /v2/suggest is a single call. Individual items can succeed or fail independently (the overall HTTP status is 200 even if some items fail).

Each batch request uses its route-specific array (codes, searches, pairs, or addresses); request echoes the corresponding count. Failed items contain {success:false,input:{...},error:{code,message,url}}. Credit totals include source, remaining, and breakdown.

Batch Response Meta

{
  "meta": {
    "batch": {
      "requested": 3,
      "succeeded": 2,
      "failed": 1
    },
    "credits": {
      "used": 5,
      "source": "subscription",
      "remaining": 74995,
      "breakdown": {
        "base": 0,
        "enrichments": {},
        "note": "2 codes, 5 total credits"
      }
    },
    "request_id": "01M3SX2V9NY9MRRAMWVJG0C09E",
    "version": "2.0.0",
    "timing_ms": 1
  }
}

Batch Endpoints

All other routes allow 100 items. include accepts a comma-separated string or array of up to 50 strings. Radius searches accept {code,max,min,include,limit}; top-level include, max, and min supply defaults overridden by per-search values. mode is batch-level only; default centroid, while spatial returns HTTP 400 SPATIAL_MODE_DISABLED_BATCH. Radius item input is {index,code,max}. Missing body/fields and oversized batches return HTTP 400; subscription/test-key restrictions 403; insufficient credits 402. Valid batches return HTTP 200.

Example: Quick ZIP Batch

curl -X POST "https://api.zip-codes.com/v2/quick-zip/batch" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"codes": ["90210", "M5V", "99999"], "include": "timezone"}'

Partial Failure

When some items fail, the overall HTTP status is still 200. Failed items appear in the results array with success: false and a per-item error object. The meta.batch summary tells you how many succeeded and failed:

{
  "success": true,
  "results": [
    {
      "success": true,
      "code": "90210",
      "city": "Beverly Hills",
      "state": "CA",
      "input": {
        "code": "90210"
      }
    },
    {
      "success": true,
      "code": "M5V",
      "city": "Toronto",
      "state": "ON",
      "input": {
        "code": "M5V"
      }
    },
    {
      "success": false,
      "error": {
        "code": "NOT_FOUND_ZIP",
        "message": "Code 99999 not found.",
        "url": "https://www.zip-codes.com/api/"
      },
      "input": {
        "code": "99999"
      }
    }
  ],
  "meta": {
    "batch": {
      "requested": 3,
      "succeeded": 2,
      "failed": 1
    },
    "credits": {
      "used": 5,
      "source": "subscription",
      "remaining": 74995,
      "breakdown": {
        "base": 0,
        "enrichments": {},
        "note": "2 codes, 5 total credits"
      }
    },
    "request_id": "01M3SX2V9NY9MRRAMWVJG0C09E",
    "version": "2.0.0",
    "timing_ms": 1
  },
  "request": {
    "codes_count": 3,
    "include": "timezone"
  }
}

Data Enrichments

All enrichments are opt-in. Add them to the include parameter as a comma-separated list. On /zip each billable flag adds 1 credit; quick-zip and radius multiply their base by the number of data layers. Address charges requested coordinates plus delivered boundary flags and tract tags. See Credit Costs.

Timezone

Returns IANA timezone data including standard and daylight saving abbreviations and UTC offsets. On /v2/zip and /v2/address (and their batches) it is one block: source, product, attribution and a zones array with each zone's share of the ZIP (pct_of_zip; null for a point: an address, coordinates, or a ZIP with only a centroid). /v2/quick-zip and /v2/distance (and their batches) return one flat object: the same source, product and attribution, then one zone's fields (the zone covering most of the ZIP, or containing the point). On /v2/radius, timezone is a flat object per match.

Fields Returned

{
  "source": "timezone-boundary-builder",
  "product": "Time zone boundaries (with oceans)",
  "attribution": "Time zone boundaries © OpenStreetMap contributors, timezone-boundary-builder (ODbL); time zone rules: IANA tz database",
  "zones": [
    {
      "iana_name": "America/Los_Angeles",
      "name": "Pacific",
      "abbreviation": "PST",
      "abbreviation_dst": "PDT",
      "utc_offset": -8,
      "utc_offset_dst": -7,
      "observes_dst": true,
      "pct_of_zip": 100.0
    }
  ]
}

Census Boundaries

Canadian codes return Statistics Canada geography under statcan (flag statcan; census, census_YYYY, cd and cd_YYYY on a Canadian code are legacy aliases answered there with an ENRICHMENT_FLAG_RENAMED notice). statcan.current is Statistics Canada’s latest census (2021; statcan_2016 and statcan_2011 add "2016" / "2011"), opening with source, product, attribution, year and vintage. Postal-code periods list tract, census_division, census_subdivision, dissemination_area, dissemination_block, metro_area, population_centre, economic_region, consolidated_subdivision, designated_place, province and federal_electoral_district (the areas containing the postal code’s location); FSA periods list census_division, census_subdivision, tract, metro_area, economic_region, population_centre, consolidated_subdivision, designated_place, province and federal_electoral_district.

Postal codes and FSAs return the same row, in this order: uid, dguid (null for 2016 and 2011, whose files have none), name, name_en and name_fr (federal electoral districts and provinces: name is Statistics Canada’s bilingual name), type and type_description (census divisions, subdivisions, metro areas, population centres), class and class_description (population centres), area_sq_mi and area_km2 (the area’s total area, water included), land_area_sq_mi and land_area_km2 (the area’s land area, every census year; for 2016 and 2011 summed from Statistics Canada’s dissemination-block land areas in the Geographic Attribute File), then pct_of_zip (postal code: always 100) or pct_of_fsa (FSA: share of the FSA), and pct_of_area (FSA: share of the area; null for a postal code). pct_of_fsa and pct_of_area are null for an FSA without a Statistics Canada polygon.

"statcan": {
  "current": {
    "source": "Statistics Canada", "product": "...", "attribution": "...",
    "year": 2021, "vintage": "2021",
    "census_subdivision": [{
      "uid": "3506008", "dguid": "2021A00053506008", "name": "Ottawa",
      "type": "CV", "type_description": "City / Ville",
      "area_sq_mi": 1116.67, "area_km2": 2892.15,
      "land_area_sq_mi": 1076.53, "land_area_km2": 2788.2,
      "pct_of_zip": 100, "pct_of_area": null
    }],
    "federal_electoral_district": [{
      "uid": "35075", "dguid": "2013A000435075", "name": "Ottawa Centre / Ottawa-Centre",
      "name_en": "Ottawa Centre", "name_fr": "Ottawa-Centre",
      "area_sq_mi": 14.42, "area_km2": 37.35,
      "land_area_sq_mi": 12.52, "land_area_km2": 32.43,
      "pct_of_zip": 100, "pct_of_area": null
    }]
  },
  "2016": { ... }
}

US sections are under results[i].census.current: county, county_subdivision, place, tract, block_group, metro_micro_cbsa_statistical_area and metropolitan_cbsa_division are arrays, largest pct_of_zip first. Empty lookups are null.

Boundary families. Each boundary flag returns its own top-level family: census, congressional_district (cd), state_legislative (state_leg), and school_district; Canadian codes return one family, statcan, with federal_electoral_district inside each period. Each family holds its latest year under current; census_YYYY, cd_YYYY and state_leg_YYYY (2010–2025) add that year under its own "YYYY" key beside current, newest first (school_district serves current only). A requested family with nothing found is present with current: null; an unrequested family is absent.

Returns all census geographic boundaries that overlap the ZIP code with percentage overlap calculations. Data sourced from the U.S. Census Bureau’s full-resolution TIGER/Line Shapefiles.

Included Boundary Types

Boundary identifiers use fips for counties, cbsa_code for CBSAs, or geoid as applicable; other fields include, name, land_area_sq_mi, water_area_sq_mi, pct_of_zip (% of ZIP this boundary covers), and pct_of_area (% of boundary this ZIP covers).

{
  "census": {
    "current": {
      "county": [
        {
          "name": "Los Angeles",
          "land_area_sq_mi": 4060.29,
          "water_area_sq_mi": 689.15,
          "pct_of_zip": 100,
          "pct_of_area": 0.27,
          "fips": "06037"
        }
      ],
      "place": [
        {
          "geoid": "0606308",
          "name": "Beverly Hills",
          "land_area_sq_mi": 5.71,
          "water_area_sq_mi": 0,
          "pct_of_zip": 37.16,
          "pct_of_area": 71.42
        }
      ],
      "tract": [
        {
          "geoid": "06037261102",
          "name": "2611.02",
          "land_area_sq_mi": 3.07,
          "water_area_sq_mi": 0,
          "pct_of_zip": 27.96,
          "pct_of_area": 99.98
        }
      ],
      "metro_micro_cbsa_statistical_area": [
        {
          "name": "Los Angeles-Long Beach-Anaheim, CA",
          "land_area_sq_mi": 4853.54,
          "water_area_sq_mi": 845.63,
          "pct_of_zip": 100,
          "pct_of_area": 0.22,
          "cbsa_code": "31080"
        }
      ],
      "source": "U.S. Census Bureau",
      "product": "TIGER/Line Shapefiles",
      "attribution": "Source: U.S. Census Bureau, TIGER/Line Shapefiles 2025",
      "year": 2025,
      "vintage": "2025"
    }
  }
}

Congressional Districts

Returns congressional district overlaps for the current Congress session, with primary district identification and area percentages. Fields sit under congressional_district.current (cd_YYYY adds an earlier year, 2010–2025, under its "YYYY" key), beside the boundary file's source, product, attribution, year, and vintage.

Fields Returned (US)

Fields Returned (CA)

Canadian codes return federal electoral districts inside each statcan period instead, as the list statcan.current.federal_electoral_district (and statcan["2016"].federal_electoral_district for statcan_2016); there is no separate top-level family and no extra charge. cd on a Canadian code is answered as statcan with an ENRICHMENT_FLAG_RENAMED notice. Full postal codes return the district containing their location; FSA boundary overlaps include pct_of_fsa. Each district is the census row above, with name in both languages ("Ottawa Centre / Ottawa-Centre"), name_en and name_fr. Canadian codes never return congressional_district, state_legislative, or school_district.

{
  "congressional_district": {
    "current": {
      "source": "U.S. Census Bureau",
      "product": "TIGER/Line Shapefiles",
      "attribution": "Source: U.S. Census Bureau, TIGER/Line Shapefiles 2025",
      "year": 2025,
      "vintage": "2025",
      "congress": 119,
      "districts": [
        {
          "geoid": "0632",
          "state": "CA",
          "district_number": 32,
          "name": "Congressional District 32",
          "land_area_sq_mi": 296.24,
          "water_area_sq_mi": 92.38,
          "pct_of_zip": 62.76,
          "pct_of_area": 2.32
        },
        {
          "geoid": "0636",
          "state": "CA",
          "district_number": 36,
          "name": "Congressional District 36",
          "land_area_sq_mi": 97.11,
          "water_area_sq_mi": 97.51,
          "pct_of_zip": 37.16,
          "pct_of_area": 4.19
        }
      ],
      "primary": {
        "geoid": "0632",
        "state": "CA",
        "district_number": 32
      }
    }
  }
}

State Legislature

Returns state senate (upper chamber) and assembly/house (lower chamber) district overlaps with area percentages, under state_legislative.current (state_leg_YYYY adds an earlier year, 2010–2025, under its "YYYY" key) beside source, product, attribution, year, and vintage. US only

Fields Returned

Each district includes: geoid, name, district_code, state, state_fips, legislative_session_year, land_area_sq_mi, water_area_sq_mi, pct_of_zip, pct_of_area.

{
  "state_legislative": {
    "current": {
      "source": "U.S. Census Bureau",
      "product": "TIGER/Line Shapefiles",
      "attribution": "Source: U.S. Census Bureau, TIGER/Line Shapefiles 2025",
      "year": 2025,
      "vintage": "2025",
      "legislative_year": 2024,
      "upper": [
        {
          "geoid": "06024",
          "name": "24",
          "name_full": "State Senate District 24",
          "state": "CA",
          "state_fips": "06",
          "district_code": "024",
          "legislative_session_year": "2024",
          "land_area_sq_mi": 327.55,
          "pct_of_zip": 92.81
        }
      ],
      "lower": [
        {
          "geoid": "06051",
          "name": "51",
          "name_full": "Assembly District 51",
          "state": "CA",
          "state_fips": "06",
          "district_code": "051",
          "legislative_session_year": "2024",
          "land_area_sq_mi": 56.4,
          "pct_of_zip": 63.49
        }
      ]
    }
  }
}

School Districts

Returns NCES school district data with boundary overlaps, under school_district.current with source, product, attribution, school_year, and a districts array. US only

Fields Returned per District

{
  "school_district": {
    "current": {
      "source": "National Center for Education Statistics (NCES)",
      "product": "EDGE School District Boundaries",
      "attribution": "Source: U.S. Department of Education, National Center for Education Statistics (NCES), EDGE School District Boundaries, SY 2024-25 (TIGER 2025)",
      "school_year": "2024-2025",
      "districts": [
        {
          "leaid": "0604830",
          "name": "Beverly Hills Unified School District",
          "type": "unified",
          "grade_low": "KG",
          "grade_high": "12",
          "state_fips": "06",
          "land_area_sq_mi": 6.02,
          "pct_of_zip": 39.95,
          "pct_of_area": 72.86,
          "centroid": {
            "lat": 34.07923,
            "lon": -118.4024374
          },
          "office": {
            "address": "624 N. Rexford Dr.",
            "city": "Beverly Hills",
            "state": "CA",
            "zip": "90210",
            "county": "Los Angeles County",
            "location": {
              "lat": 34.078986,
              "lon": -118.40392
            }
          },
          "locale": {
            "code": "21",
            "description": "Suburb - Large"
          },
          "nces_codes": {
            "mtfcc": "G5420",
            "mtfcc_desc": "Unified School District",
            "funcstat": "E",
            "funcstat_desc": "Active"
          }
        }
      ]
    }
  }
}

ACS Data

American Community Survey 5-year estimates from the Census Bureau. Four separate data profiles available, each activated by its own flag. US only

ACS metrics include an estimate (est) and margin of error (moe). Percentage fields also include pct and pct_moe. Suppressed Census values are returned as null.

pct is what Census prints in the field’s percent column, which is not always a percentage: for most fields it is the share of the field’s total (race.one_race.asian.chinese.pct, a share of the total population); on a total row it is the count itself (households.total.pct equals households.total.est); a rate is in whichever column Census prints it: employment.unemployment_rate and the poverty fields are published only as a percent, so est is null and the rate is in pct, while the housing vacancy rates (occupancy.homeowner_vacancy_rate, occupancy.rental_vacancy_rate) are published in the estimate column, so the rate is in est and pct is null; and it is null where Census gives no percent (income.per_capita, fertility and vacancy rates). The /v2/radius aggregates follow the same convention field by field: a share is recomputed from the aggregated sums of the field and the total Census divides it by, a total row’s pct is its aggregated count, the unemployment rate is recomputed from the aggregated labor force, and the poverty rates are averages weighted by population.

acs_demographic — DP05 (108 fields)

acs_social — DP02 (154 fields)

acs_economic — DP03 (137 fields)

acs_housing — DP04 (143 fields)

Historical ACS Data (2011–2024)

Append _YYYY to any ACS profile flag to request a specific year. Example: include=acs_housing_2022 returns the 2018–2022 5-Year Estimates for housing. You can request multiple years simultaneously (e.g., include=acs_economic,acs_economic_2019). Each flag adds one data layer: +1 credit on /zip, multiplied by the distance-band base on /radius. The current year's suffix is the same request as the unsuffixed flag (acs_economic and acs_economic_2024 return one block under current and are charged once) — on every endpoint, including the address tract flags. When Census publishes the next release, current moves to it and 2024 is requested as _2024. On /v2/zip, a year Census published no data for at that ZCTA comes back with published: false and is not charged.

{
  "acs": {
    "current": {
      "geo_id": "860Z200US90210",
      "published": true,
      "year": 2024,
      "product": "ACS 5-Year Estimates Data Profiles",
      "vintage": "2020-2024",
      "geography_level": "zcta",
      "tables": {
        "demographic": "DP05"
      },
      "demographic": {
        "sex_and_age": {
          "male": {
            "est": 9417,
            "moe": 800,
            "pct": 49.6,
            "pct_moe": 2.3
          },
          "female": {
            "est": 9587,
            "moe": 585,
            "pct": 50.4,
            "pct_moe": 2.3
          },
          "median_age": {
            "est": 51.9,
            "moe": 2.3
          },
          "total_population": {
            "est": 19004,
            "moe": 1101,
            "column": "DP05_0001"
          }
        },
        "race": {
          "one_race": {
            "white": {
              "est": 15147,
              "moe": 1106,
              "pct": 79.7,
              "pct_moe": 3.7
            },
            "black": {
              "est": 403,
              "moe": 193,
              "pct": 2.1,
              "pct_moe": 1
            },
            "asian": {
              "total": {
                "est": 1628,
                "moe": 467,
                "pct": 8.6,
                "pct_moe": 2.4
              }
            }
          }
        }
      },
      "source": "U.S. Census Bureau"
    }
  }
}

Demographics

Returns a compact population, race, age, household and business summary for a US ZIP Code. Each figure comes from the latest release of its source: population, race, age and household counts from the latest decennial Census (tabulated for the ZIP Code Tabulation Area); median household income and median home value from the latest ACS 5-year estimates; business counts and payroll from the latest County Business Patterns; and a current population estimate from USPS delivery points.

Fields Returned

{
  "demographics": {
    "population": {
      "total": 21134,
      "estimate": 22973,
      "male": 10099,
      "female": 11035
    },
    "race": {
      "white": 17130,
      "black": 366,
      "hispanic": 1296,
      "asian": 1406,
      "american_indian": 25,
      "hawaiian_pacific_islander": 12,
      "other": 481
    },
    "age": {
      "median": 49.3,
      "median_male": 49.3,
      "median_female": 49.2
    },
    "households": {
      "total": 8553,
      "persons_per_household": 2.47,
      "average_family_size": 3.13,
      "median_income": 187801,
      "average_home_value": 2000001
    },
    "business": {
      "establishments": 2536,
      "employees": 32353,
      "payroll_q1": 648013000,
      "payroll_annual": 2653591000
    }
  }
}

Medicare

Returns Medicare geographic identifiers used in healthcare pricing, insurance rating areas, and CMS administrative boundaries.

Fields Returned

{
  "medicare": {
    "cbsa_code": "31084",
    "cbsa_name": "Los Angeles-Long Beach-Glendale, CA",
    "cbsa_type": "Metro",
    "rating_area_id": "16",
    "ssa_state_county_code": "05200"
  }
}

Data sources

Every dataset the API answers from: the authority behind it, the edition we serve where the source publishes editions, how often we take a new release, and a ready-made citation. Cite the edition shown; a dataset updated on a cadence (the USPS files, for example) has no edition. The same list is served free, without a key, by the MCP server's about_data tool.

Spatial layers: full provenance

Every spatial block in a response (each census, congressional_district and state_legislative period, school_district, timezone) states source, product and attribution. Show attribution wherever you display the data. The full provenance of each source is below; it is generated from the data files themselves.

Credit Costs

Radius Credit Costs

Formula: base × (1 + enrichment_count + auto_radius). Base bands differ by mode.

Centroid Mode (default) — ceil(radius / 100), max 500mi

Spatial Mode — ceil(radius / 50), max 250mi

Band boundaries are inclusive at the top: max=50 = band 1, max=51 = band 2. Decimal values are accepted: max=50.5 = band 2.

Formula Examples

• 25mi centroid, no flags → ceil(25/100) × (1 + 0) = 1 credit
• 25mi centroid, timezone → 1 × (1 + 1) = 2 credits
• 100mi centroid, acs_demographic + timezone → 1 × (1 + 2) = 3 credits
• 200mi centroid, 4 ACS flags → 2 × (1 + 4) = 10 credits
• 500mi centroid, 4 ACS + timezone → 5 × (1 + 5) = 30 credits
• 50mi spatial, no flags → ceil(50/50) × (1 + 0) = 1 credit
• 100mi spatial, 2 ACS flags → 2 × (1 + 2) = 6 credits
• 250mi spatial, 4 ACS + timezone → 5 × (1 + 5) = 30 credits

Credit Estimator

Select an endpoint and configure options to estimate credits assuming the selected enrichments are delivered. Actual usage appears in meta.credits.

Free accounts receive 2,500 daily credits. Subscribers receive their monthly allowance and no daily free credits.

Subscription Plans

Credit Packs

Pre-purchase credits that never expire. Works alongside any plan — free or paid. If you exceed your daily free allowance or monthly subscription, purchased credits kick in automatically.

Purchased credits are used only after your free or subscription allowance is exhausted. Need a custom volume? Contact us.

Error Codes

Every error, including per-item failures, includes a public url for next steps. AUTH_MISSING_KEY, AUTH_INVALID_KEY, AUTH_INACTIVE_KEY, AUTH_INACTIVE_ACCOUNT, AUTH_TEST_KEY_RESTRICTED, AUTH_TEST_KEY_RADIUS_EXCEEDED, AUTH_IP_RESTRICTED, AUTH_ORIGIN_RESTRICTED, and CREDIT_INSUFFICIENT link to your account. AUTH_BATCH_REQUIRES_SUBSCRIPTION, AUTH_FREE_TIER_RADIUS_EXCEEDED, and RATE_LIMIT_MINUTE link to pricing. All VALIDATION_* errors, MISSING_VERSION, UNKNOWN_VERSION, ROUTE_NOT_FOUND, BAD_REQUEST, SPATIAL_MODE_DISABLED_BATCH, and NOT_FOUND_COORDS_NO_BOUNDARY link to documentation. Other errors link to the general API page. The missing-key response for a key sent in the Authorization header without the Bearer scheme links to authentication documentation.

Whole-request failures use {success:false,request?,error:{code,message,retryable?,url,get_started?},meta}; results is omitted. Middleware echoes request:{method,path} and marks 429/503/504 as retryable. Braces in messages are placeholders; validation can return additional parameter-specific messages.

Test-key restriction messages append this suffix: Demo US ZIPs: 90210, 10001, 10118, 32504, 00601, 96950, 33139, 60601, 98101, 30301, 02872, 06103. Demo CA: M5V, K1A, V6B, T2P, H3A, M1R0E9, V5K0A1, K1A0A1, T1X0L3, H1A0A1. Address restrictions read Test API keys are restricted to demo addresses only. Use a real API key to look up any address. followed by a suffix naming demo addresses. The full demo address list (matched ignoring case, commas, periods and extra spaces) is in llms-full.txt; every address example on this page is on it.

Address service-not-ready messages are Address matching service is not ready. Binary files are still loading, please retry shortly. or Address matching service is not ready. Address matching is not enabled on this server.

401 responses include WWW-Authenticate: ApiKey realm="zip-codes-api". Missing-key, invalid-key, and insufficient-credit messages also include the account link in their text. VALIDATION_UNKNOWN_ENRICHMENT is a notice on HTTP 200, not an error.

Per-Item Not Found (HTTP 200)

quick-zip coordinate variant: No ZIP or FSA boundary found for coordinates {coordinates}. /zip can also report Coordinates {lat},{lon} landed in FSA {fsa} but no postal code could be resolved. Use /quick-zip for FSA-level lookups.

Postal lookup envelopes keep success:true with {success:false,input:{code},error:{code,message,url}} in results. Codes: NOT_FOUND_ZIP, NOT_FOUND_FSA, NOT_FOUND_POSTAL, NOT_FOUND_COORDS_NO_BOUNDARY, and distance NOT_FOUND_FROM/NOT_FOUND_TO. ZIP: ZIP code {zip} not found.; quick-zip batch: Code {code} not found.; FSA: FSA {fsa} not found.; radius: Center code '{code}' not found.; distance: Code '{input}' not found in any boundary table. Unknown ZIP+4 with a known parent ZIP succeeds with detail:{zip4,valid:false}.

See Address Matching for INSUFFICIENT_INPUT, AMBIGUOUS, and NOT_FOUND, also HTTP 200. Address batch validation messages: Address exceeds maximum length of 500 characters., Address exceeds maximum length of 300 characters after cleanup., Address too short to parse (minimum 9 characters).; item INTERNAL_ERROR: Address matching failed for this item.

Error Response Format

{
  "success": false,
  "request": {
    "method": "GET",
    "path": "/v2/quick-zip"
  },
  "error": {
    "code": "AUTH_MISSING_KEY",
    "message": "API key is required. Send it in the X-Api-Key header or the ?key= query parameter. Try the API now with the demo key in error.get_started, see prices and credit packs at https://api.zip-codes.com/pricing.json, or get a key at https://www.zip-codes.com/api/account.",
    "retryable": false,
    "url": "https://www.zip-codes.com/api/account",
    "get_started": {
      "demo_key": "zc_test_DEMOAPIKEY000000000000",
      "demo_scope": "the demo ZIPs, postal codes and addresses listed in https://api.zip-codes.com/llms-full.txt",
      "pricing": "https://api.zip-codes.com/pricing.json",
      "llms_txt": "https://api.zip-codes.com/llms.txt",
      "openapi": "https://api.zip-codes.com/v2/openapi.json",
      "signup": "https://www.zip-codes.com/api/account"
    }
  },
  "meta": {
    "request_id": "01M3SX2VHP0M9TXH8WFHW7ZM3G",
    "version": "2.0.0",
    "timing_ms": 0
  }
}

Rate Limiting

Limits use a one-minute sliding window (six 10-second segments). There are no hourly or daily request limits; daily free credits are a separate allowance.

Allowed authenticated API requests carry X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (Unix timestamp, now + 60 seconds), and X-RateLimit-Window: minute. These headers are absent on health, docs, swagger, OPTIONS and auth-rejected requests. A 429 adds Retry-After: 60. X-Request-Id is a ULID; X-Api-Version is 2.0.

Limits by Rate Tier

{
  "success": false,
  "request": {
    "method": "GET",
    "path": "/v2/quick-zip"
  },
  "error": {
    "code": "RATE_LIMIT_MINUTE",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "retryable": true,
    "url": "https://www.zip-codes.com/api/pricing"
  },
  "meta": {
    "request_id": "01M3SX2VHP0M9TXH8WFHW7ZM3G",
    "version": "2.0.0",
    "timing_ms": 0,
    "rate_limit": {
      "limit": 60,
      "window": "minute",
      "retry_after": 60
    }
  }
}

Buying Credits with a Wallet (MPP)

This API accepts payment programmatically. Anyone with an MPP wallet (a shared payment token paid through Stripe — card or Link), an agent or a person, can buy credits and keep working with no signup, no account and no person on our side. The wallet authorizes each payment (Link, for example, asks its human to approve every payment in the Link app). The scheme is the Machine Payments Protocol (MPP, draft-httpauth-payment): the API answers 402 with a WWW-Authenticate: Payment challenge, you pay it with your wallet, and you send the same request again with the credential in a Payment-Authorization header. A successful answer carries a Payment-Receipt header. Credits are added only after the payment completes (a card clears at once; some methods take longer).

Two moments raise a challenge:

• Out of credits. A data request that runs out of credits answers 402 CREDIT_INSUFFICIENT; when one pack would make that request succeed, it carries the offer (error.payment: the smallest such pack, its price and the payment methods) and the challenge. Pay it and send the request again: the pack is credited and the request answered.
• Buying on purpose. POST /v2/purchase sent without a Payment-Authorization header answers 402 PAYMENT_REQUIRED with the challenge.

Three endpoints, each with its parameters, response fields, examples and errors in the endpoint reference:

• POST /v2/purchase buys one pack (with a key, for that key's account or prepaid card; without one, a new prepaid card).
• GET /v2/balance reads the credit pools of this key's account or prepaid card.
• GET /v2/purchases/{id} reads one purchase by its order number; use it to follow a 202 until status reads succeeded.

Prepaid cards. Sent without any API key, POST /v2/purchase makes a prepaid card: an API key with no account that holds the pack's credits and works on every endpoint until they run out (it has no free daily credits, and runs at 10 requests a minute while empty). Its key is in results[0].api_key. A purchase sent with that key reloads the card. Keep the key: the same payment sent again returns it again only while the card is unused, and for at most 24 hours after the payment settles. From zero, go straight to POST /v2/purchase: a data request without a key answers 401 AUTH_MISSING_KEY, not a purchase offer.

Limits and keys

• GET /v2/purchases/{id} and GET /v2/balance take the key in a header (X-Api-Key or Authorization: Bearer), never ?key= (401). They share a limit of 10 a minute per key; after 20 unknown purchase ids in an hour, purchase lookups answer 429 until the hour ends.
• POST /v2/purchase: 5 payment attempts a minute per key, 20 per IP.
• Test, demo and admin keys cannot read a purchase or a balance (403 AUTH_TEST_KEY_RESTRICTED); test and demo keys cannot buy and get no payment offers.

A pack bought with a key is added to that key's account or prepaid card. The names, credits and prices of the agent packs are live at pricing.json. Paying accepts the Terms of Service.

Supported Countries

HTTP Status Codes

Summary of all HTTP status codes the API can return:

Versioning

The API uses path-based versioning. All current endpoints are under /v2/. The version is also returned in API response metadata as meta.version.

• Backward-compatible changes (new fields, new enrichments, new endpoints) are added without a version bump.
• Breaking changes (removed fields, changed response structure) will only occur in a new version (e.g., /v3/).
• Nothing is removed from v2. An include flag, year, field or endpoint that is retired keeps working: it is still accepted and answered with an ENRICHMENT_FLAG_RETIRED notice (with its data while it exists, otherwise not charged).
• The current version (v2) is stable and actively maintained. There are no plans to deprecate it.
• If a future version is released, v2 will continue to operate for a minimum of 12 months after deprecation notice.
• See our Service Level Agreement and Terms of Service for uptime and usage commitments.

OpenAPI Specification

A machine-readable OpenAPI 3.0 specification is auto-generated from the API and always reflects the current endpoints, parameters, and response schemas.

Changelog

Notable API changes, data updates, and new features.

November 3, 2026

• Tract ACS for every year, 2011–2024: /v2/address and its batch accept acs_tract_{profile}_{YYYY} for every ACS release from 2011 (was 2022–2024), in the same per-year block under data.acs.tract and at the same price, one credit per profile and year delivered. Each year’s tract comes from that year’s Census tracts, so an address’s geo_id can differ between years.
• Private mailboxes printed as PMB n: a unit at a commercial mail receiving agency (a mail drop such as a UPS Store) that does not confirm is read as the renter’s private mailbox, as USPS reads it, and printed as PMB n, with a new UNIT_READ_AS_PMB notice. The ZIP+4, street and house number are unchanged.
• Address notices: MILITARY_ADDRESS now says where USPS puts the parts of an APO/FPO/DPO address (street holds the unit, number the box); HOUSE_NUMBER_CORRECTED is now sent when a house number is read differently from how it was written; ZIP4_WITHHELD on a phantom carrier route says why.
• A wrong /v2 route names the right call: a /v2 path that matches no route answers 404 ROUTE_NOT_FOUND (was 400 MISSING_VERSION) with the call it most likely meant, such as GET /v2/zip?code=10977&include=census for /v2/zip/10977?include=census. A route asked with the wrong method answers 405 METHOD_NOT_ALLOWED with an Allow header. Neither is charged. See Error codes.
• Faster ACS: tract ACS on /v2/address and ACS on /v2/zip are built faster and with less memory. Responses are unchanged.

November 1, 2026

• Buying credits through the API: POST /v2/purchase buys a credit pack with an MPP wallet (a shared payment token paid through Stripe), and an out-of-credits 402 CREDIT_INSUFFICIENT can carry a payment offer to pay and retry. Sent without an API key, a purchase makes a prepaid API key holding the pack’s credits. GET /v2/balance reads your credit pools and GET /v2/purchases/{id} reads one purchase. Purchased credits never expire. The account owner can switch API purchases off on the dashboard’s Settings page. Purchases through the API may answer 503 “paused” with Retry-After while they are switched off on our side.
• Batch with purchased credits: the batch routes now answer for an account holding purchased credits, not only for a subscriber. A free account holding purchased credits gets 300 requests a minute (was 60) while they last.
• API key as Authorization: Bearer: every route accepts the key as a Bearer token as well as X-Api-Key (recommended).
• The payment credential in Authorization: Payment (2.3.1): the paid credential is read from Authorization: Payment …, the MPP default, as well as from Payment-Authorization. The credential's format is shown under POST /v2/purchase.
• TIGER/Line 2026 is current: bare census, cd and state_leg answer from the 2026 Census boundaries under current; 2025 is an earlier year, under its "2025" key (census_2025), and every year from 2010 stays available.
• MCP: pages on www.zip-codes.com and api.zip-codes.com can call the MCP server from a browser (CORS); other sites cannot. MCP clients are unaffected.
• Documentation: the Data sources section lists every dataset the API answers from, and the address notice lists name NO_HOUSE_NUMBER and ZIP4_WITHHELD.

October 19, 2026

• Metro areas are lists (response shape change): in every census period on /v2/zip, /v2/address and their batches, metro_micro_cbsa_statistical_area and metropolitan_cbsa_division are now arrays of every area the ZIP Code overlaps, largest pct_of_zip first (each was a single object, so a ZIP Code in two metro areas lost the second). Read [0] where you read the object.
• Address coordinates charged only when returned: on /v2/address, coordinates costs a credit only when a location is returned.
• ZIP+4 street detail: on /v2/quick-zip and /v2/zip, detail.street[] now sends what USPS publishes. A blank house or unit number is null (it was "0", giving "350 5TH AVE, 0" and "0 GENERAL DELIVERY"); name is uppercase like the rest of the address (5TH, not 5Th); unit numbers such as K01 keep their zeros. record_type H reads Highrise (it read “Highway Contract”) and F reads Firm. Where several USPS records cover one ZIP+4, the same one is always returned.
• Land and water area: /v2/zip zip_info.land_area_sq_mi and water_area_sq_mi now come from the Census ZIP Code Tabulation Area (land area was the boundary polygon’s, water included), and are null for a ZIP Code with no ZCTA of its own.
• No placeholder values: ZIP Codes stored without a location (military and a few PO Box and unique ones) return location, area_codes and elevation as null instead of 0,0, ["000"] and 0; medicare.rating_area_id "0" (none) is null.
• Congressional districts carry their own state on /v2/zip and /v2/address: a ZIP crossing a state line no longer shows the other state’s district under its own state.
• Radius: /v2/radius ACS statistics cover every match in the radius whatever the limit, and each field’s pct follows what Census prints in its percent column (shares use Census’s own totals). Spatial mode no longer lists codes that only graze the circle (pct_inside under 0.01). County names are spelled as on /v2/zip (DeKalb, not Dekalb), on /v2/distance too.
• Suggest: /v2/suggest finds every ZIP Code, PO Box and military ones included; metro areas carry their two-letter state; places, counties and metro areas follow the 2025 Census boundaries, with location at Census’s internal point.
• Documentation: the OpenAPI spec describes nearly every response field, among them the /v2/address fields, confidence levels and codes; the address input guidance asks for one line in mailing order, with any unit before the city.

October 17, 2026

• MCP server: the API’s data as Model Context Protocol tools for AI agents at https://mcp.zip-codes.com/mcp (Claude, Cursor, VS Code and other MCP clients). Without a key every tool answers in demo mode (real values, deeper fields withheld, not charged); with your key in X-Api-Key answers are complete and a tool call costs what its endpoint costs. Connect instructions and the tool list: mcp.zip-codes.com.
• Boundary history: on /v2/zip, /v2/address and their batches, add a year to census, cd or state_leg (for example census_2018, cd_2012, state_leg_2020; 2010–2024) to get that year’s boundaries under its own "YYYY" key beside current. The bare flags return each family’s latest year; asking for the latest year both ways (census and census_2025) returns one block, charged once. A year we do not hold is ignored with VALIDATION_UNKNOWN_ENRICHMENT at no charge.
• Full-resolution Census boundaries: census, congressional and state legislative boundaries now come from the U.S. Census Bureau’s full-resolution TIGER/Line files instead of the simplified cartographic files, and current moves from 2024 to 2025. Overlap percentages shift, most visibly along coasts, and tiny slivers no longer appear. pct_of_area now measures land only: the share of the area’s land, as covered by ZIP boundaries. source reads "U.S. Census Bureau" (was "Census Bureau TIGER/Line Cartographic Boundaries").
• Shared area: /v2/zip boundary rows gain shared_area_sq_mi. /v2/address boundary rows now carry pct_of_zip, pct_of_area and shared_area_sq_mi as null (an address is a point), so both endpoints return the same shape.
• ZIPs without a boundary polygon: about 7,600 ZIPs that have a location but no boundary polygon (for example 06101) now return boundaries on /v2/zip, answered from their point, with the overlap fields null. They previously returned none.
• 2022 metro areas: Census published no CBSA or metropolitan division boundaries for 2022, so census_2022 returns the 2021 TIGER/Line delineation (OMB Bulletin 20-01, the one Census’s 2022 data products use) for both.
• Missing boundary data: a requested family or year whose data is not available returns ENRICHMENT_UNAVAILABLE and is not charged. If a single layer within a delivered year is missing, its keys are null and a DATA_UNAVAILABLE notice names it.
• Time zone for an address: /v2/address and its batch accept timezone and return the same block as /v2/zip, with pct_of_zip null. One credit, charged only when returned.
• Quick ZIP and Distance timezone gain attribution: /v2/quick-zip, /v2/distance and their batches keep timezone as one flat object with every field it had, and add product and attribution; source now names the publisher ("timezone-boundary-builder"), as on /v2/zip. The zone comes from the time zone boundary file: for a ZIP crossing a zone line, the zone covering most of it. Credits are unchanged.
• Data sources: spatial blocks now carry source, product and attribution; each source's license, product page, vintages and refresh cadence are listed under Spatial layers: full provenance.
• Radius: /v2/radius spatial mode now returns pct_inside for about 100 ZIPs that returned null, and ACS aggregates weight them by their real share. county_fips now follows the ZIP data vendor, which changes it for about 100 ZIPs, mostly Connecticut planning regions.
• Fixed: overlap percentages far above 100%, from overlaps that failed to compute, no longer occur.
• Canadian boundaries from Statistics Canada’s boundary files: on /v2/zip and its batch, a Canadian postal code’s or FSA’s census and cd (federal_electoral_district) now come from Statistics Canada’s Boundary Files (full extent) and census FSA file, with the same row fields. A postal code’s areas are those containing its location. An FSA’s polygon includes its coastal and Great Lakes water, so pct_of_fsa is a share of the whole FSA (shares move in about 470 coastal FSAs). FSAs Statistics Canada has no polygon for (for example M5K) are answered from their location, with pct_of_fsa and pct_of_area null; large rural FSAs that timed out (for example X0A) now return. Rows with shares far above 100% no longer occur.
• Canadian census rows unified: on /v2/zip, a Canadian postal code’s and an FSA’s census and federal_electoral_district rows now have the same fields: uid, dguid, areas in square miles and km² (area_sq_mi, area_km2, land_area_sq_mi, land_area_km2), pct_of_area, and type descriptions on FSAs. Federal electoral district and province names are in both languages (name bilingual, plus name_en and name_fr; an FSA’s name was English only). Postal codes also return province. No field was removed.
• Canadian census years: census and cd on a Canadian code return the latest Statistics Canada census (2021); census_2016 / cd_2016 and census_2011 / cd_2011 return that census under its "YYYY" key, one credit each, charged only when returned. A year without a Canadian census (for example census_2024) returns ENRICHMENT_UNAVAILABLE at no charge. Each Canadian period opens with source, product and attribution, then year and vintage (was "source": "Statistics Canada 2021 Census").
• Canadian geography is now statcan (response shape change): on /v2/zip and its batch, a Canadian postal code’s or FSA’s Statistics Canada geography moves from census to statcan, requested with statcan (latest census, 2021; statcan_2021 is the same), statcan_2016 or statcan_2011, one credit each. Federal electoral districts are now a list inside each period, statcan.current.federal_electoral_district, at no extra charge; the top-level federal_electoral_district family is gone. Periods and rows are unchanged. census, census_YYYY, cd and cd_YYYY on a Canadian code still work: they are answered under statcan with an ENRICHMENT_FLAG_RENAMED notice, and asking for an alias and statcan together returns one block, charged once (so census plus cd is now one credit). statcan on a US code returns ENRICHMENT_UNAVAILABLE at no charge. US census and cd are unchanged.
• Canadian time zones: come from the same time zone boundaries as US ZIPs, with source, product and attribution. A postal code’s zone has pct_of_zip null (it is a point); an FSA crossing a zone line lists each zone covering at least 1% of it. About 1% of postal codes had a wrong zone (for example Saskatoon returned America/Adak); they are corrected.
• ACS fields are the same in every year: every ACS field now appears in every year’s response on /v2/zip, /v2/radius and /v2/address. When Census published no item with that meaning in a year, the field is present with column null and every value null, instead of being left out (a 2011 response carried 394 of the 542 fields). Fields that held another item’s value are corrected, among them year_moved_in and year_built bins, households.male_householder.living_alone before 2019, and repeated DP05 rows whose percent could be a count; 74 fields were added for items Census published under no name.
• Server start-up (503 with Retry-After): right after a server start or restart, while their data is still loading (usually under a minute), /v2/radius, its batch and /v2/suggest answer HTTP 503 SERVICE_WARMING_UP with a Retry-After header, not charged. They previously answered meanwhile from a slower fallback whose matches could differ. Once loaded, answers are unchanged. /v2/health reports ready and lists what is still loading.
• Credits: under heavy load a funded account no longer gets a false 402 CREDIT_INSUFFICIENT; when the service is genuinely at capacity the answer is HTTP 503 SERVICE_POOL_EXHAUSTED with Retry-After, not charged. A not-found answer on /v2/zip, /v2/quick-zip, /v2/distance or /v2/radius that cannot be paid now returns 402 CREDIT_INSUFFICIENT instead of a 200 saying a credit was charged, and an uncharged one reads "Not found (no credit charged).". The unused part of a batch reservation is now also returned to your free daily credits, on the day it was charged.
• OpenAPI specification: response schemas are open (a response may gain fields, so clients should ignore fields they do not know) and have permanent names (ZipResponse, ZipBatchItem, AddressResponse, …, replacing generated names such as ZipResultBatchItemApiResponse; the old names stay as deprecated aliases, so SDKs built from them keep working). Fields sent in every response are marked required. Nothing is removed from v2: see Versioning. No response changed.
• Faster: Canadian /v2/radius spatial searches over large areas (worst cases from 6–8 s to under 0.4 s), repeat /v2/zip calls on Canadian FSAs with statcan, and batches, which now run several items at a time while keeping input order and credits. No response changed.
• Address matching: /v2/address now matches city-only addresses (no state or ZIP, for example 123 Main St, Boise) when the street identifies one town, with the notice “State 'XX' inferred from the city.”, and handles more edge cases (recipient lines, unit prefixes, wrong ZIPs, alternate street names).

October 4, 2026

• Boundary families (response shape change): on /v2/zip and /v2/address, congressional and state legislative districts moved out of census.current into their own top-level objects, congressional_district.current and state_legislative.current (with upper and lower), and school districts are now school_district.current. Canadian cd returns federal_electoral_district.current. Each family is keyed so historical periods can be added beside current. A requested family with nothing found returns {"current": null}. Flags and prices are unchanged.
• Congressional primary basis: congressional_district.current.primary now includes basis. On /v2/zip the primary is the district with the largest share of the ZIP’s area; on /v2/address it is the USPS ZIP+4 congressional district.
• Autocomplete notices: /v2/suggest now says “Showing results for” only when the results come from a spelling correction, not on correctly spelled words.
• Agent documentation: a redesigned llms.txt and llms-full.txt, an AGENTS.md with credit-safety notes for AI agents, plus robots.txt and sitemap.xml.
• Faster ACS enrichments: ACS profiles on /v2/zip, /v2/address and /v2/radius are now served from in-memory Census data files instead of database queries, so requests with many ACS years and profiles return significantly faster. Every historical year on /v2/radius now aggregates as quickly as the current year.
• ACS values match Census exactly: every ACS value is now taken directly from the Census Bureau’s published files. Open-ended medians return the Census threshold (for example 250000 for “250,000+”), and values Census could not compute return null rather than 0.
• ACS year availability on /v2/zip: each ACS year block now includes published. When Census published no data for the ZIP’s ZCTA in a requested year (ZCTAs are redrawn every decade), published is false, the profiles are null, and a note says so. Year blocks are returned newest first.

September 2026

• New address engine: /v2/address now runs on a new matching engine that is faster and more accurate, with the same request and response format.
• Address enrichments: coordinates, census, congressional and state legislative boundaries, school districts, and tract ACS profiles for 2011–2024, charged only for the boundary and tract data actually delivered.
• Error next steps: every error includes a public url; FREE_TIER_LIMIT_CAPPED notices link to pricing, and key and credit messages include account links.
• Reference corrections: batch formats and limits, HTTP 200 not-found behavior, emitted errors, per-minute rate limits, and credit formulas in this reference now match the API.

August 2026

• Improved address matching: /v2/address now runs on a rebuilt matching engine that resolves more real-world input to a deliverable ZIP+4. Notably better on addresses that were previously hard to place: misspelled or heavily abbreviated street names, missing or incorrect ZIP codes, alternate and historical street names, and apartment or suite designators.
• Relocated addresses: an address whose delivery point has been moved by the USPS now returns its current ZIP+4 instead of the retired one.
• No charge for undelivered responses: if a request is cancelled or times out before a response reaches you, no credits are charged.

March 2026

• New endpoint: /v2/address — Address matching. Parse and validate raw US street addresses against USPS ZIP+4 delivery-point data. Returns standardized address, ZIP+4, parsed components, and delivery metadata. Launched with a 1-credit base; see September 2026 for enrichments.

March 12, 2026 — ZIP Codes API v2 launched

• Launch: ZIP Codes API v2 went live with ZIP, radius, distance and autocomplete lookups for US and Canadian postal codes, opt-in enrichments, and credit-based pricing.

Frequently Asked Questions