1. Fetch
php tools/sync.php requests two official Detailed Tables datasets, vintage 2024:
- ACS 5-Year: https://api.census.gov/data/2024/acs/acs5
- ACS 1-Year: https://api.census.gov/data/2024/acs/acs1
Both requests ask for NAME, B01003_001E, B19013_001E, B19113_001E, and B19301_001E for state:* and county:*. Those IDs were confirmed on the official /variables/{ID}.json pages for both datasets. Data queries require a Census API key; metadata does not.
ACS 1-Year is published for areas with populations of 65,000+ (ACS 1-Year Data). Many counties are absent from the 1-Year response. Those rows keep acs1_* null. We do not invent a substitute.
2. Cache
ACS 5-Year rows are upserted into MySQL table places (one row per geography). population and median_hh_income stay 5-Year, joined by median_family_income and per_capita_income. ACS 1-Year values land in nullable acs1_* columns on the same row. Raw responses go to api_cache with distinct keys (acs5-… vs acs1-…). Pages never call Census. If the key is missing or a request fails, the cache is left as-is and the site says so. Census missing values (blank, ., or large negative sentinels) are stored as null and displayed as “Not available.”
3. Publish
php tools/publish.php reads places only. It does not call the Census API. If there are no rows, it publishes nothing — no placeholder statistics.
When rows exist it upserts:
- A vintage note that ACS 5-Year 2024 covers 2020–2024 and that ACS 1-Year 2024 is limited to areas 65,000+.
- Rank briefs (top and bottom 10 states) when at least 10 state rows exist, including family income and per capita income when those columns are present.
- A 1-Year vs 5-Year state comparison when at least two states have non-null ACS 1-Year values. The two products are stated side by side; the brief does not treat the difference as year-over-year change.
- One state spotlight per cached state (new figures appear only when present).
- A highest/lowest-income county brief for a state when that state has county rows with income.
Every figure is formatted from the related places column. Sentences do not claim year-over-year change unless two vintages are stored as such. Republish updates the same (kind, place, vintage) row instead of duplicating it.
4. What we will not do
- Invent a population or income for an empty cache.
- Fill ACS 1-Year columns for geographies the Census Bureau did not publish.
- Say “new population every day.” ACS vintages are annual.
- Use Data.gov as a source.
- Let an LLM guess a statistic for a brief body.
5. Other official series
When the shared MySQL cache already has indicators and stories rows written by a CLI publisher that called official APIs, home and tracker pages read those rows. They do not scrape agency HTML and they do not invent a missing observation.
- BLS Public Data API — unemployment, CPI, payrolls, earnings and related monthly series
- SEC EDGAR companyfacts — quarterly revenue and net income for named filers
- World Bank Open Data API — GDP and population series
- Eurostat Statistics API — EU unemployment, inflation and GDP
Attribution
This product uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.
This product uses the U.S. Bureau of Labor Statistics Public Data API but is not endorsed or certified by the Bureau of Labor Statistics.
Company facts are read from the U.S. Securities and Exchange Commission EDGAR companyfacts API. This product is not affiliated with or endorsed by the SEC.
This product uses the World Bank Open Data API but is not endorsed or certified by the World Bank.
This product uses the Eurostat Statistics API but is not endorsed or certified by Eurostat or the European Commission.