# 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-18. 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 using a person's key, 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.
- With a user's own key, follow-up calls are fine (a radius search, then a /v2/zip lookup of each ZIP it returns): credits are the only limit, and 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
- 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, unique and military ZIPs as points | "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 2025 (earlier years 2010-2024 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); ?key= is accepted for convenience but keeps the key in URLs and logs; Authorization: Bearer is not accepted.
- [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.
- [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 + requested coordinates + delivered boundary flags + delivered timezone + delivered tract tags; no match costs 1 (+1 for coordinates). 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 and charge each item, duplicates included.

## 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) 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 and adds 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; 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.
- An autonomous agent purchase path for pay-as-you-go credits, through Stripe.

## 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.