pytidycensus.acs
American Community Survey (ACS) data retrieval functions.
Functions
|
Obtain data from the American Community Survey (ACS). |
|
Get available ACS variables for a given year and survey. |
- pytidycensus.acs.get_acs(geography, variables=None, table=None, cache_table=False, year=2022, survey='acs5', state=None, county=None, zcta=None, output='tidy', geometry=False, keep_geo_vars=False, shift_geo=False, summary_var=None, moe_level=90, api_key=None, show_call=False, **kwargs)[source]
Obtain data from the American Community Survey (ACS).
- Parameters:
geography (str) – The geography of your data (e.g., ‘county’, ‘tract’, ‘block group’).
variables (str, list of str, or dict, optional) – Variable ID(s) to retrieve. Can be a single variable, list of variables, or dictionary mapping custom names to variable IDs. If not provided, must specify table.
table (str, optional) – ACS table ID to retrieve all variables from.
cache_table (bool, default False) – Whether to cache table names for faster future access.
year (int, default 2022) – Year of ACS data (2009-2022 for 5-year, 2005-2022 for 1-year).
survey (str, default "acs5") – ACS survey type (“acs1”, “acs3”, or “acs5”).
state (str, int, or list, optional) – State(s) to retrieve data for. Accepts names, abbreviations, or FIPS codes.
county (str, int, or list, optional) – County(ies) to retrieve data for. Must be used with state.
zcta (str or list of str, optional) – ZIP Code Tabulation Area(s) to retrieve data for. Geography must be “zcta”.
output (str, default "tidy") – Output format (“tidy” or “wide”).
geometry (bool, default False) – Whether to include geometry for mapping.
keep_geo_vars (bool, default False) – Whether to keep all geographic variables from shapefiles.
shift_geo (bool, default False) – (Deprecated) If True, warn user to use alternative geometry shifting.
summary_var (str, optional) – Summary variable from the ACS to include for comparison (e.g. total population).
moe_level (int, default 90) – Confidence level for margin of error (90, 95, or 99).
api_key (str, optional) – Census API key. If not provided, looks for CENSUS_API_KEY environment variable.
show_call (bool, default False) – Whether to print the API call URL.
**kwargs – Additional parameters passed to geography functions.
- Returns:
ACS data, optionally with geometry.
- Return type:
Examples
>>> import pytidycensus as tc >>> tc.set_census_api_key("your_key_here") >>> >>> # Get median household income by county in Texas >>> tx_income = tc.get_acs( ... geography="county", ... variables="B19013_001", ... state="TX", ... year=2022 ... ) >>> >>> # Get data with geometry for mapping >>> tx_income_geo = tc.get_acs( ... geography="county", ... variables="B19013_001", ... state="TX", ... geometry=True ... ) >>> >>> # Get data with named variables >>> tx_demo = tc.get_acs( ... geography="county", ... variables={"total_pop": "B01003_001", "median_income": "B19013_001"}, ... state="TX", ... year=2022 ... )