Python interface to the US Census Bureau API — American Community Survey, Decennial Census, PUMS microdata, population estimates, and migration flows.

Get county-level median household income for California:

import pypums df = pypums.get_acs( geography="county", variables=["B19013_001"], state="CA", year=2023, ) df.head()

Make a map with tract-level data:

df = pypums.get_acs( geography="tract", variables=["B19013_001"], state="CA", county="037", year=2023, geometry=True, # returns a GeoDataFrame ) df.plot(column="estimate", legend=True, figsize=(12, 8))

Work with PUMS microdata:

pums = pypums.get_pums( variables=["AGEP", "SEX", "WAGP"], state="CA", year=2023, recode=True, # adds human-readable labels ) pums.head()

• get_acs() — American Community Survey data (1-year and 5-year)
• get_decennial() — Decennial Census data (2000, 2010, 2020)
• get_pums() — PUMS microdata with replicate weight support
• get_estimates() — Population Estimates Program data
• get_flows() — ACS migration flows (county and MSA level)
• load_variables() — Search and browse Census variable codes
• MOE functions — moe_sum(), moe_ratio(), moe_prop(), moe_product(), significance()
• Spatial support — Attach TIGER/Line geometries, returns GeoDataFrames
• Survey design — SurveyDesign class with successive difference replication
• Caching — File-based caching with configurable TTL
• CLI — Command-line access to all data functions

uv add pypums

For spatial/mapping support:

uv add "pypums[spatial]"

You need a free Census API key. Request one here, then:

export CENSUS_API_KEY="your-key-here"

Or set it in Python:

import pypums pypums.census_api_key("your-key-here")

Full documentation: https://pypums.readthedocs.io

To contribute to this library, first checkout the code. Then install uv and set up the project:

cd pypums uv sync --extra test

To run the tests:

uv run pytest

To run the linter:

uvx ruff check . uvx ruff format --check .

@misc{pypums, author = {Sergio Sanchez Zavala}, title = {PyPUMS: Python interface to the US Census Bureau API}, year = {2019}, publisher = {GitHub}, journal = {GitHub repository}, howpublished = {\url{https://github.com/chekos/pypums}} }