# Methodology: US Geographic & Demographics

> Where do the Geographic & Demographics API's numbers come from, and how are they checked?

Demographics are American Community Survey 5-year estimates from the Census Bureau's Data API, for every ZCTA and county in the 50 states, DC and Puerto Rico, loaded once per ACS release with margins of error and the survey period on every value. Geography comes from the Census Gazetteer and the 2020 ZCTA-to-county relationship file, and schools from the NCES Common Core of Data. A release is published only after row-count, format, bounds and benchmark checks pass, the benchmark being values read by hand from a second Census channel.

## Sources

| Dataset | Source | Release | Refresh |
| --- | --- | --- | --- |
| `atlas.zcta_demographics` | American Community Survey 5-year (Census Data API) and the Gazetteer ZCTA file, U.S. Census Bureau | Latest ACS 5-year release loaded (for example 2020-2024), stated on every metric | Annual; stale after 400 days |
| `atlas.county_demographics` | American Community Survey 5-year and the Gazetteer county file, U.S. Census Bureau | Same ACS release as ZCTAs | Annual; stale after 400 days |
| `atlas.zcta_counties` | 2020 ZCTA-to-county relationship file, U.S. Census Bureau | 2020 (decennial) | Decennial |
| `atlas.schools` | Common Core of Data school directory, National Center for Education Statistics | Latest CCD school year loaded (for example 2024-2025), stated as `school_year` | Annual; stale after 400 days |

## How values are produced

- Each metric names its ACS table and variables (`source.table_id`, `source.variables`) and carries the 90% margin of error the Census Bureau publishes (`moe`).
- Where the Census Bureau publishes an annotation instead of an estimate, `value` is null and `null_reason` says why. Top- and bottom-coded medians are returned as the interval edge with a `qualifier` (`or_more`, `less_than`).
- Percentages we derive from two published estimates are marked `derived: true` and have no margin of error.
- ZCTA land areas and internal points come from the Gazetteer; county overlaps and land-area shares come from the 2020 relationship file.
- Schools are assigned to a ZCTA by their USPS location ZIP; distances are straight-line from the ZCTA's Census internal point.

## Validation checks

Every release runs the dataset's required checks before it can become active. A blocking check that fails stops the release, and the previous one keeps serving. Records that did not change keep their original `published_at`, and every record carries a `provenance` block with its `source_url`, the source snapshot it was read from and the validation status of its release.

| Check | What it guards |
| --- | --- |
| `row_count_range`, `state_row_counts` | National row counts within expected bounds (about 33,000 to 34,500 ZCTAs and 3,140 to 3,300 counties per ACS release), and rows for every expected state |
| `unique_record_id`, `required_fields_present` | One row per geography and school; no missing required fields |
| `percent_bounds`, `coordinates_in_us_bounds` | Percentages between 0 and 100; internal points and school locations inside the US, DC and Puerto Rico |
| `sentinels_resolved` | Census annotation codes (negative sentinel values) never survive into a numeric value |
| `zcta_land_shares` | Each ZCTA's county land shares are between 0 and 1, sum to 1, and name exactly one primary county |
| `benchmark_values` | Hand-checked values, read from the Census table-based summary file rather than the Data API, must match |
| `null_rate`, `state_county_consistency` | Non-blocking: flag drift in the share of null values, and schools whose county is outside their state |

## Known limits

- **ZCTAs are not ZIP codes.** Not every USPS ZIP code has a ZCTA (some PO-box, single-building and other non-residential ZIP codes have none), and a ZIP code and the ZCTA with the same code rarely cover exactly the same addresses. Codes are matched exactly; a code with no ZCTA returns `404 ZCTA_NOT_FOUND`. See [ZCTA vs ZIP code](https://olympus.new-odyssey.com/guides/zcta-vs-zip-code).
- **Estimates, not counts.** ACS values describe a five-year period, not today. Dollar values are inflation-adjusted to the final year of the period.
- **County overlaps use 2020 counties.** Connecticut's planning regions (ACS 2022 onwards) have no ZCTA overlaps in the 2020 relationship file.
- Not included: crime data or scores, school ratings or rankings, flood or other risk scores, parcel-level decisions, private schools, predictive scores.

> This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.

## Sources

- U.S. Census Bureau: [ZIP Code Tabulation Areas (ZCTAs)](https://www.census.gov/programs-surveys/geography/guidance/geo-areas/zctas.html)
- U.S. Census Bureau: [Gazetteer Files](https://www.census.gov/geographies/reference-files/time-series/geo/gazetteer-files.html)
- U.S. Census Bureau: [Relationship Files](https://www.census.gov/geographies/reference-files/time-series/geo/relationship-files.2020.html)

## Related

- [Coverage and sources: Geographic & Demographics](https://olympus.new-odyssey.com/coverage#geo-demographics)
- [Geographic & Demographics API reference](https://olympus.new-odyssey.com/docs/geo-demographics)
- [ZCTA vs ZIP code](https://olympus.new-odyssey.com/guides/zcta-vs-zip-code)
- [Data release notes](https://olympus.new-odyssey.com/releases)

---
Published 2026-10-21, updated 2026-10-21 by New Odyssey. Canonical: https://olympus.new-odyssey.com/methodology/geo-demographics