pytidycensus.get_acs

pytidycensus.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:

pandas.DataFrame or geopandas.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
... )