Connects to the Census API. It has been tested with the ACS and Economic Survey endpoints.



The API requires a key that you can get here (click on the box that says “Request a KEY”)


To instantiate the Census class, either store your CENSUS_API_KEY as an environment variable or pass it as an argument:

from parsons import Census

# First approach: Use API key environment variables

# In Mac OS, for example, set your environment variables like so:

census = ActBlue()

# Second approach: Pass API key as arguments
actblue = ActBlue(api_key = 'MY_CENSUS_KEY')

Example 1

from parsons import Census
# year, dataset_acronym, variables and location tell the API what data we want
# for example, 'B01001_001E' is population and 'us:1' is the entire U.S.
year = '2019'
dataset_acronym = '/acs/acs1'
variables = 'NAME,B01001_001E'
location = 'us:1'

# here's our connector
census = Census(api_key=acs_key)

# now pull data into a Parsons table
t = census.get_census(year, dataset_acronym, variables, location)

This example pulls the population of the US in 2019 from the ACS 1-year estimates.

Example 2

year = '2017'
dataset_acronym = '/ecnbasic'
location = 'state:51'
census = Census(api_key=acs_key)

t = census.get_census(year, dataset_acronym, variables, location)

This example pulls data on payroll by industry in Virginia from the 2017 Economic Census.


class parsons.Census(api_key=None)[source]

Class that creates a connector to the Census Bureau API

get_census(year=None, dataset_acronym=None, variables=None, location=None)[source]
Pull census data. For background check out the `Census API Guide


year: 4-digit string or integer

e.g. ‘2019’ or 2019

dataset_acronym: string with dataset name

e.g. ‘/acs/acs1’

variables: comma-separated string with variable names

e.g. ‘NAME,B01001_001E’

location: string with desired locations

e.g. ‘us:*


Parsons table with data