API documentation

Datasets

exception censaurus.dataset.DatasetError[source]

class censaurus.dataset.DatasetExplorer(_dataset_json: Dict = None)[source]

An object that explores the available Census API Datasets.

Parameters:: _dataset_json (dict = None) – This parameter should only be used internally. Used for creating subsets of an already existing DatasetExplorer.

filter_by_year(start_year: int = None, end_year: int = None) → DatasetExplorer[source]

Returns a new DatasetExplorer consisting of all datasets that match the year range.

Parameters:

start_year (int = None) – The earliest year for which to include datasets. If start_year is None, then no such restriction is applied.
end_year (int = None) – The latest year for which to include datasets. If end_year is None, then no such restriction is applied.

filter_by_term(term: str | List[str], by: str = 'title') → DatasetExplorer[source]

Returns a new DatasetExplorer consisting of all datasets that match the search. Can filter by each dataset’s title or description.

Parameters:

term (str or list of str) – The search string or strings.
by (str = ‘title’) – If by is ‘title’, then datasets will be filtered by their titles. Otherwise, by should be ‘description’, and datasets will be filtered by their descriptions.

to_df() → DataFrame[source]: Converts the DatasetExplorer into a pandas.DataFrame object detailing all of each datasets’s attributes.

describe(url_extension: str | List[str] = None, other_attributes: List[str] = []) → None[source]

Prints out a string that describes each dataset in the explorer.

Parameters:

url_extension (str or list of str = None) – A specific URL extension or a list of specific URL extensions to describe. If url_extension is None, then all datasets in the explorer will be described.
other_attributes (list of str = []) – A list of addition attributes to describe from each dataset, if that attribute is available. For a list of attributes, see the source file.

visualize(hierarchical: bool = False, filename: str = 'dataset_explorer_graph.html', show: bool = True, keep_file: bool = False, **kwargs) → None[source]

Visualizes the DatasetExplorer as a tree in your default webbrowser.

Parameters:

hierarchical (bool = False) – Determines whether the variables (nodes) are presented in a hierarchical layout (with root nodes at the top), as opposed to a layout that looks more like spokes on a wheel.
filename (str = ‘variable_graph.html’) – The path (from within the current working directory) the save the generated file at.
show (bool = True) – Determines whether or not to open the generated file in your default webbrowser.
keep_file (bool = False) – Determines whether or not to delete the generated file after opening it.

class censaurus.dataset.Dataset(url_extension: str, map_service: str, census_api_key: str = None)[source]

A base class to represent a Census dataset (product). This class should not be used if the dataset you desire already has its own Dataset subclass. The following datasets do have Dataset subclasses, and so you should use those instead.

Decennial Census (general): Decennial
- Decennial Census Redistricting Data: DecennialPL
- Decennial Census Summary File 1: DecennialSF1
- Decennial Census Summary File 2: DecennialSF2
American Community Survey Census (general): ACS
- American Community Survey 1-Year Data: ACS1
- American Community Survey 1-Year Supplemental Data: ACSSupplemental
- American Community Survey 3-Year Data: ACS3
- American Community Survey 5-Year Data: ACS5
- American Community Survey Migration Flows: ACSFlows
- American Community Survey Language Statistics: ACSLanguage
Public Use Microdata Sample (general): PUMS
Current Population Survey (general): CPS
Economic Census (general): Economic
- Economic Census Key Statistics: EconomicKeyStatistics
Population Estimates (general): Estimates
Population Projections (general): Projections

Parameters:

url_extension (str) – A unique url path that accesses the content for this dataset. Appended to https://api.census.gov. Typically of the form <year>/<product>/<extension>, though there are occasionally additional elements. For example, 2021/acs/acs1 is the extension for the American Community Survey 1-Year Estimates published in 2021.
map_service (str = ‘tigerWMS_Current’) – The name of the TIGERWeb mapservice to use as the geographic basis for this dataset. Defaults to the current mapservice.
census_api_key (str = None) – A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

property geographies: GeographyCollection[source]: An object representing the collection of supported geographies for this dataset. Found by visiting https://api.census.gov/<url_extension>/geography.json.

property variables: VariableCollection[source]: An object representing the collection of available variables for this dataset. Found by visiting https://api.census.gov/<url_extension>/variables.json.

property groups: GroupCollection[source]: An object representing the collection of groups of available variables for this dataset.

Get Census data for the entire United States.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for regions of the United States. See here for an overview of Census regions.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for divisions of the United States. See here for an overview of Census divisions.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for states.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for counties.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for county subdivisions.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for Census tracts.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for Census block groups.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for Census blocks.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for Census places (both Incorporated Places and Census Designated Places).

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for Metropolitan and Micropolitan Statistical Areas.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for Combined Statistical Areas.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for Congressional Districts.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for voting districts.

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for Zib Code Tabulation Areas (note that these are not the exact same as zip codes).

Parameters:

within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

Get Census data for any other geographic level supported by the Census.

Parameters:

geography (str) – The geographic level to get data from. To see the available geographies, see Dataset.geographies.
geography_layer (str = None) – The TIGERWeb MapService geographic layer to use for area geometries. Only necessary if 1) you want to return geometries or 2) you are not using a default geographic Census hierarchy.
within (Area or list of Area = None) – A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. If within is None, then all areas with the entire (cartographic) boundary of the United States will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
variables (list of str or list of Variable or list of mixed str and Variable or VariableCollection or dict of str: str = []) – The Census variables to get. If variables is a dictionary, then variables will also be renamed. For example, setting variables={"B01001_001E": "total_pop"} would rename the B01001_001E variable to total_pop in the resulting pandas.DataFrame. Note that NAME and GEO_ID will be added to this list if you do not include them.
groups (list of str or list of Group = []) – The Census groups to get. All variables within each group in groups will be requested.
return_geometry (bool = False) – Determines whether or not the geometry of each geographic area should be returned.
area_threshold (float = 0.01) – Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).
extra_census_params (dict of str: str = {}) – Extra query parameters to pass to the Census when requesting data.

class censaurus.dataset.ACS(year: int = 2021, product: str = 'acs5', extension: str = None, census_api_key: str = None)[source]

Data from the American Community Survey. Generally, there is no need to instantiate an object of this class: you should use one of the subclasses instead. The available subclasses are:

American Community Survey 1-Year Data: ACS1

American Community Survey 1-Year Supplemental Data: ACSSupplemental

American Community Survey 3-Year Data: ACS3

American Community Survey 5-Year Data: ACS5

American Community Survey Migration Flows: ACSFlows

American Community Survey Language Statistics: ACSLanguage

Parameters:

