US Census ACS data query

**關鍵字 / 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).