Census Areas Documentation¶
This Python library extends the Census API Wrapper to allow querying Census tracts, block groups, and blocks by Census place, as well as by arbitrary geographies.
Setup¶
Get the library and its dependencies using pip:
pip install census_area
Usage¶
from census_area import Census
c = Census("MY_API_KEY")
old_homes = c.acs5.state_place_tract(
('NAME', 'B25034_010E'), 17, 14000
)
The call above will return the name of the census tract and the number of homes
that were built before 1939 for every tract in the City of Chicago. 17
is
the FIPS code for Illinois and 14000
is the FIPS code for Chicago.
By default, this method will return a list of dictionaries, where each dictionary represents the data for one tract.
With the return_geometry
argument, you can have the method return a
geojson-like dictionary. Each tract is a feature, and the census variables
about the tract appear in the feature’s property attributes.
old_homes_geojson = c.acs5.state_place_tract(
('NAME', 'B25034_010E'), 17, 14000,
return_geometry=True
)
There are similar methods for block groups –
old_home_block_groups = c.acs5.state_place_blockgroup(
('NAME', 'B25034_010E'), 17, 14000
)
– and blocks.
owner_occupied = c.sf1.state_place_block(
('NAME', 'H016F0002'), 17, 14000
)
Note that block-level geographies are only available for the short-form data from the Decennial Census and redistricting summary files.
Series |
Tract |
Block Group |
Block |
---|---|---|---|
ACS 5-Year Estimates |
✅ |
✅ |
|
Decennial Census Short Form |
✅ |
✅ |
✅ |
Redistricting Summary Files |
✅ |
✅ |
✅ |
In addition to these convenient methods, there are lower level methods to
get census tracts, blocks, and groups for arbitrary geometries: geo_tract()
,
geo_blockgroup()
, geo_block()
.
Consider this example:
import json
with open('my_shape.geojson') as infile:
my_shape_geojson = json.load(infile)
features = []
# N.b., your geometry must be in ESPG:4326
old_homes = c.acs5.geo_tract(
('NAME', 'B25034_010E'), my_shape_geojson['geometry']
)
for tract_geojson, tract_data, tract_proportion in old_homes:
tract_geojson['properties'].update(tract_data)
features.append(tract)
my_shape_with_new_data_geojson = {
'type': 'FeatureCollection',
'features': features
}
The geo_tract()
method takes in the census variables you want and a
geojson geometry, and returns a generator of the tract shapes, as geojson
features, and the variables for that tract. Additionally, the generator returns
a “tract proportion”; this is the proportion of the area of the tract that falls
within your target shape.
geo_block()
and geo_blockgroup()
work in the same manner.
API¶
Census
Object¶
- class census_area.Census(key, year=None, session=None)¶
Unified API for accessing Census data
Attributes:
acs5: instance of ACS5Client
sf1: instance of SF1Client
pl: instance of PLClient
ACS5Client
Object¶
- class census_area.core.ACS5Client(key, year=None, session=None, retries=3)¶
Client to access American Community Survey 5-Year Estimates (see: https://www.census.gov/data/developers/data-sets/acs-5year.html)
- state_place_tract(*args, **kwargs)¶
Retrieve variable values for tracts in the specified state and incorporated place.
Arguments:
fields (iterable) - Variables to retrieve
state (int or str) - state FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#state)
place (int or str) - place FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#place)
year (int) - data year
return_geometry (bool) - set True to return results as GeoJSON like object (default: False)
Returns:
List with dictionary for each tract containing variable values.
- state_place_blockgroup(*args, **kwargs)¶
Retrieve variable values for block groups in the specified state and incorporated place.
Arguments:
fields (iterable) - Variables to retrieve
state (int or str) - state FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#state)
place (int or str) - place FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#place)
year (int) - data year
return_geometry (bool) - set True to return results as GeoJSON like object (default: False)
Returns:
List with dictionary for each block group containing variable values.
- geo_tract(fields, geojson_geometry, year=None, **kwargs)¶
Retrieve variable values for tracts intersecting with an arbitrary geometry.
Arguments:
fields (iterable) - Variables to retrieve
geojson_geometry (dict) - Geometry object in ESPG:4326
year (int) - data year
Returns:
Generator with three-tuple for each tract containing: tract geometry, dictionary containing variable values, and proportion of tract that overlaps with the arbitrary geometry
- geo_blockgroup(fields, geojson_geometry, year=None, **kwargs)¶
Retrieve variable values for block groups intersecting with an arbitrary geometry.
Arguments:
fields (iterable) - Variables to retrieve
geojson_geometry (dict) - Geometry object in ESPG:4326
year (int) - data year
Returns:
Generator with three-tuple for each block group containing: block group geometry, dictionary containing variable values, and proportion of block group that overlaps with the arbitrary geometry
SF1Client
Object¶
- class census_area.core.SF1Client(key, year=None, session=None, retries=3)¶
Client to access Census Summary File data (see https://www.census.gov/data/datasets/2010/dec/summary-file-1.html)
- state_place_tract(*args, **kwargs)¶
Retrieve variable values for tracts in the specified state and incorporated place.
Arguments:
fields (iterable) - Variables to retrieve
state (int or str) - state FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#state)
place (int or str) - place FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#place)
year (int) - data year
return_geometry (bool) - set True to return results as GeoJSON like object (default: False)
Returns:
List with dictionary for each tract containing variable values.
- state_place_blockgroup(*args, **kwargs)¶
Retrieve variable values for block groups in the specified state and incorporated place.
Arguments:
fields (iterable) - Variables to retrieve
state (int or str) - state FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#state)
place (int or str) - place FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#place)
year (int) - data year
return_geometry (bool) - set True to return results as GeoJSON like object (default: False)
Returns:
List with dictionary for each block group containing variable values.
- state_place_block(*args, **kwargs)¶
Retrieve variable values for blocks in the specified state and incorporated place.
Arguments:
fields (iterable) - Variables to retrieve
state (int or str) - state FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#state)
place (int or str) - place FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#place)
year (int) - data year
return_geometry (bool) - set True to return results as GeoJSON like object (default: False)
Returns:
List with dictionary for each block containing variable values.
- geo_tract(fields, geojson_geometry, year=None, **kwargs)¶
Retrieve variable values for tracts intersecting with an arbitrary geometry.
Arguments:
fields (iterable) - Variables to retrieve
geojson_geometry (dict) - Geometry object in ESPG:4326
year (int) - data year
Returns:
Generator with three-tuple for each tract containing: tract geometry, dictionary containing variable values, and proportion of tract that overlaps with the arbitrary geometry
- geo_blockgroup(fields, geojson_geometry, year=None, **kwargs)¶
Retrieve variable values for block groups intersecting with an arbitrary geometry.
Arguments:
fields (iterable) - Variables to retrieve
geojson_geometry (dict) - Geometry object in ESPG:4326
year (int) - data year
Returns:
Generator with three-tuple for each block group containing: block group geometry, dictionary containing variable values, and proportion of block group that overlaps with the arbitrary geometry
- geo_block(fields, geojson_geometry, year)¶
Retrieve variable values for blocks intersecting with an arbitrary geometry.
Arguments:
fields (iterable) - Variables to retrieve
geojson_geometry (dict) - Geometry object in ESPG:4326
year (int) - data year
Returns:
Generator with three-tuple for each block containing: block geometry, dictionary containing variable values, and proportion of block that overlaps with the arbitrary geometry
PLClient
Object¶
- class census_area.core.PLClient(key, year=None, session=None, retries=3)¶
Client to access Redistricting data (see https://www.census.gov/programs-surveys/decennial-census/about/rdo/summary-files.2020.html)
- state_place_tract(*args, **kwargs)¶
Retrieve variable values for tracts in the specified state and incorporated place.
Arguments:
fields (iterable) - Variables to retrieve
state (int or str) - state FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#state)
place (int or str) - place FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#place)
year (int) - data year
return_geometry (bool) - set True to return results as GeoJSON like object (default: False)
Returns:
List with dictionary for each tract containing variable values.
- state_place_blockgroup(*args, **kwargs)¶
Retrieve variable values for block groups in the specified state and incorporated place.
Arguments:
fields (iterable) - Variables to retrieve
state (int or str) - state FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#state)
place (int or str) - place FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#place)
year (int) - data year
return_geometry (bool) - set True to return results as GeoJSON like object (default: False)
Returns:
List with dictionary for each block group containing variable values.
- state_place_block(*args, **kwargs)¶
Retrieve variable values for blocks in the specified state and incorporated place.
Arguments:
fields (iterable) - Variables to retrieve
state (int or str) - state FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#state)
place (int or str) - place FIPS code (see https://www.census.gov/library/reference/code-lists/ansi.html#place)
year (int) - data year
return_geometry (bool) - set True to return results as GeoJSON like object (default: False)
Returns:
List with dictionary for each block containing variable values.
- geo_tract(fields, geojson_geometry, year=None, **kwargs)¶
Retrieve variable values for tracts intersecting with an arbitrary geometry.
Arguments:
fields (iterable) - Variables to retrieve
geojson_geometry (dict) - Geometry object in ESPG:4326
year (int) - data year
Returns:
Generator with three-tuple for each tract containing: tract geometry, dictionary containing variable values, and proportion of tract that overlaps with the arbitrary geometry
- geo_blockgroup(fields, geojson_geometry, year=None, **kwargs)¶
Retrieve variable values for block groups intersecting with an arbitrary geometry.
Arguments:
fields (iterable) - Variables to retrieve
geojson_geometry (dict) - Geometry object in ESPG:4326
year (int) - data year
Returns:
Generator with three-tuple for each block group containing: block group geometry, dictionary containing variable values, and proportion of block group that overlaps with the arbitrary geometry
- geo_block(fields, geojson_geometry, year)¶
Retrieve variable values for blocks intersecting with an arbitrary geometry.
Arguments:
fields (iterable) - Variables to retrieve
geojson_geometry (dict) - Geometry object in ESPG:4326
year (int) - data year
Returns:
Generator with three-tuple for each block containing: block geometry, dictionary containing variable values, and proportion of block that overlaps with the arbitrary geometry