year (int = 2021) – The year to get data from. Selected ACS data is available from 2005 to 2021.
product (str = ‘acs5’) –
The specific American Community Survey product to get data from. Available products are:
- American Community Survey 1-Year Data: acs1
- American Community Survey 1-Year Supplemental Data: acsse
- American Community Survey 3-Year Data: acs3
- American Community Survey 5-Year Data: acs5
- American Community Survey Migration Flows: flows
- American Community Survey Language Statistics: language
extension (str = None) –
The specific American Community Survey product extension to get data from. Example extension include:
- Subject Tables: subject
- Data Profiles: profile
- Comparison Profile: cprofile
- Selected Population Profiles: spp
However, the available extensions depend on the product used. The extensions above are for the American Community Survey 1-Year Estimates.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.ACS1(year: int = 2021, extension: str = None, census_api_key: str = None)[source]

Data from the American Community Survey 1-Year Estimates.

Parameters:

year (int = 2021) – The year to get data from. Selected ACS1 data is available from 2005 to 2021.
extension (str = None) –
The specific ACS1 product extension to get data from. Defaults to None, which maps to Detailed Tables. Other available extensions are:
- Subject Tables: subject
- Data Profiles: profile
- Comparison Profile: cprofile
- Selected Population Profiles: spp
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.ACS3(year: int = 2013, extension: str = None, census_api_key: str = None)[source]

Data from the American Community Survey 3-Year Estimates.

Parameters:

year (int = 2013) – The year to get data from. Selected ACS3 data is available from 2007 to 2013.
extension (str = None) –
The specific ACS1 product extension to get data from. Defaults to None, which maps to Detailed Tables. Other available extensions are:
- Subject Tables: subject
- Data Profiles: profile
- Comparison Profile: cprofile
- Selected Population Profiles: spp
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.ACS5(year: int = 2021, extension: str = None, census_api_key: str = None)[source]

Data from the American Community Survey 5-Year Estimates.

Parameters:

year (int = 2021) – The year to get data from. Selected ACS5 data is available from 2009 to 2021.
extension (str = None) –
The specific ACS5 product extension to get data from. Defaults to None, which maps to Detailed Tables. Other available extensions are:
- Subject Tables: subject
- Data Profiles: profile
- Comparison Profile: cprofile
- Selected Population Data Profiles: sptprofile
- American Indian and Alaska Native Detailed Tables: aian
- American Indian and Alaska Native Data Profiles: aianprofile
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.ACSSupplemental(year: int = 2021, census_api_key: str = None)[source]

Data from the American Community Survey 1-Year Supplemental Data.

Parameters:

year (int = 2021) – The year to get data from. Selected ACS Supplement data is available from 2014 to 2021.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.ACSFlows(year: int = 2020, census_api_key: str = None)[source]

Data from the American Community Survey Migration Flows.

Parameters:

year (int = 2020) – The year to get data from. ACS Flows data is available from 2010 to 2020.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.ACSLanguage(census_api_key: str = None)[source]

Data from the American Community Survey Language Statistics (2013).

Parameters:

census_api_key (str = None) –

A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.PUMS(year: int = 2021, duration: str | int = 5, puerto_rico: bool = False, census_api_key: str = None)[source]

Data from the Public Use Microdata Sample.

Parameters:

year (int = 2021) – The year to get data from. Selected PUMS data is available from 2005 to 2021.
duration (int = 5) – THe duration of the sample. Indicates whether to get 5 or 1 year estimates.
puerto_rico (bool = False) – Determines whether or not to get data from the PUMS Puerto Rico survey.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.CPS(year: int = 2023, month: int = 'jan', product: str = 'basic', census_api_key: str = None)[source]

Data from the Current Population Survey.

Parameters:

year (int = 2023) – The year to get data from. Selected CPS data is available from 1989 to 2023.
month (str = ‘jan’) –
The month to get data from. Should be one of the following formats:
- Full month name (January, February, etc.). Capitalization does not matter.
- 3-letter abbreviated month name (Jan, Feb, etc.). Capitalization does not matter.
- An integer between 1-12.
Not all months are available every year and for every product.
product (str = ‘basic’) –
The specific Current Population Survey product to get data from. Example products include:
- Arts Benchmarking Supplement: arts
- Basic Monthly: basic
- Civic Engagement Supplement: civic
- Computer and Internet Use Supplement: internet
- Contingent Worker Supplement: contworker
- Disability Supplement: disability
However, the available products depend on the year and month requested.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.Decennial(year: int = 2020, product: str = 'pl', census_api_key: str = None)[source]

Data from the Decennial Census. This class should not be used if the dataset you desire already had its own Dataset subclass that inherits from Decennial. The available subclasses are:

Decennial Redistricting Data: DecennialPL

Decennial Summary File 1: DecennialSF1

Decennial Summary File 2: DecennialSF2

Parameters:

year (int = 2020) – The year to get data from. Selected Decennial Census data is available in 2000, 2010, and 2020.
product (str = ‘pl’) –
The specific Decennial Census product to get data from. Example products include:
- Demographic and Housing Characteristics File: dhc
- Demographic Profile: dp
- Redistricting Data: pl
- Decennial Post-Enumeration Survey: pes
- Island Areas Demographic and Housing Characteristics File: dhcas
- Island Areas Demographic Profile: dpas
However, the available products depend on the year requested. The products above are for 2020 Decennial Census. More products are available for the 2010 and 2000 Decennial Censuses.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.DecennialPL(year: int = 2020, census_api_key: str = None)[source]

Data from the Decennial Census Redistricting Data.

Parameters:

year (int = 2020) – The year to get data from. Redistricting data is available in 2000, 2010, or 2020.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.DecennialSF1(year: int = 2010, census_api_key: str = None)[source]

Data from the Decennial Census Summary File 1.

Parameters:

year (int = 2010) – The year to get data from. SF1 data is available in 2000 or 2010.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.DecennialSF2(year: int = 2010, census_api_key: str = None)[source]

Data from the Decennial Census Summary File 2.

Parameters:

year (int = 2010) – The year to get data from. SF2 data is available in 2000 or 2010.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.Economic(year: int = 2017, product: str = 'ecnbasic', census_api_key: str = None)[source]

Data from the Economic Census. This class should only be used if you desire something other than the Census’s Economy-Wide Key Statistics. If you do in fact want key statistics, you should use the EconomicKeyStatistics subclass instead.

Parameters:

year (int = 2017) – The year to get data from. Selected Economic Census data is available in 2002, 2007, 2012, and 2017.
product (str = ‘pl’) –
The specific Economic Census product to get data from. Example products include:
- Economy-Wide Key Statistics: ecnbasic in 2017, ewks otherwise
- Economic Census of Island Areas: ecn/islandareas/napcs
- Brokering and Dealing Products Income for the U.S.: ecnbranddeal
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.EconomicKeyStatistics(year: int = 2017, census_api_key: str = None)[source]

