# ZIP Codes API

> Location intelligence for the US and Canada: postal lookups, every geographic overlap a ZIP Code has (counties, places, tracts, districts, school districts, with shares), a normalized 14-year ACS demographic series, spatial radius search and US address matching to ZIP+4. ZIP boundaries are carrier-route derived and refreshed quarterly, not Census ZCTAs. Free accounts: 2,500 credits/day, 60 requests/minute. Base URL https://api.zip-codes.com; authenticate with the X-Api-Key header (?key= also works for quick browser tests; keys in URLs can end up in logs).

Updated 2026-10-29. The complete reference, with batch bodies, every enrichment and the demo ZIPs and addresses, is https://api.zip-codes.com/llms-full.txt.

## For AI agents

- [AGENTS.md](https://api.zip-codes.com/AGENTS.md): credit-safety notes for agents (on a person's key, or your own prepaid card), with cost formulas and measured examples.
- Start with the public demo key (zc_test_DEMOAPIKEY000000000000; demo codes and addresses only, 5 requests/minute) to confirm response shapes before using a user's key.
- Every enrichment flag costs credits; batch routes charge every item, duplicates included, so dedupe first and state the expected credits before a large run. Batch routes need a paid plan or purchased credits.
- With a user's own key, follow-up calls are fine (a radius search, then a /v2/zip lookup of each ZIP it returns): within your plan's credits and per-minute limit (see Rates); a batch route does the same in fewer requests. With the demo key, keep to a few calls.
- Unknown flags, unavailable enrichments and unpublished ACS years are not charged; they return notices, not errors, and retrying will not change them.
- Every error carries a code, a message and a next-step url, plus retryable where it is known.
- Bugs, feature requests, apps built on the API, and research credits go to jharris@zip-codes.com (see Programs and contact). Including the request_id helps.

## MCP server

- [mcp.zip-codes.com](https://mcp.zip-codes.com/llms.txt): the same data as Model Context Protocol tools at https://mcp.zip-codes.com/mcp (Streamable HTTP, stateless, read-only). Claude Code: claude mcp add --transport http zip-codes https://mcp.zip-codes.com/mcp
- [MCP page](https://www.zip-codes.com/api/mcp): what the server does, how to connect, demo mode versus a key.
- No key needed: without one every tool answers in demo mode (real, current values; deeper fields withheld, masked text and null meaning withheld, not missing) and nothing is charged. With a key (X-Api-Key header) answers are complete and a tool call costs what its endpoint costs.
- Six tools call the API (zip_lookup /v2/zip, quick_zip /v2/quick-zip, radius_search /v2/radius, distance /v2/distance, suggest_places /v2/suggest, validate_address /v2/address) with the same include flags; five reference tools are free and need no key (zip_facts, about_data, city_name_rules, county_reference, metro_area_reference).

## Use it for / not for

- Use it for: what a US ZIP or Canadian postal code really covers (every county, place, tract, block group, district and school district it crosses, with shares); ZIP-level and tract-level ACS over time; who lives within a radius (spatial share of each ZIP inside it); matching a US address to its ZIP+4 and that point's districts; Medicare CBSA assignments; autocomplete and distance.
- Not for: countries other than the US and Canada; routing, directions or map tiles; rooftop geocoding (an address resolves to its ZIP+4 point).

## Quick start (demo key, expected output trimmed)

- [GET /v2/zip?code=90210&include=census,cd](https://api.zip-codes.com/docs#zip-details): census.current.county[0] = Los Angeles, pct_of_zip 100, is_usps_primary true; congressional_district.current.districts = CA-32 (62.83% of the ZIP), CA-36 (37.09%), CA-30 (0.08%); primary 32 with basis "Largest share of the ZIP Code area".
- [GET /v2/address?address=9641 Sunset Blvd, Beverly Hills, CA 90210&include=cd,acs_tract_demographic](https://api.zip-codes.com/docs#address): matched 9641 SUNSET BLVD 90210-2938; congressional primary 36 with basis "USPS ZIP+4 congressional district"; acs.tract.current for the containing census tract.
- [GET /v2/zip?code=34.0901,-118.4065](https://api.zip-codes.com/docs#zip-details): a coordinate resolves to ZIP+4 90210-2940.

## ZIP Codes versus Census ZCTAs

| | This API's ZIP boundaries | Census ZCTAs |
|---|---|---|
| Built from | USPS carrier routes, refreshed quarterly | 2020 Census tabulation blocks, delineated once a decade |
| Coverage | every ZIP; PO Box and unique ZIPs as points; military (APO/FPO/DPO) ZIPs with no location | "Not all valid ZIP Codes are represented by a 2020 ZCTA" (Census) |
| Overlaps | every county, tract, district... with pct_of_zip and pct_of_area | none; one area per code |
| ZIP+4 and addresses | yes | no |

Census describes ZCTAs as "generalized areal representations of the geographic extent and distribution of the point-based ZIP Codes built using 2020 Census tabulation blocks" (https://www.census.gov/programs-surveys/geography/guidance/geo-areas/zctas.html). ACS is published only for ZCTAs, so /zip ACS is the same-code ZCTA's, and says so (geography_level "zcta").

## Why this data

- [Every overlap, not one assignment](https://api.zip-codes.com/docs#zip-details): carrier-route ZIP polygons intersect Census, congressional, state-legislative and school-district polygons; every overlap above per-layer sliver thresholds carries pct_of_zip and pct_of_area.
- [USPS assignment beside the geometry](https://api.zip-codes.com/docs#zip-details): the base county is the USPS assignment, usually the county with the most mail; census.current.county shows where the ZIP actually lies, flagging the assigned county is_usps_primary. ZIP 02872 (Prudence Island, RI): USPS county Bristol (44001); Newport (44005) covers 98.74% of the ZIP, is_usps_primary false.
- [ACS normalized across years](https://api.zip-codes.com/docs#zip-details): Census renumbers Data Profile columns between years (339 of the 528 fields served change column code somewhere in 2011-2024); each field keeps one name across years, ZCTAs, tracts and radius aggregates, and every value names its source column (social.citizenship.foreign_born_total is DP02_0093 in 2015 and DP02_0095 in 2024), with table, vintage and GEO_ID per year block.
- [ACS time series](https://api.zip-codes.com/docs#zip-details): 14 years (2011-2024) of ACS 5-Year profiles by ZCTA on /zip and /radius, 2022-2024 by census tract on /address; several years in one call.
- [Spatial radius](https://api.zip-codes.com/docs#radius): mode=spatial intersects a geodesic circle with ZIP/FSA boundaries; pct_inside is the share of each inside it, and US ACS counts are area-weighted in stats.acs.
- [Any input, ZIP to coordinates](https://api.zip-codes.com/docs#zip-details): /zip, /quick-zip and /radius accept ZIP, ZIP+4, Canadian FSA, full postal code or latitude,longitude.
- [Address-level geography](https://api.zip-codes.com/docs#address): the matched ZIP+4 point decides county (Connecticut: its planning region), districts, school district and the ACS tract.
- [Medicare geography](https://api.zip-codes.com/docs#zip-details): include=medicare returns the ZIP's CMS CBSA code/name/type, rating_area_id and ssa_state_county_code.
- [Postal and Canadian coverage](https://api.zip-codes.com/docs#zip-details): delivery-point and ZIP+4 counts, city aliases, metro areas, elevation; Canadian FSAs and postal codes get Statistics Canada geography under statcan (include=statcan, 2021; statcan_2016, statcan_2011), federal electoral districts inside each period, FSA overlaps with pct_of_fsa; census/cd on a Canadian code are answered as statcan; Canada has no ACS.

## Sources and refresh

- US ZIP boundaries: carrier-route derived, quarterly. US ZIP base data and ZIP+4: monthly. Census boundaries: full-resolution TIGER/Line 2026 (earlier years 2010-2025 by year flag). School districts: NCES 2024-2025. ACS: 5-Year Data Profiles 2011-2024, annual. Canada: Canada Post codes monthly; Statistics Canada 2021 geographies.

## ACS tables

Four ACS 5-Year Data Profile tables, 528 normalized fields (423 present in all 14 years). Request a table with its flag on /zip and /radius, or the acs_tract_ flag on /address; each field is {column, est, moe, pct, pct_moe} on /zip and /address; radius summaries carry est and pct.

- [Demographic: acs_demographic, Census DP05, 94 fields](https://api.zip-codes.com/docs#enrich-acs): sex and age (age bands, median age, 18+, 65+), race (one race with detail, two or more, alone or in combination), Hispanic or Latino by origin, total housing units, citizen voting-age population.
- [Social: acs_social, Census DP02, 154 fields](https://api.zip-codes.com/docs#enrich-acs): household types and size, relationship, marital status, fertility, grandparents as caregivers, school enrollment, educational attainment, veterans, disability, residence 1 year ago, place of birth, citizenship, year of entry, world region of birth, language spoken at home, ancestry, computers and broadband internet.
- [Economic: acs_economic, Census DP03, 137 fields](https://api.zip-codes.com/docs#enrich-acs): employment status and labor force, commuting mode and travel time, occupation, industry, class of worker, income and benefits (household and family brackets, median, mean, per capita), health insurance coverage, poverty by family type.
- [Housing: acs_housing, Census DP04, 143 fields](https://api.zip-codes.com/docs#enrich-acs): occupancy and vacancy, units in structure, year built, rooms, bedrooms, tenure, year moved in, vehicles available, heating fuel, plumbing/kitchen/telephone, occupants per room, home value, mortgage status, owner costs and owner costs as a percentage of income, gross rent and rent as a percentage of income.

## Calling it correctly

- [Authentication](https://api.zip-codes.com/docs): X-Api-Key header (recommended) or Authorization: Bearer with your key; ?key= is accepted for convenience but keeps the key in URLs and logs.
- [Radius parameters](https://api.zip-codes.com/docs#radius): the radius is max (miles), not radius; min is the inner radius; centroid is the default; spatial mode needs an individual /v2/radius call.
- [ACS flags](https://api.zip-codes.com/docs#zip-details): acs_{demographic,social,economic,housing}[_YYYY] on /zip and /radius, acs_tract_{...}[_YYYY] on /address; unsuffixed and _2024 are the same request, charged once.
- [Unknown flags](https://api.zip-codes.com/docs#response-envelope): ignored without charge, reported as VALIDATION_UNKNOWN_ENRICHMENT in meta.notices; an out-of-range ACS year is an unknown flag.
- [Unpublished ACS](https://api.zip-codes.com/docs#zip-details): a ZCTA/year Census did not publish returns published:false with null profiles and is not charged.
- [Empty boundary families](https://api.zip-codes.com/docs#response-envelope): a requested family that finds nothing is {current:null}.
- [Congressional primary](https://api.zip-codes.com/docs#address): /zip uses the largest ZIP-area share; /address uses the USPS ZIP+4 district (else the district containing the point); primary.basis says which.
- [Address input](https://api.zip-codes.com/docs#address): one line in mailing order: number and street, then any unit (APT 4, STE 900, #9), then city, state and ZIP. With a ZIP, city and state are optional; without one, give city and state. It tolerates ordinary slips (a misspelling, a missing ZIP or directional), but a unit after the city or ZIP ("Pensacola FL #9") is ambiguous, a unit or a floor. Send the address once; if it does not match, report that rather than trying rewrites.
- [Address results](https://api.zip-codes.com/docs#address): confidence is high: the address matches a USPS record exactly, number and unit included. medium: it matched after a relaxation (a corrected spelling, an inferred state, a dropped suffix or directional, a building's default record). low: the match needed heavy repair or left input out, or the ZIP+4 is withheld (plus4 is then absent). Notices: MATCHED (confidence high) or PARTIAL_MATCH (medium or low), then any of ZIP_CORRECTED, CITY_CORRECTED, STATE_CORRECTED, STREET_CORRECTED, HOUSE_NUMBER_CORRECTED, NO_HOUSE_NUMBER, SECONDARY_NEEDED (the building has units: ask for one), SECONDARY_NOT_VERIFIED (the unit given could not be confirmed), INPUT_NOT_USED, ZIP4_WITHHELD; each is explained in llms-full.txt.
- [Not found and no match](https://api.zip-codes.com/docs#response-envelope): lookup not-found is HTTP 200 per item; a single-address no-match is top-level success:false; meta.notices is omitted when empty.

## Single endpoints

- [GET/POST /v2/quick-zip](https://api.zip-codes.com/docs#quick-zip): optional timezone (one flat object: source, product, attribution as on /v2/zip, then the zone covering most of the ZIP); credits = base * (1 + timezone + reverse_geocode), base 2 for ZIP+4, otherwise 1.
- [GET/POST /v2/zip](https://api.zip-codes.com/docs#zip-details): full lookup; 1 + billable flags + reverse_geocode credits.
- [GET/POST /v2/radius](https://api.zip-codes.com/docs#radius): centroid/spatial search; distance-band base * (1 + timezone/ACS requests + auto_radius); ACS aggregates in stats.acs, newest year first.
- [GET/POST /v2/distance](https://api.zip-codes.com/docs#distance): distance and bearing, 1 credit per pair; timezone per point (one flat object: source, product, attribution as on /v2/zip, then the zone containing the point).
- [GET/POST /v2/suggest](https://api.zip-codes.com/docs#suggest): autocomplete; limit bands <=15/50/150/500 cost 1/2/3/5; POST is single, no suggest batch.
- [GET/POST /v2/address](https://api.zip-codes.com/docs#address): optional coordinates, census, cd, state_leg, school_district, timezone and acs_tract_* (2022-2024); cost = 1 + delivered coordinates + delivered boundary flags + delivered timezone + delivered tract tags; no match costs 1 (+1 for coordinates). Single address validation typically completes in under 15 ms of server time, with 99% under 50 ms; a batch of 250 addresses (no enrichments) typically completes in under 100 ms. Network time not included. Paths under results[i].data: location, census.current, congressional_district.current, state_legislative.current, school_district.current, timezone (same object as /v2/zip's timezone, one zone with pct_of_zip null); every spatial block carries source, product, attribution (license, product page and vintages: https://api.zip-codes.com/docs#data-sources), acs.tract.{current|2023|2022}.
- [GET /v2/health](https://api.zip-codes.com/docs#health): database health, no key or credits.

## Five batch routes

- [POST /v2/quick-zip/batch](https://api.zip-codes.com/docs#batch-endpoints): codes array, optional include; maximum 100.
- [POST /v2/zip/batch](https://api.zip-codes.com/docs#batch-endpoints): codes array, optional include; maximum 100.
- [POST /v2/radius/batch](https://api.zip-codes.com/docs#batch-endpoints): searches array of {code,max,min,include,limit}; centroid only; maximum 100.
- [POST /v2/distance/batch](https://api.zip-codes.com/docs#batch-endpoints): pairs array of {from,to}; maximum 100.
- [POST /v2/address/batch](https://api.zip-codes.com/docs#address): addresses array, include string or array; maximum 250. All batches need a paid subscription or purchased credits and charge each item, duplicates included.

## Paying with a wallet (Stripe 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, buys credits 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 API answers 402 with a WWW-Authenticate: Payment challenge (MPP, draft-httpauth-payment); pay it and resend the same request with the credential in a Payment-Authorization header. A successful answer carries a Payment-Receipt header; credits are added only after the payment completes.
- The credential: "Payment " + base64url (no padding) of {"challenge":{"id","realm","method","intent","request","expires": the challenge's parameters exactly as received},"payload":{"spt":"spt_…" (the wallet's shared payment token for the challenge's amount)}}. Authorization: Payment … (the MPP default) is read the same way; to pay with a key, send the key in X-Api-Key. A prepaid card's key starts pp_card_ (account keys zc_live_).
- Out of credits: a data request's 402 CREDIT_INSUFFICIENT carries an offer (error.payment: the smallest pack that makes it succeed) and the challenge. Pay it, resend, and the pack is credited and the request answered.
- [POST /v2/purchase](https://api.zip-codes.com/docs#purchase): buy a pack on purpose ({"pack":"Mini"}, or price_usd or credits, each naming one agent pack in pricing.json; sent together they must name the same pack). Without a credential it answers 402 PAYMENT_REQUIRED with the challenge. results[0] is the purchase: {purchase_id, status, api_key?, pack, charged, credits, receipt_url, created, settled, terms}. 201 paid and credited; 202 still clearing (status processing): keep purchase_id and read GET /v2/purchases/{id}, never buy again; 200 the same credential again, nothing charged twice. Errors: PAYMENT_FAILED, PAYMENT_CREDENTIAL_INVALID, PAYMENT_PENDING, PACK_NOT_AVAILABLE, PURCHASES_DISABLED, PURCHASES_ON_HOLD, AUTH_TEST_KEY_RESTRICTED.
- No key at all: POST /v2/purchase sent without one makes a prepaid card, an API key with no account holding the pack's credits, in results[0].api_key; use it on every endpoint, and buy with it to reload the card. Keep the key: the same payment sent again returns it only while the card is unused and for 24 hours. From zero, call POST /v2/purchase directly — a keyless data request answers 401 AUTH_MISSING_KEY, not a purchase offer.
- [GET /v2/purchases/{id}](https://api.zip-codes.com/docs#purchase-lookup): read one purchase by its order number (PP- through the API, ZC- on the website; dashes and case forgiven). status is processing, succeeded, failed, refunded or disputed; an unknown id, or one on another account or card, answers 404 PURCHASE_NOT_FOUND.
- [GET /v2/balance](https://api.zip-codes.com/docs#balance): the credit pools (results[0] = {free|null, subscription|null, purchased, purchase_url, packs}; a prepaid card has purchased only). A request draws on free or subscription first, then purchased. The balance and purchase lookups take the key in a header (X-Api-Key or Authorization: Bearer), never ?key=; 10 a minute per key, shared.
- A pack is added to the account or prepaid card of the key that pays, and purchased credits never expire. The account owner can switch API purchases off (PURCHASES_DISABLED); test and demo keys get no offers and cannot buy. Paying accepts the Terms of Service: https://www.zip-codes.com/api/tos.

## Rates

- [pricing.json](https://api.zip-codes.com/pricing.json): plans, credit packs, free allowance, per-plan rate limits and key counts, and credit formulas as JSON, generated from the live billing configuration.
- Credit packs ($19 for 25,000 up to $799 for 2,000,000; agents buying through the API can also choose $5 and $10 packs) never expire and stack on top of the free 2,500 credits/day; a subscription ($49/100,000 a month and up) replaces the daily free credits; either one opens batch access. Light users usually pay least with free credits plus a pack.
- [Rate limits](https://api.zip-codes.com/docs#rate-limiting): per minute only: Free 60, Restricted 20, Developer 300, Professional 300, Business 600, Enterprise 1800, Demo 5/IP, Prepaid 300 (a free account holding purchased credits, while they last, or a prepaid card holding credits), an empty prepaid card 10; rate headers are not on every response.

## Programs and contact

- [Bugs and feature requests](mailto:jharris@zip-codes.com): jharris@zip-codes.com. Every message is read, and feature requests from agents and developers shape what gets built. Include the request_id and your use case.
- [Featured apps and tools](mailto:jharris@zip-codes.com): built something with the API? Send it to jharris@zip-codes.com; apps and tools we feature get 100,000 credits.
- [Research credits](mailto:jharris@zip-codes.com): college and university researchers, email jharris@zip-codes.com with a line about your project; we grant free credits for genuine research.

## Coming soon (planned, not available)

- ACS time series at higher geographies (tract, county, place) for modeling.

## Optional

- [Get a key and pricing](https://www.zip-codes.com/api/pricing): free keys, subscriptions and credits.
- [Documentation](https://api.zip-codes.com/docs): the human reference (large HTML page).
- [MCP server](https://mcp.zip-codes.com/): connect instructions and the tool list.
- [OpenAPI](https://api.zip-codes.com/v2/openapi.json): machine-readable contract.
- [API catalog](https://api.zip-codes.com/.well-known/api-catalog): RFC 9727 linkset naming the OpenAPI, docs, pricing and health URLs.
- [Playground](https://api.zip-codes.com/docs/playground): interactive requests and responses.
- [Changelog](https://api.zip-codes.com/docs#changelog): dated API changes, data updates and new features.