pypums 0.3.1

Python interface to the US Census Bureau API for ACS, Decennial Census, PUMS, population estimates, and migration flows.

PyPUMS

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

Quick Start

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()

Features

• 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

Installation

uv add pypums

For spatial/mapping support:

uv add "pypums[spatial]"

Census API Key

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")

Documentation

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

Development

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 .

Citation

@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}}
}