zip-codes.com

``` ========================================================================================== FREE TIER (NO API KEY): READ THIS FIRST ========================================================================================== ``` Every tool answers without an API key, and what it returns is **real**: current, curated ZIP Code data, not a sample and not placeholder data. Use the shown values as you would a keyed answer. - **Current, monthly.** Rebuilt from USPS updates every month. A ZIP Code and its name rarely change, but what sits under it does: ZIP+4s and delivery points are added, removed and moved between ZIPs (military addresses often), so a ZIP's counties and its multi-county status can change from one month to the next. Boundaries follow real carrier routes. - **ZIPs that free data lacks.** Census ZCTA files leave out ZIPs with no area of their own, such as PO Box and single-organization ZIPs. They are here. - **Boundary history.** Administrative boundaries move too (Connecticut's counties became planning regions in 2022). `census_YYYY`, `cd_YYYY` and `state_leg_YYYY` give any year from 2010. **Some deeper fields are withheld without a key.** The JSON structure is identical to a keyed response; only values are held back: - withheld text reads as asterisks, one per character up to five (`*` to `*****`); - withheld numbers and true/false read `null`, and those are *not* null in a keyed response; - a long list is truncated, with a `*_truncated` marker beside it, and the full count stays in `summary`; - `meta.demo.withheld_count` says how many values were held back. **With an API key nothing is withheld.** Every value is the real answer, `null` included: a `null` in a keyed response means the data does not exist (for example, Census published none), never that it was held back. Only a response carrying `meta.demo` has withheld values. **Withheld is not missing.** Never report a masked or `null` value as the answer, or as "no data". If the question needs a withheld field, tell the user an API key returns it, rather than guessing or substituting another source. A free key gives 2,500 credits a day: <https://www.zip-codes.com/api/signup>. **Demo values: full depth without a key.** These come back complete, exactly as with a key (no `meta.demo`, nothing withheld): ZIP Codes 90210, 10001, 10118, 32504, 00601, 96950, 33139, 60601, 98101, 30301 (and any ZIP+4 in them); Canadian FSAs M5V, K1A, V6B, T2P, H3A (and any postal code in them); postal codes M1R 0E9, V5K 0A1, K1A 0A1, T1X 0L3, H1A 0A1; coordinates inside any of them; a `radius_search` from one of them up to 10 miles; a `distance` between two of them; and these addresses for `validate_address`: 1600 Pennsylvania Ave NW, Washington DC; 1 Arizona Memorial Pl, Honolulu HI 96818; 300 Alamo Plaza, San Antonio TX 78205; 3764 Elvis Presley Blvd, Memphis TN 38116; 400 Broad St, Seattle WA 98109; 11 N 4th St, St Louis MO 63102; 4 Jersey St, Boston MA 02215; 150 Calle de la Fortaleza, San Juan PR 00901; ATTN Admissions, 77 Massachusetts Ave, Cambridge MA 02139; 200 E Colfax Ave, Denver 80203; 1 Infinite Loop, Cupertino; 1 Infinite Loop, Cupertino, CA; ATTN Leasing Office, 233 S Wacker Dr Ste 4700, Chicago IL 60606; 350 Fifth Avenue, New York NY 10118; 20 W 34th St, New York NY 10001; 1060 W Addison St, Chicago IL 60613; 3700 SW 328th St, Homestead FL 33033; 8039 Beach Blvd, Buena Park CA 90620; 1 Rocket Rd, Hawthorne CA 90250; PO Box 1142, Beverly Hills CA 90213; 750 N Glebe Rd, Arlington VA 22203; 1600 Pennsylvania Ave NW, Washington DC 20500; 9641 Sunset Blvd, Beverly Hills, CA 90210; 350 5th Ave, New York, NY 10118; 4034 Elmcrest Dr, Pensacola, FL 32504; 123 Nowhere Lane Faketown ZZ; 999 Nonexistent St, Beverly Hills, CA 90210; 1600 pennsylvania ave nw washingtn dc; 1600 pensylvania ave nw washingtn dc; 350 fifth avenue apt 101 new york ny; 350 5th ave apt 101 new york ny; po box 1234 beverly hills ca 90210; p.o. box 1234 beverly hills ca 90210; 400 BROAD st seattle WA. ``` ========================================================================================== ``` zip-codes.com — **location intelligence for the United States and Canada**. Postal geography, census geography, demographics and survey estimates, keyed to a place you can name: an address, a ZIP Code, a ZIP+4, a Canadian FSA or postal code, or a latitude/longitude pair. **What is hard to get elsewhere** 1. **Fourteen years of American Community Survey data in one schema.** The four profiles (demographic, social, economic, housing) use *identical field paths in every year* from 2011 to 2024, and at every geography level (ZIP Code areas and census tracts), so years and places can be compared directly, with nothing to reconcile or rename. `include` takes the REST API's flags verbatim: `acs_social` is the current release, `acs_social_2015` an earlier one (the `include` description lists the years served; `acs_years` remains as an alias). Several years come back keyed by year, and each field carries its source Census table and column (radius aggregates carry neither a column nor a margin of error). `pct` is what Census prints in the field's percent column: a share of its total for most fields, but the count itself on a total row, and null where Census gives no percent (per capita income). A rate is in whichever column Census prints it: unemployment and poverty rates in `pct` (`est` null), the housing vacancy rates in `est` (`pct` null). In a radius, `coverage_pct` under 100 is normal: PO Box, unique and other point ZIP Codes have no area of their own, so Census publishes nothing for them, and their residents are counted in the surrounding ZIP Codes. The totals are not short. Census, congressional and state legislative boundaries work the same way: `census`, `cd`, `state_leg` for the newest TIGER/Line year, `census_2015`, `cd_2020`, `state_leg_2018` for another; a flag naming the newest year (`cd_2025` today) is answered under `current`. Districts come from the legal boundaries; an address's `details.congressional_district` and its newest-year `primary` are USPS's ZIP+4 assignment, which can be wrong, so compare `districts`, not `primary`, across years. 2. **Which census geographies a place overlaps, and by how much.** Tract, block group, place, county, CBSA, congressional district and state legislative district each carry `pct_of_zip` and `pct_of_area`. The geography lists are public; the overlap is the work. 3. **Standardisation and placement.** `validate_address` parses an address string into components and places it to a ZIP+4. `quick_zip` reads a ZIP+4 back to its street ranges, or turns coordinates into the code containing them. 4. **What USPS says, and what is on the ground.** ZIP Codes follow mail routes, not political lines, so this server gives two kinds of answers on purpose. USPS's assignments: a ZIP's `state` and `county`, `multi_county` (from the counties USPS gives its ZIP+4 records) and, for an address, `details.county` and `details.congressional_district`. These are what USPS-based systems show, are maintained by local post offices and are sometimes wrong; USPS's county for a ZIP is not necessarily the one covering most of it. The boundary enrichments (`census`, `cd`, `state_leg`, `school_district`, `timezone`) intersect the ZIP's area with the official boundaries; `pct_of_zip` is a share of area, not of addresses or people, and a ZIP can cross any of them, a state line included. When the two disagree, report both. A small `pct_of_zip` is real area that may hold few or no addresses ("a small part of the ZIP extends into …"). **Choosing a tool.** `zip_lookup` for everything attached to a code; `validate_address` for a street address; `radius_search` to find codes near one; `distance` between two places; `suggest_places` to resolve a vague or misspelled name first. Enrichments are opt-in per call and each one adds to the credit cost, so ask for what you need rather than everything. **Scope — these tools answer for one place per call.** With your own API key, follow-up calls are fine: a radius search and then a lookup of each ZIP Code it returns, for example. Credits are the only limit. Without a key (the shared demo), keep to a few calls per question. For long lists the REST API's batch endpoints are faster (this server does not expose them, to keep responses within a context window): `POST /v2/zip/batch`, `/v2/quick-zip/batch`, `/v2/radius/batch` and `/v2/distance/batch` take up to 100 items per request and `/v2/address/batch` takes 250, all with a subscription; there is no suggest batch. Request bodies are in <https://api.zip-codes.com/llms.txt> and the spec below. Going the other way, the reference tools here (`zip_facts`, `about_data`, `city_name_rules`, `county_reference`, `metro_area_reference`) have no REST equivalent. Neither surface contains the other. Docs <https://www.zip-codes.com/api/> · OpenAPI <https://api.zip-codes.com/swagger/v2/swagger.json> · Postman <https://api.zip-codes.com/postman/ZIP_Codes_API_v2.postman_collection.json> · Terms of Service <https://www.zip-codes.com/api/tos> **Provenance.** `about_data` gives each dataset's authority, edition and refresh cadence; `zip_facts` gives corpus counts. Both are free and need no key. Prefer citing these over assuming currency.