CLI Reference¶
PyPUMS provides a command-line interface for accessing Census data directly from your terminal.
Overview¶
After installing PyPUMS, the pypums command is available:
Commands¶
| Command | Description |
|---|---|
pypums config |
Set your Census API key |
pypums acs |
Fetch ACS data from the Census API |
pypums decennial |
Fetch Decennial Census data |
pypums variables |
Search and browse Census variables |
pypums estimates |
Fetch population estimates |
pypums acs-url |
Build a URL to the Census FTP server (legacy) |
pypums download-acs |
Download PUMS data files (legacy) |
Quick Examples¶
Set your API key¶
Fetch ACS data¶
# State-level total population
pypums acs state -v B01003_001
# County-level median income for California
pypums acs county -v B19013_001 -s CA -y 2022
# Full table in wide format
pypums acs state -t B01001 -o wide
Fetch Decennial Census data¶
# State-level population from 2020 Census
pypums decennial state -v P1_001N
# County-level for California
pypums decennial county -v P1_001N -s CA -y 2020
Search for variables¶
# Search for income-related variables
pypums variables --search "median income"
# Search in a specific dataset and year
pypums variables --dataset acs1 --year 2022 --search "housing"
# Cache results for faster subsequent searches
pypums variables --search "poverty" --cache
Fetch population estimates¶
# State-level population estimates
pypums estimates state
# County-level for Texas
pypums estimates county -s TX --vintage 2023
Full Command Reference¶
cli¶
Usage:
Options:
-v, --version Show the application's version and exit.
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or
customize the installation.
acs¶
Fetch ACS data from the Census API.
Usage:
Options:
GEOGRAPHY Geography level (e.g. 'state', 'county') [required]
-v, --variables TEXT Comma-separated variable IDs
-t, --table TEXT Census table ID
-s, --state TEXT State FIPS or abbreviation
--county TEXT County FIPS code
-y, --year INTEGER Data year [default: 2023]
--survey TEXT Survey: acs1 or acs5 [default: acs5]
-o, --output TEXT Output: tidy or wide [default: tidy]
-k, --key TEXT Census API key
acs-url¶
Builds URL pointing to the Census Bureau’s FTP server containing the data for the desired ACS.
Usage:
Options:
--year INTEGER Year of survey (2000 - 2024) [required]
--state TEXT One of the 50 US States or District of Columbia
[required]
--survey TEXT One of '1-', '3-' or '5-year' [default: 1-year]
--sample-unit TEXT Unit of observation (person or household) [default:
person]
config¶
Set your Census API key.
Usage:
Options:
KEY Census API key to store [required]
--install / --no-install Save key to environment [default: install]
decennial¶
Fetch Decennial Census data from the Census API.
Usage:
Options:
GEOGRAPHY Geography level (e.g. 'state', 'county') [required]
-v, --variables TEXT Comma-separated variable IDs
-t, --table TEXT Census table ID
-s, --state TEXT State FIPS or abbreviation
--county TEXT County FIPS code
-y, --year INTEGER Census year [default: 2020]
-o, --output TEXT Output: tidy or wide [default: tidy]
-k, --key TEXT Census API key
download-acs¶
Downloads and, optionally, extracts data related to the specified ACS into a specified directory.
Usage:
Options:
--year INTEGER Year of survey (2000 - 2024) [required]
--state TEXT One of the 50 US States or District of
Columbia [required]
--survey TEXT One of '1-', '3-' or '5-year' [default:
1-year]
--sample-unit TEXT Unit of observation (person or household)
[default: person]
--data-directory DIRECTORY [default: /home/docs/.pypums/data]
-e, --extract Extract the downloaded zip file? [default:
True]
--overwrite-download / --no-overwrite-download
Overwrite previously downloaded version of
this data [default: no-overwrite-download]
--overwrite-extract / --no-overwrite-extract
Overwrite previously extracted version of
this data [default: no-overwrite-extract]
estimates¶
Fetch population estimates from the Census API.
Usage:
Options:
GEOGRAPHY Geography level (e.g. 'state', 'county') [required]
-p, --product TEXT Estimates product [default: population]
-v, --variables TEXT Comma-separated variable IDs
-s, --state TEXT State FIPS or abbreviation
--county TEXT County FIPS code
--vintage INTEGER Vintage year [default: 2023]
-o, --output TEXT Output: tidy or wide [default: tidy]
-k, --key TEXT Census API key
variables¶
Search/browse Census variables.
Usage:
Options: