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='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
... )