# Census ZIP / ZCTA and ACS data packages

Source: U.S. Census Bureau. Downloadable, bundled data; no API key or live Census request is required to use these files. Rebuild with `node scripts/census-data/build.mjs`; use `--refresh` to fetch upstream again. The committed manifest records actual build time, exact source URLs, SHA-256 checksums, byte sizes, output counts and join diagnostics.

## Files and coverage

- `zcta-2024-points.geojson` / `zcta-2024-reference.csv`: all 33,791 ZCTAs in the 2024 national Census Gazetteer (including 50 states, DC, Puerto Rico and Island Area entries present in the source). These are **representative internal points**, not geometric centroids or USPS delivery addresses. Includes land/water area in m² and stable five-character GEOID / zcta codes.
- `acs-2024-counties.geojson` / `.csv`: 2020–2024 ACS 5-year population, median household income, median age and housing-unit estimates, each with its margin of error. Covers all published counties/county equivalents in the 50 states, DC and Puerto Rico. Boundaries use matching 2024 Census cartographic counties, joined strictly by five-character GEOID. County GeoJSON excludes other territories lacking these ACS observations. Connecticut uses current planning regions.
- `acs-2024-zcta.csv`: all ZCTAs published in the 2020–2024 ACS 5-year Summary File, same four variables and MOEs.
- `acs-2024-zcta-points.geojson`: ACS rows with a matching 2024 Gazetteer representative point. See `join-report.json` for any unmatched geography. The point file stores period/year once at collection level; the CSV repeats them per row. Points do not describe the whole polygon or precise radius population.
- `zcta-puerto-rico-2020-acs-2024.geojson`: **Puerto Rico only**, ZCTAs 006xx,007xx,009xx, 2020 Census cartographic polygons joined to 2020–2024 ACS. This is a useful real boundary package, not a national ZCTA polygon file. The full national authoritative shapefile remains available from the exact official URL in the manifest.
- `fields.json`, `manifest.json`, `join-report.json`: field definitions, provenance, and exact join coverage.

## ZIP codes are not ZCTAs

USPS ZIP codes identify mail delivery routes/addresses. Census ZCTAs approximate ZIP-code areas for statistical mapping; not every ZIP code has a ZCTA. These official Census packages do **not** claim to be a complete, current USPS ZIP directory. A ZCTA can cross state/county boundaries. Do not infer an authoritative state from its prefix or internal point.

## Interpretation

ACS data describe the combined **2020–2024** survey period, not a 2024 census count or a 2026 real-time population. MOEs are published 90% confidence margins; keep them with estimates. Income is median household income in **2024 inflation-adjusted US dollars**. Age is years; population/housing are counts.

All selected numeric fields are nonnegative quantities. Census negative numeric "jam" values and blanks become JSON `null` / empty CSV cells; the original code and source variable are retained in `acs_special_values`. In particular, a controlled estimate whose MOE is unavailable is **not** assigned a fabricated zero MOE. Do not treat missing values as zero. Do not average medians to claim the median of a combined area.

GeoJSON coordinates are longitude, latitude for web mapping. Census cartographic source files use geographic NAD83; their positions are used as a WGS84 web mapping approximation, appropriate to these generalized outlines, not survey positioning. Polygon previews are further generalized with per-feature RDP (county 0.003°, Puerto Rico ZCTA 0.001°), coordinates rounded to 5 decimals; every polygon part and hole is retained, but shared-edge topology is not guaranteed. Use original official shapefiles for precise area/perimeter, legal boundaries, or spatial-overlay research.

CSV IDs must be imported as **text** in spreadsheets to preserve leading zeros. GeoJSON stores IDs as strings. Radius queries test representative points; counting points inside a circle does not measure area overlap or population within the circle.

## Rights and attribution

U.S. Census Bureau public data are generally not copyrighted. Cite: "U.S. Census Bureau, 2024 Gazetteer; 2020 and 2024 Cartographic Boundary Files; 2020–2024 American Community Survey 5-year Detailed Tables (B01003, B19013, B01002, B25001). Prepared by GeoDataViewer."

Official policy: https://www2.census.gov/foia/ds_policies/ds027.pdf
ZCTA definition: https://www.census.gov/programs-surveys/geography/guidance/geo-areas/zctas.html
ACS Summary File: https://www.census.gov/programs-surveys/acs/data/summary-file/2024.html
Special values: https://www.census.gov/programs-surveys/acs/technical-documentation/code-lists.html