Data from the Economic Census Economy-Wide Key Statistics.

Parameters:

year (int = 2017) – The year to get data from. EWKS data is available in 2002, 2007, 2012, or 2017.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.Estimates(year: int = 2021, monthly: bool = False, census_api_key: bool = None)[source]

Data from the Census Population Estimates.

Parameters:

year (int = 2021) – The year to get data from. Selected Population Estimates data is available from 2013 to 2021.
monthly (bool = False) – Determines whether or not to get yearly or monthly population estimates.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

class censaurus.dataset.Projections(year: int = 2017, extension: str = 'pop', census_api_key: str = None)[source]

Data from the Census Population Projections.

Parameters:

year (int = 2017) – The year to get data from. Selected Population Projections data is available in 2012, 2014, and 2017.
extension (str = ‘pop’) –
The specific Census Population Projections extension to get data from. Example extensions include:
- Projected Population by Demographic Characteristics: pop
- Projected Population by Demographic Characteristics: agegroups
- Projected Population by Demographic Characteristics (Single Year of Age) and Nativity: nat
- Projected Births by Demographic Characteristics: births
- Projected Deaths by Demographic Characteristics: deaths
- Projected Net International Migration by Demographic Characteristics: nim
However, the available extensions depend on the year requested. The extensions above are for 2017 Population Projections.
census_api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making more than 500 requests per day.

Variables

exception censaurus.variable.UnknownGroup[source]

class censaurus.variable.Group(name: str, concept: str, variables: List[str])[source]

An object that represents a single Census group (made up of Census variables).

Parameters:

name (str) – The name of the group.
concept (str) – The concept (description) of the group.
variables (list of str) – The list of variables name associated with the group.

class censaurus.variable.GroupCollection[source]

An object that represents a collection of Group objects.

get(group: str | Group) → Group[source]

Returns the requested Group object if it exists. Otherwise, raises an UnknownGroup exception.

Parameters:: group (str) – The requested group.

filter_by_term(term: str | List[str]) → GroupCollection[source]

Filters the Group objects based on a term or a list of terms. If term is a list, only groups whose concepts contain all terms will be included.

Parameters:: term (str or list str) – The requested search term or terms.

to_df() → DataFrame[source]: Converts the GroupCollection into a pandas.DataFrame object detailing each group’s name, concept, and associated variables.

to_list() → List[Group][source]: Converts the GroupCollection into a list of Group objects.

class censaurus.variable.RegroupedVariable(path: Tuple[str], variables: List[Variable])[source]

An object that represents a group of Variable objects after a regrouping has occurred. Not to be confused with an actual Census group. To learn more about custom regrouping, see Regrouper.

Parameters:

path (tuple of str) – The shared part of each path among all Variable objects in this group.
variables (list of Variable) – The variables associated with this group.

group[source]

The shared Census group among all Variable objects in this group.

Type:: str

concept[source]

The shared concept among all Variable objects in this group.

Type:: str

exception censaurus.variable.VariableError[source]

class censaurus.variable.Variable(name: str, info: Dict[str, str])[source]

An object representing a single Census variable.

Parameters:

name (str) – The name of the variable.
info (dict of str: str) – A dictionary detailing the attributes of the variable.

label[source]

The label (description) of the variable.

Type:: str or None

group[source]

The Census group the variable belongs to.

Type:: str or None

concept[source]

The concept of the Census group the variable belongs to.

Type:: str or None

type[source]

The type (int, float, etc.) of the variable.

Type:: str or None

items[source]

Possible values of this variable. This attribute is only set for variables in certain datasets.

Type:: list of str or None

path[source]

The label of the variable split up into clean, individual pieces, with the variable’s concept prepended. For example, the variable B01001_001E in the 2021 American Community Survey 1-Year Estimates has the label Estimate:!!Total. This variable has a path ("sex by age", "estimate", "total").

Type:: tuple of str or None

parent_path[source]

The path of this variable’s parent variable.

Type:: tuple of str or None

readable_path[source]

The elements of the path of this variable joined by “ -> “. For example, the variable B01001_001E in the 2021 American Community Survey 1-Year Estimates has a readable_path of sex by age -> estimate -> total.

Type:: str

class censaurus.variable.AttributeVariable(name: str, owner: Variable)[source]

class censaurus.variable.VariableCollection(variables_json: Dict[str, Dict[str, str]])[source]

An object that represents a collection of Variable objects.

Parameters:: variables_json (dict of str: (dict of str: str)) – A dictionary detailing the attributes of each variable.

property names: List[str][source]: A list of the names of each variable in the collection.

property groups: GroupCollection[source]: The collection of groups associated with the variables in this collection.

get(variable: str | Variable) → Variable[source]

Returns the requested Variable object if it exists. Otherwise, returns None.

Parameters:: variable (str or Variable) – The requested variable.

parent_of(variable: str | Variable) → Variable[source]

Returns the parent of the requested variable.

For example, the variable B01001_002 (path = (sex by age, estimate, total, male)) has the parent B01001_001 (path = (sex by age, estimate, total)).

Parameters:: variable (str or Variable) – The requested variable.

siblings_of(variable: str | Variable, include_root: bool = False) → VariableCollection[source]

Returns the siblings of the requested variable as a new VariableCollection.

For example, the variable B01001_003 (path = (sex by age, estimate, total, male, under 5 years)) has 22 siblings, including:

B01001_004 (path = (sex by age, estimate, total, male, 6 to 9 years)).

B01001_005 (path = (sex by age, estimate, total, male, 10 to 14 years)).

…

B01001_024 (path = (sex by age, estimate, total, male, 80 to 84 years)).

B01001_025 (path = (sex by age, estimate, total, male, 85 years and over)).

Parameters:

variable (str or Variable) – The requested variable.
include_root (bool = False) – Determines whether or not the requested variable will be included in the returned VariableCollection.

siblings_and_cousins_of(variable: str | Variable, include_root: bool = False) → VariableCollection[source]

Returns the siblings and cousins of the requested variable as a new VariableCollection.

For example, the variable B01001_003 (path = (sex by age, estimate, total, male, under 5 years)) has 45 siblings and cousins, including:

B01001_004 (path = (sex by age, estimate, total, male, 6 to 9 years)).

B01001_005 (path = (sex by age, estimate, total, male, 10 to 14 years)).

…

B01001_024 (path = (sex by age, estimate, total, male, 80 to 84 years)).

B01001_025 (path = (sex by age, estimate, total, male, 85 years and over)).

B01001_027 (path = (sex by age, estimate, total, female, under 5 years)).

B01001_028 (path = (sex by age, estimate, total, female, 6 to 9 years)).

