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='wide', 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 (
Union[str,List[str],Dict[str,str],None]) – 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 (
Optional[str]) – ACS table ID to retrieve all variables from.cache_table (
bool) – Whether to cache table names for faster future access.year (
int) – Year of ACS data (2009-2022 for 5-year, 2005-2022 for 1-year).survey (
str) – ACS survey type (“acs1”, “acs3”, or “acs5”).state (
Union[str,int,List[Union[str,int]],None]) – State(s) to retrieve data for. Accepts names, abbreviations, or FIPS codes.county (
Union[str,int,List[Union[str,int]],None]) – County(ies) to retrieve data for. Must be used with state.zcta (
Union[str,List[str],None]) – ZIP Code Tabulation Area(s) to retrieve data for. Geography must be “zcta”.output (
str) – Output format (“tidy” or “wide”).geometry (
bool) – Whether to include geometry for mapping.keep_geo_vars (
bool) – Whether to keep all geographic variables from shapefiles.shift_geo (
bool) – (Deprecated) If True, warn user to use alternative geometry shifting.summary_var (
Optional[str]) – Summary variable from the ACS to include for comparison (e.g. total population).moe_level (
int) – Confidence level for margin of error (90, 95, or 99).api_key (
Optional[str]) – Census API key. If not provided, looks for CENSUS_API_KEY environment variable.show_call (
bool) – Whether to print the API call URL.**kwargs – Additional parameters passed to geography functions.
- Returns:
ACS data, optionally with geometry.
- Return type:
Union[DataFrame,GeoDataFrame]
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 ... )