# ZIP Codes API > US and Canadian postal lookups, radius and distance search, autocomplete, and US address matching with ZIP+4. US ZIP boundaries are carrier-route derived, built from USPS delivery routes, not Census ZCTAs, and every Census, district and school-district overlap is a real polygon intersection with its share of the ZIP and of the area. ACS is a 14-year time series (2011-2024) by ZCTA on /zip and /radius, and 2022-2024 by census tract on /address, normalized so each field means the same thing in every year. Spatial radius search calculates the percentage of each ZIP's area inside the radius. Base URL: https://api.zip-codes.com. Authenticate with the X-Api-Key header or ?key=. ## Why this data - [ZIP boundary overlaps](https://api.zip-codes.com/docs#zip-details): each returned US Census, congressional, state-legislative or school-district polygon overlap carries pct_of_zip and pct_of_area; the USPS-assigned county is flagged is_usps_primary. - [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); here each field keeps one name in every year and at every geography (ZCTA, tract, radius aggregates), so years compare like for like. Every value carries its source column (social.citizenship.foreign_born_total is DP02_0093 in 2015 and DP02_0095 in 2024), and each year block names its table, vintage and GEO_ID. - [ACS time series](https://api.zip-codes.com/docs#zip-details): 14 years of ACS 5-Year demographic, social, economic and housing profiles on /zip and /radius; several years can be requested in one call. - [ZIP versus ZCTA](https://api.zip-codes.com/docs#zip-details): /zip ACS uses the same-code ZCTA, the geography Census publishes ACS for, not the carrier-route-derived ZIP polygon; PO Box, unique and military ZIPs are point-only and normally have no ACS. - [Spatial radius](https://api.zip-codes.com/docs#radius): mode=spatial intersects a geodesic circle with ZIP/FSA boundaries; pct_inside measures the ZIP/FSA area inside it, and US ACS counts are area-weighted in stats.acs; point-only ZIPs have pct_inside:null. - [Address-level geography](https://api.zip-codes.com/docs#address): the matched ZIP+4 record's point determines Census, district and school-district containment and the tract used for ACS. - [Postal and Canadian coverage](https://api.zip-codes.com/docs#zip-details): US base fields include delivery-point counts, ZIP+4 counts, city aliases, metro areas and elevation; Canadian FSAs include Statistics Canada 2021 polygon overlaps with pct_of_fsa/pct_of_area, while full postal codes use assigned Census geographies; Canada has no ACS. - [Boundary periods](https://api.zip-codes.com/docs#zip-details): census, congressional_district, state_legislative and school_district are served as current only today, with a per-period key structure for history to come; boundary history is not available today. ## Calling it correctly - [Radius parameters](https://api.zip-codes.com/docs#radius): use max, not radius; min is the inner radius; centroid is the default, and spatial mode requires an individual /v2/radius call. - [ACS flags](https://api.zip-codes.com/docs#zip-details): use acs_{demographic,social,economic,housing}[_YYYY] on /zip and /radius, or acs_tract_{demographic,social,economic,housing}[_YYYY] on /address; unsuffixed and _2024 select the same current-year request and are charged once on every endpoint. - [Unknown flags](https://api.zip-codes.com/docs#response-envelope): single enrichment requests ignore unknown flags without charge and report 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): when Census published no data for a requested ZCTA/year, /zip returns published:false with null profiles and does not charge that year's flags; /address tract ACS has no published field. - [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 chooses the district with the largest ZIP-area share; /address uses the USPS ZIP+4 district, falling back to the district containing the matched point when the USPS district is absent; primary.basis says which. - [Address input](https://api.zip-codes.com/docs#address): with a ZIP, city and state are optional; without a ZIP, give city and state; GET include is comma-separated, and single POST include must be a string. - [Notices](https://api.zip-codes.com/docs#response-envelope): meta.notices is omitted when empty. ## Reference - [Documentation](https://api.zip-codes.com/docs): parameters, responses, errors, rates and credits. - [Complete agent reference](https://api.zip-codes.com/llms-full.txt): standalone reference with batch bodies, enrichment examples, and the public demo key with its demo ZIPs and addresses. - [OpenAPI](https://api.zip-codes.com/v2/openapi.json): machine-readable API contract. - [Playground](https://api.zip-codes.com/docs/playground): interactive requests and responses. - [Get a key and pricing](https://www.zip-codes.com/api/pricing): free keys, subscriptions and credits. ## Single endpoints - [GET/POST /v2/quick-zip](https://api.zip-codes.com/docs#quick-zip): optional timezone; 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. - [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 and acs_tract_* profiles for 2022-2024; cost = 1 + requested coordinates + delivered boundary flags + delivered tract tags; unavailable flags are free with ENRICHMENT_UNAVAILABLE; no match costs 1 (+1 for coordinates). - [Address response paths](https://api.zip-codes.com/docs#address): below results[i].data: location, census.current, congressional_district.current, state_legislative.current, school_district.current, 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}; top-level include/max/min defaults and mode, 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 require a paid subscription and charge each item, including duplicates. ## Response and rate rules - [Response contract](https://api.zip-codes.com/docs#response-envelope): lookup not-found is HTTP 200 per-item; single address no-match has top-level success:false, batch unmatched has success:true and matched:false; null model fields are generally omitted, with explicit exceptions such as {current:null}; request IDs are ULIDs; every error includes a next-step url, while only FREE_TIER_LIMIT_CAPPED notices include url (pricing). - [Free credits](https://www.zip-codes.com/api/pricing): free accounts receive 2,500 credits/day and 60 requests/minute. - [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.