…

B01001_048 (path = (sex by age, estimate, total, female, 80 to 84 years)).

B01001_049 (path = (sex by age, estimate, total, female, 85 years and over)).

Parameters:

variable (str or Variable) – The requested variable.
include_root (bool = False) – Determines whether or not the requested variable will be included in the returned VariableCollection.

children_of(variable: str | Variable, include_root: bool = False) → VariableCollection[source]

Returns the children of the requested variable as a new VariableCollection.

For example, the variable B01001_002 (path = (sex by age, estimate, total, male)) has 23 children, including:

B01001_004 (path = (sex by age, estimate, total, male, under 5 years)).

B01001_004 (path = (sex by age, estimate, total, male, 6 to 9 years)).

…

B01001_024 (path = (sex by age, estimate, total, male, 80 to 84 years)).

B01001_025 (path = (sex by age, estimate, total, male, 85 years and over)).

Parameters:

variable (str or Variable) – The requested variable.
include_root (bool = False) – Determines whether or not the requested variable will be included in the returned VariableCollection.

descendants_of(variable: str | Variable, include_root: bool = False) → VariableCollection[source]

Returns the descendants of the requested variable as a new VariableCollection.

For example, the variable B01001_001 (path = (sex by age, estimate, total)) has 48 descendants, including:

B01001_002 (path = (sex by age, estimate, total, male)).

B01001_003 (path = (sex by age, estimate, total, male, under 5 years)).

B01001_004 (path = (sex by age, estimate, total, male, 6 to 9 years)).

…

B01001_024 (path = (sex by age, estimate, total, male, 80 to 84 years)).

B01001_025 (path = (sex by age, estimate, total, male, 85 years and over)).

B01001_026 (path = (sex by age, estimate, total, female)).

B01001_027 (path = (sex by age, estimate, total, female, under 5 years)).

B01001_028 (path = (sex by age, estimate, total, female, 6 to 9 years)).

…

B01001_048 (path = (sex by age, estimate, total, female, 80 to 84 years)).

B01001_049 (path = (sex by age, estimate, total, female, 85 years and over)).

Parameters:

variable (str or Variable) – The requested variable.
include_root (bool = False) – Determines whether or not the requested variable will be included in the returned VariableCollection.

first_ancestor_of(variable: str | Variable) → Variable[source]

Returns the first (root) ancestor of the requested variable.

For example, the variable B01001_003 (path = (sex by age, estimate, total, male, under 5 years)) has a first ancestor of B01001_001 (path = (sex by age, estimate, total)).

Parameters:: variable (str or Variable) – The requested variable.

ancestors_of(variable: str | Variable, include_root: bool = False) → VariableCollection[source]

Returns the ancestors of the requested variable as a new VariableCollection.

For example, the variable B01001_003 (path = (sex by age, estimate, total, under 5 years)) has 2 ancestors:

B01001_001 (path = (sex by age, estimate, total)).

B01001_002 (path = (sex by age, estimate, total, male)).

Parameters:

variable (str or Variable) – The requested variable.
include_root (bool = False) – Determines whether or not the requested variable will be included in the returned VariableCollection.

filter_by_term(term: str | List[str], by: str = 'label') → VariableCollection[source]

Returns a new VariableCollection consisting of all variables that match the search. Can filter by each variable’s label or by the concept of each variable’s group.

Parameters:

term (str or list of str) – The search string or strings.
by (str = ‘label’) – If by is ‘label’, then variables will be filtered by their labels. Otherwise, by should be ‘concept’, and variables will be filtered by the concepts of their groups.

filter_by_group(group: str | Group) → VariableCollection[source]

Returns a new VariableCollection consisting of all variables within the given group.

Parameters:: group (str or Group) – The group to return.

to_df() → DataFrame[source]: Converts the VariableCollection into a pandas.DataFrame object detailing each variable’s name, label, group, concept, type, items, attributes, and path.

to_list() → List[Variable][source]: Converts the VariableCollection into a list of Variable objects.

visualize(label_type: str = 'name', hierarchical: bool = False, filename: str = 'variable_graph.html', show: bool = True, keep_file: bool = False, **kwargs)[source]

Visualizes the VariableCollection as a tree in your default webbrowser.

Parameters:

label_type (str = ‘name’) – Controls the labels of each variable (node). If label_type equals ‘name’, then the label of each variable is its name (B01001_001E, B01001_002E, B01001_003E, etc.). If label_type equals ‘difference’, then the label of each variable is the last element of its path (total, male, under 5 years, etc.). ‘difference’ shows the difference between each variable and its parent.
hierarchical (bool = False) – Determines whether the variables (nodes) are presented in a hierarchical layout (with root nodes at the top), as opposed to a layout that looks more like spokes on a wheel.
filename (str = ‘variable_graph.html’) – The path (from within the current working directory) the save the generated file at.
show (bool = True) – Determines whether or not to open the generated file in your default webbrowser.
keep_file (bool = False) – Determines whether or not to delete the generated file after opening it.

Geography

exception censaurus.geography.UnknownGeography[source]

exception censaurus.geography.InvalidGeographyHierarchy[source]

censaurus.geography.pad_geography_filters(geo_filters: Dict[str, str])[source]

Pads (with zeros) a set of geography filters to their appropriate lengths.

Parameters:: geo_filters (dict of str: str) – The geography filters to pad.

class censaurus.geography.Geography(params: Dict[str, Any])[source]

An object representing a single Census geography hierarchy.

Parameters:: params (dict of str: Any) – A set of parameters detailing the attributes of the Census geography hierarchy.

name[source]

The name of the geography hierarchy. For example, us, region, division, state, etc.

Type:: str or None

level[source]

The level (represented as an integer) or the geography hierarchy.

Type:: int or None

requires[source]

A list of other Census geography hierarchies that this hierarchy depends on. For example, county may require state.

Type:: list of str or None

wildcard[source]

A list of other Census geography hierarchies that this hierarchy depends on that can be used as a wildcard. For example, state can be a wildcard when requesting counties.

Type:: list of str or None

optional_wildcard[source]

The lowest level optional wildcards.

Type:: list of str or None

ordered_others[source]

A list of all required hierarchies in hierarchical order.

Type:: list of str or None

path[source]

A path representing the geography hierarchy. For example, (state, county, tract).

Type:: tuple of str

parent_path[source]

A path representing the geography hierarchy’s parent. For example, the parent of the geography hierarchy with path (state, county, tract) is the hierarchy with path (state, county).

Type:: tuple of str

readable_path[source]

The elements of the path of this variable joined by “ -> “. For example, the geography hierarchy with path (state, county, tract) has a readable_path of state -> county -> tract.

Type:: str

