Developer API
ZipVitals public data API
Free, public, read-only access to the persisted per-ZCTA (ZIP Code Tabulation Area) health dataset — one endpoint, no key, no sign-up. It reads already-published data (no generation, no live model calls), and every response carries its own license block so a reused value travels with its terms.
Machine-readable spec: /api/v1/openapi.json · Methodology & sources: /methodology
Get started
Quickstart
Request one ZCTA by its 5-digit code. The response is JSON — the full published bundle for a fully-covered ZCTA, or a slim body for a restricted-coverage one (see the contract below).
curl -s https://zipvitals.com/api/v1/zcta/90210Or open it in your browser: /api/v1/zcta/90210. A malformed or non-ZCTA 5-digit code returns 404 — a USPS ZIP is never coerced into a result.
Reference
Endpoint
Returns the full per-ZCTA payload for a `full`-coverage ZCTA. A restricted-coverage ZCTA returns a slim body (no composite score / ranks / narrative) per ADR-0033. A non-ZCTA 5-digit code or an unknown code returns 404 (the ZCTA canonical-key contract, ADR-0002 — a USPS ZIP is never coerced to a result).
Path parameter
| Name | Type | Description |
|---|---|---|
| zcta | string(^\d{5}$) | A 5-digit ZIP Code Tabulation Area code. |
Response codes
| Status | Meaning |
|---|---|
| 200 | The ZCTA dataset (full) or a slim restricted-coverage body. |
| 404 | Not a ZCTA (malformed or non-ZCTA 5-digit code) or unknown ZCTA. |
| 429 | Rate limit exceeded. |
| 500 | An unexpected read failure. Retryable — the endpoint reads persisted data, so the same request may succeed once the underlying read recovers. |
A 200 is one of two shapes — the full bundle or a slim restricted-coverage body. See the ZCTA contract.
Reference
Response shape (full)
A fully-covered ZCTA returns these top-level fields. Every response is stamped with a schema_version — the shape is an explicit, versioned public contract, decoupled from internal types, so a page-layer refactor can never silently break a consumer. Field-level detail (nested objects, enums) is in the OpenAPI spec.
| Field | Type | Notes |
|---|---|---|
| schema_version | string | |
| zcta | string | |
| state | string | |
| centroid | object | |
| place_name | string | null | |
| editorial_status | string | |
| as_of | object | |
| score | object | null | The composite health index + ranks. Null when the ZCTA is unscored. |
| metrics | object[] | The calibrated KPI metrics for this ZCTA (ADR-0058 bundle). |
| narrative | object | null | |
| places | object[] | CDC PLACES model-based health measures. |
| acs | object | null | Census ACS 5-Year demographic + socioeconomic values. The 13 `*_rate` fields are FRACTIONS (0.106 = 10.6%), not percentages; the three `median_*` money fields are dollars. Null when the ZCTA has no ACS row. |
| acs_context | object | National + state distribution anchors (p10/p50/p90) per ACS metric. Keyed by the SAME field names as `acs`, so `acs.poverty_rate` joins to `acs_context.poverty_rate` directly. Present for all `acs` fields except `data_year` and `total_population`, which have no distribution anchors. A key is absent when no aggregate row exists for the metric. |
| usaleep | object | null | |
| usaleep_context | object | |
| neighbors | object[] | Sister ZCTAs (geographic, similar-health, closest-healthier). |
| env_co_occurrence | object | Combined-exposure indicators (ADR-0083): the environmental-hazard pairs that co-fire in this ZCTA. Carries only the fired pairs and, per pair, whether both legs cross their federal reference line — never a co-fire count, lift, or correlation. An empty `pairs` array means no pair fired (not impacted). |
| license | License |
Operations
Rate limits
Requests are limited per client IP with a sliding window: 60 requests per 60 s. Every successful response carries the standard rate-limit headers; exceeding the limit returns 429 with Retry-After.
| Header | Meaning |
|---|---|
| RateLimit-Limit | Requests allowed per window. |
| RateLimit-Remaining | Requests remaining in the window. |
| RateLimit-Reset | Unix-seconds when the window resets. |
| Retry-After | Seconds to wait before retrying (on 429). |
Behavior
The ZCTA contract
The API key is the ZCTA (ZIP Code Tabulation Area), the Census unit — not a USPS ZIP. The response mirrors the per-ZIP page’s URL contract exactly:
- Full → 200 with the bundle
- A fully-covered ZCTA returns the complete published payload — score, ranks, metrics, narrative, neighbors, and the license block.
- Restricted-coverage / excluded → slim 200
- A real ZCTA whose per-source coverage forbids the composite score, ranks, and narrative returns a slim body (zcta, editorial_status, canonical_url, message, license) — a machine-readable mirror of the page’s redirect. The full payload is never fetched, so nothing forbidden can leak. It is a 200, not a 404, because the ZCTA is real — a 404 would be dishonest.
- Non-ZCTA / unknown → 404
- A malformed or non-ZCTA 5-digit code, or an unknown code, returns 404. A USPS ZIP is never coerced into a ZCTA result — this is the canonical-key contract.
Terms
License & attribution
CC BY 4.0 on ZipVitals’s derived columns — the composite ZipVitals Score, its sub-scores, percentile ranks, and narrative text. Attribute as “ZipVitals, CC BY 4.0” (license). Upstream source licenses are preserved and never overridden (ADR-0034 §D). Attribution required for derived columns under CC BY 4.0. CC BY-NC upstream values are non-commercial.
Upstream source licenses are preserved, never overridden. Every response carries this same block per source:
| Source | License | Commercial use |
|---|---|---|
| CDC PLACES | U.S. federal government work — public domain (17 U.S.C. §105) | Permitted |
| U.S. Census Bureau ACS 5-Year | U.S. federal government work — public domain (17 U.S.C. §105) | Permitted |
| CDC USALEEP | U.S. federal government work — public domain (17 U.S.C. §105) | Permitted |
| CMS Hospital General Information | U.S. federal government work — public domain (17 U.S.C. §105) | Permitted |
| EPA SDWIS | U.S. federal government work — public domain (17 U.S.C. §105) | Permitted |
| EPA TRI | U.S. federal government work — public domain (17 U.S.C. §105) | Permitted |
| CDC EPHT (Heat & Health Index; PM2.5) | U.S. federal government work — public domain (17 U.S.C. §105) | Permitted |
| CDC/ATSDR SVI 2022 | U.S. federal government work — public domain (17 U.S.C. §105) | Permitted |
| EPA AirToxScreen | U.S. federal government work — public domain (17 U.S.C. §105) | Permitted |
| NaNDA (ICPSR public-use datasets: walkability, land cover, broadband, parks, transit)Commercial-use permissive; attribution + citation required (ICPSR ToU). | ICPSR standard Terms of Use | Permitted |
| NaNDA (openICPSR CC BY-NC datasets: civic/social/religious, recreational, grocery, liquor/tobacco/convenience, health care, social services)NON-COMMERCIAL. Served per-row under fair-use read-by-row access (ADR-0034 §B-7); NOT redistributed in bulk. Commercial reuse requires written permission from the NaNDA maintainers / openICPSR. | CC BY-NC 4.0 | Non-commercial |
Attribution + license apply to values reused from this response. See the per-source entries for upstream terms.
Building against the API? The full machine-readable contract lives at /api/v1/openapi.json (OpenAPI 3.1.0) — point your codegen or client tooling there.