Skip to main content

A wrapper for the US Census Bureau's API

Project description

https://github.com/datamade/census/workflows/Python%20package/badge.svg

A simple wrapper for the United States Census Bureau’s API.

Provides access to ACS and SF1 data sets.

Install

pip install census

You may also want to install a complementary library, us, which help you figure out the FIPS codes for many geographies. We use it in the examples below.

pip install us

Usage

First, get yourself a Census API key.

from census import Census
from us import states

c = Census("MY_API_KEY")
c.acs5.get(('NAME', 'B25034_010E'),
          {'for': 'state:{}'.format(states.MD.fips)})

The call above will return the name of the geographic area and the number of homes that were built before 1939 for the state of Maryland. Helper methods have been created to simplify common geometry calls:

c.acs5.state(('NAME', 'B25034_010E'), states.MD.fips)

Full details on geometries and the states module can be found below.

The get method is the core data access method on both the ACS and SF1 data sets. The first parameter is either a single string column or a tuple of columns. The second parameter is a geoemtry dict with a for key and on option in key. The for argument accepts a “*” wildcard character or Census.ALL. The wildcard is not valid for the in parameter.

By default, the year for a dataset is the most recent year available. To access earlier data, pass a year parameter to the API call:

c.acs5.state(('NAME', 'B25034_010E'), states.MD.fips, year=2010)

The default year may also be set client-wide:

c = Census("MY_API_KEY", year=2010)

Detailed information about the API can be found at the Census Data API User Guide.

Datasets

For each dataset, the first year listed is the default.

Geographies

The API supports a wide range of geographic regions. The specification of these can be quite complicated so a number of convenience methods are provided. Refer to the Census API documentation for more geographies beyond the convenience methods.

Not all geographies are supported in all years. Calling a convenience method with a year that is not supported will raise census.UnsupportedYearException.

Geographic relationship files are provided on the Census developer site as a tool to help users compare the geographies from the 1990, 2000 and 2010 Censuses. From these files, data users may determine how geographies from one Census relate to those from the prior Census.

ACS5 Geographies

  • state(fields, state_fips)

  • state_county(fields, state_fips, county_fips)

  • state_county_blockgroup(fields, state_fips, county_fips, blockgroup)

  • state_county_subdivision(fields, state_fips, county_fips, subdiv_fips)

  • state_county_tract(fields, state_fips, county_fips, tract)

  • state_place(fields, state_fips, place)

  • state_congressional_district(fields, state_fips, congressional_district)

  • state_legislative_district_upper(fields, state_fips, legislative_district)

  • state_legislative_district_lower(fields, state_fips, legislative_district)

  • us(fields)

  • state_zipcode(fields, state_fips, zip5)

ACS1 Geographies

  • state(fields, state_fips)

  • state_congressional_district(fields, state_fips, district)

  • us(fields)

SF1 Geographies

  • state(fields, state_fips)

  • state_county(fields, state_fips, county_fips)

  • state_county_subdivision(fields, state_fips, county_fips, subdiv_fips)

  • state_county_tract(fields, state_fips, county_fips, tract)

  • state_place(fields, state_fips, place)

  • state_congressional_district(fields, state_fips, district)

  • state_msa(fields, state_fips, msa)

  • state_csa(fields, state_fips, csa)

  • state_district_place(fields, state_fips, district, place)

  • state_zipcode(fields, state_fips, zip5)

PL Geographies

  • state(fields, state_fips)

  • state_county(fields, state_fips, county_fips)

  • state_county_subdivision(fields, state_fips, county_fips, subdiv_fips)

  • state_county_tract(fields, state_fips, county_fips, tract)

  • state_county_blockgroup(fields, state_fips, county_fips, blockgroup)

  • state_place(fields, state_fips, place)

  • state_congressional_district(fields, state_fips, district)

  • state_legislative_district_upper(fields, state_fips, legislative_district)

  • state_legislative_district_lower(fields, state_fips, legislative_district)

States

This package previously had a census.states module, but now uses the us package.

>>> from us import states
>>> print states.MD.fips
u'24'

Convert FIPS to state abbreviation using lookup():

>>> print states.lookup('24').abbr
u'MD'

BYOS - Bring Your Own Session

If you’d prefer to use a custom configured requests.Session, you can pass it to the Census constructor:

s = requests.session()
s.headers.update({'User-Agent': 'census-demo/0.0'})

c = Census("MY_API_KEY", session=s)

You can also replace the session used by a specific data set:

c.sf1.session = s

Examples

The geographic name for all census tracts for county 170 in Alaska:

c.sf1.get('NAME', geo={'for': 'tract:*',
                       'in': 'state:{} county:170'.format(states.AK.fips)})

The same call using the state_county_tract convenience method:

c.sf1.state_county_tract('NAME', states.AK.fips, '170', Census.ALL)

Total number of males age 5 - 9 for all states:

c.acs5.get('B01001_004E', {'for': 'state:*'})

The same call using the state convenience method:

c.acs5.state('B01001_004E', Census.ALL)

Don’t know the list of tables in a survey, try this:

c.acs5.tables()

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sdcensus-0.8.20.tar.gz (13.0 kB view details)

Uploaded Source

Built Distribution

sdcensus-0.8.20-py3-none-any.whl (11.3 kB view details)

Uploaded Python 3

File details

Details for the file sdcensus-0.8.20.tar.gz.

File metadata

  • Download URL: sdcensus-0.8.20.tar.gz
  • Upload date:
  • Size: 13.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.3

File hashes

Hashes for sdcensus-0.8.20.tar.gz
Algorithm Hash digest
SHA256 d43bb56d586b3bce71428ceb5602585174c602d7d78ee1b3e0930415d3b67d77
MD5 9e2c3c178eef14353c595490ee61527c
BLAKE2b-256 5ccc99fe6840a9cecfc8fa5b62f0deb5030d895e2e1bbbad6d74b4ca15c1f2fa

See more details on using hashes here.

File details

Details for the file sdcensus-0.8.20-py3-none-any.whl.

File metadata

  • Download URL: sdcensus-0.8.20-py3-none-any.whl
  • Upload date:
  • Size: 11.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.11.3

File hashes

Hashes for sdcensus-0.8.20-py3-none-any.whl
Algorithm Hash digest
SHA256 dfabe2d83e9a7b494936cd31795a11de7b59fe12ae19b4b950d8cf5f6b418459
MD5 4454c1331a485201ee2351a37bd4382b
BLAKE2b-256 daf63301ff9d23ac6ab0e166e4383e28ce3e9e01e66a82da702f88ab4c9e31a0

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page