class censaurus.geography.GeographyCollection(supported_geographies_json: Dict[str, str])[source]

An object representing a collection of available Census geography hierarchies.

Parameters:: supported_geographies_json (dict of str: (dict of str: str)) – A dictionary detailing the attributes of each geography hierarchy.

get(level: str = None, name: str = None) → Geography | List[Geography][source]

Returns the requested Geography object if it exists, or a list of Geography objects if there are multiple matches. Otherwise, raises an UnknownGeography exception. Can search by level or name.

Parameters:

level (str) – The requested geography hierarchy represented by its level.
name (str) – The requested geography hierarchy represented by its name. Note that since the same name may refer to multiple geographies, specifying a name may return a list.

to_df() → DataFrame[source]: Converts the GeographyCollection into a pandas.DataFrame object detailing each geography’s name, level, and requirements.

to_list()[source]: Converts the GeographyCollection into a list of Geography objects.

visualize(label_type: str = 'difference', hierarchical: bool = False, filename: str = 'geography_graph.html', show: bool = True, keep_file: bool = False, **kwargs)[source]

Visualizes the GeographyCollection as a tree in your default webbrowser.

Parameters:

label_type (str = ‘path’) – Controls the labels of each geography hierarchy (node). If label_type equals ‘path’, then the label of each variable is its path ((state), (state, county), (state, county, tract), etc.). If label_type equals ‘difference’, then the label of each hierarchy is the last element of its path (state, county, tract, etc.). ‘difference’ shows the difference between each hierarchy and its parent.
hierarchical (bool = False) – Determines whether the geography hierarchies (nodes) are presented in a hierarchical layout (with root nodes at the top), as opposed to a layout that looks more like spokes on a wheel.
filename (str = ‘geography_graph.html’) – The path (from within the current working directory) the save the generated file at.
show (bool = True) – Determines whether or not to open the generated file in your default webbrowser.
keep_file (bool = False) – Determines whether or not to delete the generated file after opening it.

Custom `pandas` functionality

class censaurus.census_accessors.DataFrameCensusAccessor(pandas_obj)[source]

Custom pandas.DataFrame accessors. Allows users to access the geography and variables associated with a pandas.DataFrame object that was generated by censaurus. Properties can be accessed by calling dataset.census.<property>.

property geography: Geography[source]: Returns the geography hierarchy associated with the pandas.DataFrame.

property variables: VariableCollection[source]: Returns the variable collection associated with the pandas.DataFrame.

class censaurus.census_accessors.SeriesCensusAccessor(pandas_obj)[source]

Custom pandas.Series accessors. Allows users to access the variable associated with a pandas.Series object from within a pandas.DataFrame that was generated by censaurus. Properties can be accessed by calling dataset["column"].census.<property>.

property variable: Variable[source]: Returns the variable associated with the pandas.Series.

TIGER and Geometry

censaurus.tiger.parse_name(name: str) → str[source]

Parses the name of a geographic area. Replaces state abbreviations with full state names and removes any leading zeros.

Parameters:: name (str) – The name to parse.

censaurus.tiger.generate_detailed_name(feature: Series, layer_name: str) → str[source]

Generates a detailed name of a geographic area. Parses the name and adds the state, if necessary.

Parameters:

feature (pandas.Series) – A pandas.Series representing the geographic area.
layer_name (str) – The layer the geographic area comes from.

censaurus.tiger.tokenize_feature_name(feature_name: str) → set[source]

Splits a detailed name of a geographic area into tokens.

Parameters:: feature_name (str) – The name to tokenize.

censaurus.tiger.build_custom_scorer(count_map: Dict[str, int], N: int) → Tuple[Callable[[str, str], float], Dict[str, float]][source]

Constructs a custom scoring function for edit distance. The custom scorer is mostly based on Normalized Setwise Levenshtein Distance, proposed in https://arxiv.org/pdf/1903.09238.pdf, with additions to account for word importance.

Parameters:

count_map (dict of str: float) – A dictionary that details the number of times each unique token in a set of geographic area names appears.
N (int) – The total number of tokens.

class censaurus.tiger.Area[source]

An object representing a single geographic area.

name[source]

The name of the geographic area.

Type:: str

layer_name[source]

The name of the layer the geographic area is derived from, if the area comes from TIGERWeb. Otherwise, this should be None.

Type:: str or None

attributes[source]

A dictionary detailing the attributes of the geographic area.

Type:: dict of str: str

geometry[source]

The geometric boundary of the geographic area.

Type:: shapely.Polygon or shapely.MultiPolygon

plot(**kwargs) → None[source]

Generates a plot of the geographic area using matplotlib.

Parameters:: **kwargs – Any additional plotting parameters to pass to matplotlib when calling matplotlib.pyplot.fill().

intersect_with_cb() → None[source]: Intersects the geometric boundary of the geographic area with the cartographic boundary of the United States.

classmethod from_tiger(geo_id: str, layer_id: int, layer_name: str, tiger_client: TIGERClient, intersect_with_cb: bool = True) → Area[source]

Constructs a Area object from TIGERWeb.

Parameters:

geo_id (str) – The geographic identifier of the area.
layer_id (int) – The identifier of the layer the area is derived from.
layer_name (str) – The name of the layer the area is derived from.
tiger_client (TIGERClient) – A client to use to interface with TIGERWeb.
intersect_with_cb (bool = True) – Determines whether the geometric boundary of the area should be intersected with the cartographic boundary of the United States.

classmethod from_url(name: str, url: str, geo_col: str = 'geometry', intersect_with_cb: bool = True) → Area[source]

Constructs a Area object from a URL.

Parameters:

name (str) – The name of the geographic area.
url (str) – The URL to fetch the geographic area from.
geo_col (str) – The column within the file the url points to that details the geometry of the area.
intersect_with_cb (bool = True) – Determines whether the geometric boundary of the area should be intersected with the cartographic boundary of the United States.

classmethod from_file(name: str, filename: str, geo_col: str = 'geometry', intersect_with_cb: bool = True) → Area[source]

Constructs a Area object from a filename.

Parameters:

name (str) – The name of the geographic area.
filename (str) – The filename to read the geographic area from.
geo_col (str) – The column within the file the filename points to that details the geometry of the area.
intersect_with_cb (bool = True) – Determines whether the geometric boundary of the area should be intersected with the cartographic boundary of the United States.

class censaurus.tiger.Layer(info: Dict[str, str], tiger_client: TIGERClient)[source]

An object representing a layer of a TIGERWeb MapService.

Parameters:

info (dict of str: str) – A dictionary detailing the attributes of the layer.
tiger_client (TIGERClient) – A client to use to interface with TIGERWeb.

name[source]

The name of the TIGERWeb MapService layer.

