Household Vehicles

Interactive visualization + data pipeline for US Census ACS B08201 (Household Size by Vehicles Available), 2009–2024, all 50 states + DC, at state / county / place / county-subdivision granularity.

TL;DR

• Live (when deployed): vehs.hccs.dev
• Pieces of this site will also be remixed into cars.dont.fit (CDF), a broader blog/portal about US car-ownership patterns and costs.

Pipeline

# One-time setup (creates .venv, installs hhvs, installs www deps)
spd
cd www && pnpm install && cd ..

# Fetch raw Census Data API responses (cached as gzipped JSON under data/raw/)
hhvs fetch                      # everything: 1Y + 5Y, all geo levels, all years
hhvs fetch -r 5Y -l cousub      # subsets are cheap to re-target

# Compose long-format parquet under data/processed/
hhvs build

# Export per-state-split parquet to www/public/data/ (snappy-compressed,
# narrow int dtypes — hyparquet on the front-end loads them column-by-column)
hhvs export

# Run the dev server
cd www && pnpm dev              # http://localhost:7366

CENSUS_API_KEY (free, sign up at api.census.gov/data/key_signup.html) removes the 500-requests/day rate limit. Without one, you can still cover state-level for both releases on a single day's budget.

Data

Table	Description	Source	Coverage
B08201	Household Size × Vehicles Available (30 cells)	ACS 1Y + 5Y	2009-2024 (1Y skips 2020); state / county / place / cousub
B01003	Total Population	ACS 1Y + 5Y	Same as B08201; used for per-capita views

Long-format schema (post-hhvs build):

release    1Y | 5Y          (constant per file post-export)
year       2009..2024
geo_level  state|county|place|cousub  (constant per file post-export)
geoid      hierarchical FIPS (e.g. "34017" = NJ Hudson County)
name       human label from Census API
hh_size    -1=any, 1, 2, 3, 4(+)      (B08201 only)
n_vehicles -1=any, 0, 1, 2, 3, 4(+)   (B08201 only)
estimate   Int32 nullable             (B08201)
population Int32 nullable             (B01003)
moe        Int32 nullable             margin of error

Web app (www/)

Vite + React 19 + TypeScript + SASS. Plotly via the runsascoded fork + pltly wrapper. URL-synced state via use-prms; keyboard navigation + SpeedDial + ShortcutsModal via use-kbd; tooltips via @floating-ui/react. Parquet is loaded in-browser via hyparquet (per-state split for place and cousub so first paint stays fast).

URL params

• r — release: 5y (default) | 1y
• l — geo level: cs (cousub, default) | s | c | p
• y — year (default 2023)
• s — state FIPS filter (default 34 = NJ; -- for all)
• c — county FIPS sub-filter (cousub only)
• v — view: p (stacked %, default) | n (counts)
• T — theme: omitted=dark, l=light, s=system

Hotkeys: r toggle 1Y/5Y, l cycle level, v toggle %/#, Shift+T cycle theme, ? open ShortcutsModal.

Adjacent modules (scaffolded)

• electeds/ — cross-project elected-officials DB (planned to spin out into its own repo + Cloudflare D1 + CFW API).
• auto_debt/ — state-level auto-debt (NY Fed CCP), TBD.
• tco/ — Total Cost of Ownership (AAA + NAIC + EIA), TBD.

Notebook archive

The original EDA notebooks (Hudson County, NJ counties) live under nbs/done/. They're superseded by the pipeline + Vite app above, but kept for provenance. Static plots from the original analyses are still in nj/ and hudson/.