pytidycensus.get_geography

pytidycensus.get_geography(geography, year=2022, state=None, county=None, keep_geo_vars=False, cache_dir=None, cb=True, **kwargs)[source]

Download and load geographic boundary data using pygris.

Parameters:

geography (str) – Geography type (e.g., ‘county’, ‘tract’, ‘block group’, ‘state’, ‘zcta’, ‘place’)
year (int, default 2022) – Census year for boundaries
state (str, int, or list, optional) – State(s) to filter data for. Can be state name, abbreviation, or FIPS code.
county (str, int, or list, optional) – County(ies) to filter data for (requires state). Can be county name or FIPS code.
keep_geo_vars (bool, default False) – Whether to keep all geographic variables
cache_dir (str, optional) – Directory for caching downloaded files (currently not used with pygris)
cb (bool, default True) – If True, download generalized cartographic boundary files (1:500k). If False, download detailed TIGER/Line files. Note: For 2020 state-level data, cartographic boundaries may fail due to Census Bureau access restrictions. The function will automatically fall back to detailed TIGER/Line files (cb=False) if this occurs.
**kwargs – Additional parameters passed to underlying pygris functions

Returns:

Geographic boundary data

Return type:

geopandas.GeoDataFrame

Notes

Automatic Fallback: If downloading cartographic boundary files (cb=True) fails with file system errors (common for 2020 state-level GENZ files), the function will automatically retry with detailed TIGER/Line files (cb=False) and issue a warning. This ensures robust data retrieval without requiring manual intervention.

Examples

>>> # Get county boundaries for Texas
>>> tx_counties = get_geography("county", state="TX", year=2022)
>>>
>>> # Get tract boundaries for Harris County, TX
>>> harris_tracts = get_geography(
...     "tract",
...     state="TX",
...     county="201",
...     year=2022
... )
>>>
>>> # Get 2020 state boundaries (will auto-fallback if needed)
>>> states_2020 = get_geography("state", year=2020)