Type:: str

id[source]

The identifier of the TIGERWeb MapService layer.

Type:: str

fields[source]

The available fields to use when querying this layer.

Type:: list of str

get_features(bbox: Iterable[float] = None, out_fields: str = '*', return_geometry: bool = False, cb: bool = True) → GeoDataFrame[source]

Get a set of features in this layer.

Parameters:

bbox (array-like of float = None) – A bounding box to subset the layer. Points should be in CRS 4236. bbox should be of length four.
out_fields (str = ‘*’) – Controls what parameters are returned for each feature.
return_geometry (bool = False) – Determines whether or not the geometry of each feature is included in the returned geopandas.GeoDataFrame.
cb (bool = True) – Determines whether or not the geometry of each feature will be intersected with the cartographic boundary of the United States.

get_area_by_geo_id(geoid: str, cb: bool = True) → Area[source]

Searches the layer for a feature from a geographic identifier.

geoidstr: The identifier to search for.
cbbool = True: Determines whether or not the geometry of the resulting feature will be intersected with the cartographic boundary of the United States.

get_area_by_name(name: str, cb: bool = True) → Area[source]

Searches the layer for a feature from a name. Please be as detailed as possible when searching for a name. For example, you should use Los Angeles, California instead of LA or even Los Angeles. Name matching is done with a custom string distance function partially based on Normalized Setwise Levenshtein Distance, as defined in https://arxiv.org/pdf/1903.09238.pdf.

namestr: The name to search for.
cbbool = True: Determines whether or not the geometry of the resulting feature will be intersected with the cartographic boundary of the United States.

class censaurus.tiger.AreaCollection(map_service: str = 'tigerWMS_Current')[source]

An object that represents a collection of geographic areas.

:param map_service str = ‘tigerWMS_Current’: The TIGERWeb MapService to use as the basis for this collection. Defaults to the: current map service.

tiger_client[source]

A client to use to interface with TIGERWeb.

Type:: TIGERClient

available_layers[source]

A dictionary detailing the available layers for this collection, based on the map_service used.

Type:: dict of str, Layer

get_layer(layer_name: str) → Layer[source]

Searches the available layers by name.

:param layer_name str: The name to search for.

get_features_within(within: Area | List[Area], layer_name: str | List[str], area_threshold: float)[source]

Gets the features within a geographic area (or areas) and a specific layer.

withinArea or list of Area = None: A censaurus.Area object or a list of censaurus.Area objects. Only geographic areas whose geometries lay within the bounds of the within area (or areas) will be included. Note that what it means for an area to be “within” depends on the area_threshold parameter.
layer_namestr: The name of the TIGERWeb MapService layer to query.
area_thresholdfloat: Only geographic areas where (total area of the geography intersected with the within area (or areas) / total area of the geography) is greater than area_threshold will be included. The default of 0.01 ensures that geographic areas that only intersect with the within area (or areas) on the boundary will not be included (boundary intersections have zero area).

area(name: str = None, geoid: str = None, layer_name: str = '', cb: bool = True) → Area[source]

Searches a layer for an area with a given name or identifier. Note that you should only supply a name or an identifier, but not both.

Parameters:

name (str = None) – A name to search for.
geoid (str = None) – A geographic identifier to search for.
layer_name (str = ‘’) – The layer to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting feature will be intersected with the cartographic boundary of the United States.

area_multilayer(name: str = None, geoid: str = None, layer_names: List[str] = [], specific_layer: str = None, cb: bool = True) → Area[source]

Searches a layer (or layers) for an area with a given name or identifier. Note that you should only supply a name or an identifier, but not both.

Parameters:

name (str = None) – A name to search for.
geoid (str = None) – A geographic identifier to search for.
layer_names (list of str = []) – A list of layers to search for.
specific_layer (str = None) – A specific layers to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting feature will be intersected with the cartographic boundary of the United States.

region(region: str = None, geoid: str = None, cb: bool = True) → Area[source]

Searches the Census Regions layer for a specific region. See here for an overview of Census regions. Can search by name or geographic identifier. Note that you should only supply a region name or an identifier, but not both. Available region names are:

Northeast Region

South Region

Midwest Region

West Region

Parameters:

region (str = None) – The name of the region to search for.
geoid (str = None) – The identifier of the region to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting region will be intersected with the cartographic boundary of the United States.

division(division: str = None, geoid: str = None, cb: bool = True) → Area[source]

Searches the Census Divisions layer for a specific division. See here for an overview of Census divisions. Can search by name or geographic identifier. Note that you should only supply a region name or an identifier, but not both. Available division names are:

New England Division

Middle Atlantic Division

South Atlantic Division

East South Central Division

West South Central Division

East North Central Division

West North Central Division

Mountain Division

Pacific Division

Parameters:

division (str = None) – The name of the division to search for.
geoid (str = None) – The identifier of the region to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting division will be intersected with the cartographic boundary of the United States.

state(state: str = None, geoid: str = None, cb: bool = True) → Area[source]

Searches the States layer for a specific state. Can search by name or geographic identifier. Note that you should only supply a state name or an identifier, but not both. State names can be abbreviations (AL, AK, AZ, etc.) or full names (Alabama, Alaska, Arizona, etc.).

Parameters:

state (str = None) – The name of the state to search for.
geoid (str = None) – The identifier of the state to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting state will be intersected with the cartographic boundary of the United States.

county(county: str = None, geoid: str = None, cb: bool = True) → Area[source]

Searches the Counties layer for a specific county. Can search by name or geographic identifier. Note that you should only supply a county name or an identifier, but not both. County names should ideally be as specific as possible to ensure correct matches. Some examples include:

Los Angeles, California

Montgomery County, Maryland

Wayne County, Michigan

Parameters:

county (str = None) – The name of the county to search for.
geoid (str = None) – The identifier of the county to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting county will be intersected with the cartographic boundary of the United States.

tract(geoid: str = None, cb: bool = True) → Area[source]

Searches the Census Tracts layer for a specific tract.

Parameters:

geoid (str = None) – The identifier of the tract to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting tract will be intersected with the cartographic boundary of the United States.

block_group(geoid: str = None, cb: bool = True) → Area[source]

Searches the Census Block Groups layer for a specific block group.

Parameters:

geoid (str = None) – The identifier of the block group to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting block group will be intersected with the cartographic boundary of the United States.

blocks(geoid: str = None, cb: bool = True) → Area[source]

Searches the Census Blocks layer for a specific block.

Parameters:

geoid (str = None) – The identifier of the block to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting block will be intersected with the cartographic boundary of the United States.

place(place: str = None, geoid: str = None, place_type: str = None, cb: bool = True) → Area[source]

