Skip to main content

A wrapper for the US Census Bureau's API

Project description

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

Provides access to ACS, SF1, and SF3 data sets.

Usage

First, get yourself a Census API key.

from census import Census
from us import states

c = Census("MY_API_KEY")
c.acs.get(('NAME', 'B25034_010E'), {'for': 'state:%s' % 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.acs.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.

The default year is 2011. To access 2010 data, pass a year parameter to the API call:

c.acs.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)

Datasets

  • ACS (2011, 2010)

  • SF1 (2010, 2000, 1990)

  • SF3 (2000, 1990)

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 helper methods provided here.

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

ACS Geometries

  • 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_district(fields, state_fips, district)

  • us(fields)

  • zipcode(fields, zip5)

SF1 Geometries

  • 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_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)

SF3 Geometries

  • state(fields, state_fips)

  • state_county(fields, state_fips, county_fips)

  • state_county_tract(fields, state_fips, county_fips, tract)

  • state_place(fields, state_fips, place)

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'

Examples

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

c.sf1.get('NAME', geo={'for': 'tract:*', 'in': 'state:%s county:170' % 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.acs.get('B01001_004E', {'for': 'state:*'})

The same call using the state convenience method:

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

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

census-0.5.tar.gz (5.6 kB view details)

Uploaded Source

File details

Details for the file census-0.5.tar.gz.

File metadata

  • Download URL: census-0.5.tar.gz
  • Upload date:
  • Size: 5.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for census-0.5.tar.gz
Algorithm Hash digest
SHA256 9738812dbe5d5d67c92556377ededbe31b19ca4315aff39294c38a9cbc31c920
MD5 5e59a6a89c46f406b80fcff7d8475847
BLAKE2b-256 fb0aa8872893bb4542fce5c3d26dd632f63d01aeb03ea7692739b9f877abd871

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