acs_cli_mi 0.1.0

CLI for querying Census ACS 5-year data for Michigan counties

acs-cli

A command-line tool for querying U.S. Census Bureau American Community Survey (ACS) 5-year estimates for Michigan counties. Returns clean CSV output ready for spreadsheets, data pipelines, or further analysis.

Install

# Run directly without installing
uvx acs_cli --help

# Or install with pip/uv
pip install acs_cli

Requires Python 3.14+.

Setup

Get a free Census API key at https://api.census.gov/data/key_signup.html, then save it:

acs-cli login --api-key YOUR_KEY

The key is stored in ~/.config/acs-cli/config. Alternatively, set CENSUS_API_KEY in your environment or a .env file.

Usage

Query topics

# Population demographics for all Michigan counties
acs-cli query population

# Filter to a specific county
acs-cli query income --county Wayne

# Combine multiple topics
acs-cli query population income education --county Washtenaw

# All topics at once
acs-cli query all

Multi-year queries

Query across multiple ACS vintages to see trends over time. Adds a Year column to the output.

acs-cli query population --years 2019,2020,2021,2022,2023,2024
acs-cli query income --years 2019,2024 --county Wayne

Save to file

acs-cli query population income --output data.csv
acs-cli query all --years 2020,2024 --output trend.csv

Sort results

acs-cli query population --sort "Total Population"

County profile

Get all topics for a single county in a vertical layout:

acs-cli info Washtenaw
acs-cli info "Grand Traverse" --year 2022

List available topics

acs-cli topics

Raw Census variables

Bypass the topic system and request specific ACS variable codes:

acs-cli query -v B01003_001E -v B19013_001E

Available Topics

Topic	Description
population	Total population, male/female, age breakouts (by sex), under 18, nativity/citizenship, households, housing units
income	Median household/family income, per capita income, Gini index, earnings by sex, household income distribution (16 brackets), income sources (Social Security, SSI, public assistance, retirement)
age	Median age overall, male, female
poverty	Poverty universe and count below poverty level
education	Full educational attainment for pop 25+ (no schooling through doctorate, including partial levels)
race	Total, White, Black, AIAN, Asian
health_insurance	Insurance universe, with coverage, without coverage
disability	Disability universe, male with disability, female with disability
insurance_income	Insurance status by household income brackets

Output Format

All output is CSV written to stdout (or a file with --output). Values are raw numbers without formatting so they can be consumed directly by pandas, Excel, database imports, or other tools. Suppressed Census values appear as empty fields.

Data Source

All data comes from the Census Bureau ACS 5-Year Estimates API. Available vintages: 2009-2024. Data covers all 83 Michigan counties (FIPS state code 26).

Project Structure

src/acs_cli/
├── cli.py              # Typer CLI commands
├── topics.py           # Variable definitions and topic registry
└── census_api/
    ├── __init__.py
    └── client.py       # API client, key management, CSV output