Searches the place layers for a specific Census place. Can search by name or geographic identifier. Note that you should only supply a place name or an identifier, but not both. Place names should ideally be as specific as possible to ensure correct matches. Some examples include:

Chicago, Illinois

Houston, Texas

Seneca Falls, New York

Parameters:

place (str = None) – The name of the place to search for.
geoid (str = None) – The identifier of the place to search for.
place_type (str = None) – The type of the Census place you are search for. Should be either Census Designated Places or Incorporated Places. Not specifying this value means that both layers will be searched, which can take longer.
cb (bool = True) – Determines whether or not the geometry of the resulting place will be intersected with the cartographic boundary of the United States.

MSA(MSA: str = None, geoid: str = None, M_type: str = None, cb: bool = True) → Area[source]

Searches the MSA layers for a specific MSA. Can search by name or geographic identifier. Note that you should only supply a MSA name or an identifier, but not both. MSA names should ideally be as specific as possible to ensure correct matches. Some examples include:

Knoxville, Tennessee Metro Area

Baltimore-Columbia-Towson, Maryland Metro Area

Ithaca, New York Metro Area

Parameters:

MSA (str = None) – The name of the MSA to search for.
geoid (str = None) – The identifier of the MSA to search for.
M_type (str = None) – The type of the MSA you are search for. Should be either Metropolitan Statistical Area or Micropolitan Statistical Area. Not specifying this value means that both layers will be searched, which can take longer.
cb (bool = True) – Determines whether or not the geometry of the resulting MSA will be intersected with the cartographic boundary of the United States.

CSA(CSA: str = None, geoid: str = None, cb: bool = True) → Area[source]

Searches the Combined Statistical Area layer for a specific CSA. Can search by name or geographic identifier. Note that you should only supply a CSA name or an identifier, but not both. CSA names should ideally be as specific as possible to ensure correct matches. Some examples include:

Phoenix-Mesa, Arizona CSA

Minneapolis-St. Paul, Minnesota-Wisconsin CSA

Dallas-Fort Worth, TX-OK Combined Statistical Area

Parameters:

CSA (str = None) – The name of the CSA to search for.
geoid (str = None) – The identifier of the CSAs to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting CSA will be intersected with the cartographic boundary of the United States.

congressional_district(congressional_district: str = None, geoid: str = None, cb: bool = True) → Area[source]

Searches the Congressional Districts layer for a specific district. Can search by name or geographic identifier. Note that you should only supply a district name or an identifier, but not both. District names should ideally be as specific as possible to ensure correct matches.

Ohio District 1

UT-01

New York 1

Parameters:

congressional_district (str = None) – The name of the congressional district to search for.
geoid (str = None) – The identifier of the congressional district to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting congressional district will be intersected with the cartographic boundary of the United States.

ZCTA(geoid: str = None, cb: bool = True) → Area[source]

Searches the Census ZIP Code Tabulation Areas layer for a specific ZCTA.

Parameters:

geoid (str = None) – The identifier of the ZCTA to search for.
cb (bool = True) – Determines whether or not the geometry of the resulting ZCTA will be intersected with the cartographic boundary of the United States.

Renaming

class censaurus.rename.Renamer(separator: str = '|', default_rename_function: ~typing.Callable[[str], str] = <function Renamer.<lambda>>, replacements: ~typing.Dict[str, str] = {}, custom_match_functions: ~typing.Dict[str, ~typing.Callable[[~re.Match, str], str]] = {}, group_prefixes: ~typing.Dict[str, str] = {})[source]

An object that handles renaming Census variable names in datasets.

Parameters:

separator (str = ‘|’) – The string to use to join individual tokens from the label of a Variable.
default_rename_function (function of str -> str = lambda x : x) – The default function to pass individual tokens from the label of a Variable into. Defaults to simply returning the token.
replacements (dict of str:str = {}) – Individual tokens to search for (keys of the dictionary) and replace (values of the dictionary).
custom_match_functions (dict of str: function of (re.Match, str) -> str = {}) – A dictionary where each key represents to a renaming function that takes as an input a match and a string and returns a string. The individual tokens from the label of a Variable are checked against each key in this dictionary: if there is a match, the corresponding renaming function is used.
group_prefixes (dict of str: str = {}) – If a Variable is in a group that matches to a key in this dictionary, the prefix of the column name after the renaming will be the corresponding value in the dictionary as opposed to that group’s concept (the default behavior).

add_group_prefixes(group_prefixes: Dict[str, str]) → None[source]

Adds additional group prefixes to an existing Renamer.

Parameters:: group_prefixes (dict of str: str = {}) – The groups and prefixes to add.

rename(data: DataFrame)[source]

Renames the columns of the dataset.

Parameters:: data (pandas.DataFrame) – The data to rename.

censaurus.rename.SIMPLE_RENAMER = <censaurus.rename.Renamer object>[source]: A Renamer object that renames variables in a simple way. Has custom match functions to handle: age, race, variable types, inflation, and incomes.

Regrouping

class censaurus.regroup.Regrouper(groupings: Dict[str, Iterable[str]] = {})[source]

An object to handle regrouping Census variables.

Parameters:: groupings (dict of str: array-like of str) – Each key in this dictionary is the name of a new group. Each corresponding value should be a list of elements that fall into that group. For example, groupings={"white_or_black": ["white alone", "black or african american alone"]} would aggregate all columns that have the token white alone or the token black or african american alone, and create a new column with those tokens replaces as white_or_black.

regroup(data: DataFrame)[source]

Regroups the columns of the dataset. Note that you should probably rename the data after a regrouping with a Renamer object to avoid long column names.

Parameters:: data (pandas.DataFrame) – The data to regroup.

censaurus.regroup.FIVE_RACE_REGROUPER = <censaurus.regroup.Regrouper object>[source]: A Regrouper object that aggregates some other race alone, two or more races, american indian and alaska native alone, native hawaiian and other pacific islander alone into a group called other.

class censaurus.regroup.AgeRegrouper(age_brackets: List[str])[source]

A subclass of the Regouper class that specifically handles regrouping into new age buckets.

Parameters:: age_brackets (list of str) – The new age brackets to group into. Must be of the form "<start_year>-<end_year>", except for the oldest age bracket, which should be of the form <start_year>+. For example, age_brackets=["0-17", "18-29", "30-49", "50-64", "65+"].

regroup(data: DataFrame) → DataFrame[source]

Regroups the columns of the dataset. Note that you should probably rename the data after a regrouping with a Renamer object to avoid long column names.

Parameters:: data (pandas.DataFrame) – The data to regroup.

Recoding

exception censaurus.recode.RecodeError[source]

class censaurus.recode.StateRecoder[source]

An object that handles recoding state to various formats. The available formats are:

