Skip to main content
The census module provides utilities for retrieving demographic data and geographic boundaries from the US Census Bureau API, including block group enrichment for property valuation models.

​
Service Classes

​
CensusCredentials

Object for storing US Census API credentials. 
from openavmkit.utilities.census import CensusCredentials

credentials = CensusCredentials(api_key='your_census_api_key')
​
api_key
str
required
API Key for the US Census

​
CensusService

Provides functions for downloading data from the US Census. 
from openavmkit.utilities.census import CensusService, CensusCredentials

credentials = CensusCredentials(api_key='your_api_key')
service = CensusService(credentials)
​
credentials
CensusCredentials
required
Credentials for the US Census

​
Census Data Retrieval

​
get_census_data()

Get Census demographic data for block groups in a given FIPS code. 
from openavmkit.utilities.census import CensusService

df = service.get_census_data(
    fips_code='06001',
    year=2022,
    census_settings=None
)
​
fips_code
str
required
5-digit FIPS code (state + county)
​
year
int
default:"2022"
Census year to query
​
census_settings
dict
default:"None"
Census settings dictionary
​
df
pd.DataFrame
DataFrame containing Census demographic data with columns:
  • median_income: Median household income
  • total_population: Total population
  • median_g_rent: Median gross rent
  • median_c_rent: Median contract rent
  • std_geoid: Standardized GEOID (state + county + tract + block group)
  • Various FIPS component fields

​
get_census_blockgroups_shapefile()

Get Census Block Group shapefiles for a given FIPS code from the Census TIGERweb service. 
gdf = service.get_census_blockgroups_shapefile(fips_code='06001')
​
fips_code
str
required
5-digit FIPS code (state + county)
​
gdf
gpd.GeoDataFrame
GeoDataFrame containing Census Block Group boundaries with:
  • geometry: Polygon geometries in EPSG:4326
  • std_geoid: Standardized GEOID
  • FIPS component fields (state_fips, county_fips, tract_fips, bg_fips)

​
get_census_data_with_boundaries()

Get both Census demographic data and boundary files for block groups in a FIPS code. 
census_data, census_boundaries = service.get_census_data_with_boundaries(
    fips_code='06001',
    year=2022,
    census_settings=None
)
​
fips_code
str
required
5-digit FIPS code (state + county)
​
year
int
default:"2022"
Census year to query
​
census_settings
dict
default:"None"
Census settings object
​
return
Tuple[pd.DataFrame, gpd.GeoDataFrame]
Tuple containing:
  • Census demographic data DataFrame
  • Census Block Group boundaries GeoDataFrame (merged with demographic data)

​
Spatial Matching

​
match_to_census_blockgroups()

Match each row in a GeoDataFrame to its corresponding Census Block Group using spatial join. 
from openavmkit.utilities.census import match_to_census_blockgroups

enriched_gdf = match_to_census_blockgroups(
    gdf=parcels_gdf,
    census_gdf=census_boundaries,
    join_type='left'
)
​
gdf
gpd.GeoDataFrame
required
Input GeoDataFrame to match (must have a geometry column)
​
census_gdf
gpd.GeoDataFrame
required
Census Block Group boundaries GeoDataFrame
​
join_type
str
default:"'left'"
Type of join to perform: 'left', 'right', 'inner', or 'outer'
​
gdf
gpd.GeoDataFrame
Input GeoDataFrame with Census Block Group data appended, including:
  • std_geoid: Census block group ID
  • median_income: Median household income
  • total_population: Total population
  • Other demographic fields from the census data
Uses centroid-based matching in an equal-area projection for accuracy.

​
Initialization Functions

​
init_service_census()

Initialize a Census service with the provided credentials. 
from openavmkit.utilities.census import init_service_census, CensusCredentials

credentials = CensusCredentials(api_key='your_api_key')
service = init_service_census(credentials)
​
credentials
CensusCredentials
required
Census API credentials
​
service
CensusService
Initialized Census service

​
get_creds_from_env_census()

Get Census credentials from environment variables. 
from openavmkit.utilities.census import get_creds_from_env_census
import os

os.environ['CENSUS_API_KEY'] = 'your_api_key'
credentials = get_creds_from_env_census()
​
credentials
CensusCredentials
Census API credentials loaded from the CENSUS_API_KEY environment variable. Returns None with a warning if the environment variable is not set.

​
Usage Example

import os
from openavmkit.utilities.census import (
    get_creds_from_env_census,
    init_service_census,
    match_to_census_blockgroups
)

# Set up credentials
os.environ['CENSUS_API_KEY'] = 'your_census_api_key'
credentials = get_creds_from_env_census()
service = init_service_census(credentials)

# Get census data with boundaries
census_data, census_boundaries = service.get_census_data_with_boundaries(
    fips_code='06001',  # Alameda County, CA
    year=2022
)

# Match parcels to census block groups
enriched_parcels = match_to_census_blockgroups(
    gdf=parcels_gdf,
    census_gdf=census_boundaries,
    join_type='left'
)

print(f"Enriched with median income: {enriched_parcels['median_income'].notna().sum()} parcels")

Build docs developers (and LLMs) love

Get started for freeTalk to us