pytidycensus.geography

Geographic boundary data retrieval and processing using pygris.

Functions

`get_block_group_boundaries`(state[, county, ...])	Get block group boundaries for a state, optionally filtered by county.
`get_county_boundaries`([state, year, cb])	Get US county boundaries, optionally filtered by state.
`get_geography`(geography[, year, state, ...])	Download and load geographic boundary data using pygris.
`get_state_boundaries`([year, cb])	Get US state boundaries.
`get_tract_boundaries`(state[, county, year, cb])	Get census tract boundaries for a state, optionally filtered by county.

pytidycensus.geography.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)

pytidycensus.geography.get_state_boundaries(year=2022, cb=True, **kwargs)[source]

Get US state boundaries.

Parameters:

year (int, default 2022) – Census year for boundaries
cb (bool, default True) – If True, download generalized cartographic boundary files
**kwargs – Additional parameters

Returns:

State boundaries

Return type:

geopandas.GeoDataFrame

pytidycensus.geography.get_county_boundaries(state=None, year=2022, cb=True, **kwargs)[source]

Get US county boundaries, optionally filtered by state.

Parameters:

state (str, int, or list, optional) – State(s) to filter by
year (int, default 2022) – Census year for boundaries
cb (bool, default True) – If True, download generalized cartographic boundary files
**kwargs – Additional parameters

Returns:

County boundaries

Return type:

geopandas.GeoDataFrame

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

Get census tract boundaries for a state, optionally filtered by county.

Parameters:

state (str or int) – State to get tracts for
county (str, int, or list, optional) – County(ies) to filter by
year (int, default 2022) – Census year for boundaries
cb (bool, default True) – If True, download generalized cartographic boundary files
**kwargs – Additional parameters

Returns:

Tract boundaries

Return type:

geopandas.GeoDataFrame

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

Get block group boundaries for a state, optionally filtered by county.

Parameters:

state (str or int) – State to get block groups for
county (str, int, or list, optional) – County(ies) to filter by
year (int, default 2022) – Census year for boundaries
cb (bool, default True) – If True, download generalized cartographic boundary files
**kwargs – Additional parameters

Returns:

Block group boundaries

Return type:

geopandas.GeoDataFrame