FIPS: FIPS codes with no zero-padding (1, 2, 4, etc.)

FIPS_PADDED: FIPS codes with two-digit zero-padding (01, 02, 04, etc.)

ABBR: state abbreviations (AL, AK, AZ, etc.)

NAME: full state names (Alabama, Alaska, Arizona, etc.)

GNIS: Geographic Names Information System codes (1779775, 1785533, 1779777 etc.)

GNIS_PADDED: Geographic Names Information System codes with seven-digit zero-padding (1779775, 1785533, 1779777 etc.)

to_FIPS(data: DataFrame, state_col: str = 'state')[source]

Recodes states as FIPS codes (1, 2, 4, etc.). Attempts to infer the original state format.

Parameters:

data (pandas.DataFrame) – The data with a column to recode.
state_col (str = ‘state’) – The column in the dataset that list states.

to_FIPS_PADDED(data: DataFrame, state_col: str = 'state')[source]

Recodes states as two-digit zero-padded FIPS codes (01, 02, 04, etc.). Attempts to infer the original state format.

Parameters:

data (pandas.DataFrame) – The data with a column to recode.
state_col (str = ‘state’) – The column in the dataset that list states.

to_ABBR(data: DataFrame, state_col: str = 'state')[source]

Recodes states as abbreviations (AL, AK, AZ, etc.). Attempts to infer the original state format.

Parameters:

data (pandas.DataFrame) – The data with a column to recode.
state_col (str = ‘state’) – The column in the dataset that list states.

to_NAME(data: DataFrame, state_col: str = 'state')[source]

Recodes states as full names (Alabama, Alaska, Arizona, etc.). Attempts to infer the original state format.

Parameters:

data (pandas.DataFrame) – The data with a column to recode.
state_col (str = ‘state’) – The column in the dataset that list states.

to_GNIS(data: DataFrame, state_col: str = 'state')[source]

Recodes states as GNIS codes (1779775, 1785533, 1779777 etc.). Attempts to infer the original state format.

Parameters:

data (pandas.DataFrame) – The data with a column to recode.
state_col (str = ‘state’) – The column in the dataset that list states.

to_GNIS_PADDED(data: DataFrame, state_col: str = 'state')[source]

Recodes states as GNIS codes (1779775, 1785533, 1779777 etc.). Attempts to infer the original state format.

Parameters:

data (pandas.DataFrame) – The data with a column to recode.
state_col (str = ‘state’) – The column in the dataset that list states.

Census and TIGERWeb APIs

exception censaurus.api.CensusAPIKeyError[source]

exception censaurus.api.CensusAPIError(status_code: int, message: str)[source]

exception censaurus.api.TIGERWebAPIError(status_code: int, message: str)[source]

class censaurus.api.AsyncLoopHandler[source]

Class to handle asynchronous requests. Useful especially in the case where a user is writing code inside an IPython environment.

Adapted from https://stackoverflow.com/a/66055205/17834461

run()[source]

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

class censaurus.api.CensusClient(url_extension: str, api_key: str = None, **kwargs)[source]

An object that interfaces with the Census API. Extends the httpx.AsyncClient` class to allow for asynchronous requests.

Parameters:

url_extension (str) – A URL extension to append to https://api.census.gov/data/ for accessing data related to a specific Dataset.
api_key (str = None) –
A Census API key. Can be obtained here. Not necessary unless you are making a large number of calls.

get_sync(url: str = '', params: Dict[str, str] = {}) → Response[source]

Make a single request to the Census API synchronously.

Parameters:

url (str = ‘’) – The relative URL to request.
params (dict of str: str) – Query parameters to supply to the Census API.

get_many_sync(url_params_list: Iterable[Tuple[str, Dict[str, str]]] = []) → List[Response][source]

Make a more than one request to the Census API synchronously. Note that while the requests are still sent asynchronously, the function call itself is synchronous.

Parameters:: url_params_list (array-like of tuple of str and dict of str: str) – An array-like of tuples, where each tuple consists of a URL to request and a set of query parameters to supply to the Census API.

async get(url: str = '', params: Dict[str, str] = {}) → Response[source]

Make a single request to the Census API asynchronously.

Parameters:

url (str = ‘’) – The relative URL to request.
params (dict of str: str) – Query parameters to supply to the Census API.

async get_many(url_params_list: Iterable[Tuple[str, Dict[str, str]]] = []) → List[Response][source]

Make a more than one request to the Census API asynchronously.

Parameters:: url_params_list (array-like of tuple of str and dict of str: str) – An array-like of tuples, where each tuple consists of a URL to request and a set of query parameters to supply to the Census API.

class censaurus.api.TIGERClient(map_service: str = 'tigerWMS_Current', **kwargs)[source]

An object that interfaces with the TIGERWeb API. Extends the httpx.AsyncClient` class to allow for asynchronous requests.

Parameters:: map_service (str = ‘tigerWMS_Current’) – The TIGERWeb MapService to use as the basis for this client. Defaults to the current map service.

get_sync(url: str = '', params: Dict[str, str] = {}, return_type: str = 'json') → Response[source]

Make a single request to the TIGERWeb API synchronously.

Parameters:

url (str = ‘’) – The relative URL to request.
params (dict of str: str) – Query parameters to supply to the TIGERWeb API.
return_type (str = ‘json’) – Determines the type of data to return. Should either be json or geojson.

get_many_sync(url_params_list: List[Tuple[str, Dict[str, str]]] = [], return_type='json') → List[Response][source]

Make a more than one request to the TIGERWeb API synchronously. Note that while the requests are still sent asynchronously, the function call itself is synchronous.

Parameters:: url_params_list (array-like of tuple of str and dict of str: str) – An array-like of tuples, where each tuple consists of a URL to request and a set of query parameters to supply to the TIGERWeb API.

async get(url: str = '', params: Dict[str, str] = {}, return_type='json') → Response[source]

Make a single request to the TIGERWeb API asynchronously.

Parameters:

url (str = ‘’) – The relative URL to request.
params (dict of str: str) – Query parameters to supply to the TIGERWeb API.
return_type (str = ‘json’) – Determines the type of data to return. Should either be json or geojson.

async get_many(url_params_list: Iterable[Tuple[str, Dict[str, str]]] = [], return_type='json') → List[Response][source]

Make a more than one request to the TIGERWeb API asynchronously.

Parameters:: url_params_list (array-like of tuple of str and dict of str: str) – An array-like of tuples, where each tuple consists of a URL to request and a set of query parameters to supply to the TIGERWeb API.

API documentation

Datasets

Variables

Geography

Custom pandas functionality

TIGER and Geometry

Renaming

Regrouping

Recoding

Census and TIGERWeb APIs

Custom `pandas` functionality