關鍵字 / Keywords: 美國 ACS 家戶調查 人口統計 5年 1年 中位數 家戶所得 教育程度 收入 人口 census ACS acs5 acs1 population household income education race age variables state county tract block group
Scope: US Census Bureau · American Community Survey (ACS).
Query the ACS with a list of variable codes + a geography-scope
string. Response matrix is converted to rows: [{col: val}, ...]
so the LLM can reason on named fields; raw matrix kept under
raw_matrix.
Endpoint: https://api.census.gov/data/{year}/acs/{survey}?get={vars}&for={for_geo}&in={in_geo}
Args:
year: vintage year (e.g. 2022 for ACS 5-year 2018-2022).
variables: list of variable codes. "NAME" returns the geo
display name. Examples:
- ["NAME", "B01001_001E"] — name + total population
- ["NAME", "B19013_001E"] — name + median household income
- ["B15003_022E", "B15003_023E"] — bachelor + master's counts
Look up variable meanings via us_get_variable_metadata.
for_geo: geography scope, Census syntax:
- "us:1" — national
- "state:" — all states (may need key)
- "state:06" — California only (FIPS 06)
- "county:" + in_geo — counties within a parent
- "tract:" + in_geo — tracts within state+county
- "block group:" — smallest ACS unit
- "zip code tabulation area:*" — ZCTAs
in_geo: parent-geo string, required for hierarchical queries.
Examples: "state:06" (in CA), "state:06 county:001".
survey: "acs5" (5-year, all geos, rolling average · default),
"acs1" (1-year, geos with pop ≥65k, more current),
"acs3" (deprecated 3-year, kept for pre-2013),
"acsse" (Supplemental Estimates).
Returns dict with columns, rows (list of dicts), total_rows,
and raw_matrix. If the anonymous data-query threshold is exceeded
Census returns HTML "Missing Key" (HTTP 200); we surface
error="census_gate_html" with a hint pointing to
api.census.gov/data/key_signup.html. Set US_CENSUS_API_KEY env
var to bypass. License: US Public Domain (17 USC §105).