A simple wrapper for the United States Census Bureau’s API.
Provides access to ACS, SF1, and SF3 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.
The default year is 2016. 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)
Datasets
acs5: ACS 5 Year Estimates (2016, 2015, 2014, 2013, 2012, 2011, 2010)
acs1dp: ACS 1 Year Estimates, Data Profiles (2016, 2015, 2014, 2013, 2012)
sf1: Census Summary File 1 (2010, 2000, 1990)
sf3: Census Summary File 3 (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 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)
zipcode(fields, 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)
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'
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()
2 maintainers
Metadata
2 maintainers
Release files for census 0.8.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| census-0.8.8.tar.gz | 9.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| census-0.8.8-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details |
Total release size: 19.3 kB
Release files / census-0.8.8.tar.gz
| Download URL | census-0.8.8.tar.gz |
|---|---|
| Size | 9.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5ffc5b5d29124c68bb194e3dba367d37b85a9bac595c2a2f28f212da5561e481
|
|
BLAKE2b-256 checksum How to use checksums |
a80167aedf07ccf1fa9b4545bc526e6cb984bf46e664b3ea17c2bc55eeaa4245
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/1.12.1 pkginfo/1.4.2 requests/2.20.1 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.6.3
|
Release files / census-0.8.8-py2.py3-none-any.whl
| Download URL | census-0.8.8-py2.py3-none-any.whl |
|---|---|
| Size | 9.9 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
0b8c915774a1d130930ba3a8c68f8d6a89a0295f8fb2630b927acf2cd6bd241c
|
|
BLAKE2b-256 checksum How to use checksums |
d749aae168aede6e2d111d72e13395c189f65f5e06b98ce5cd9989416f9c5f42
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/1.12.1 pkginfo/1.4.2 requests/2.20.1 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.28.1 CPython/3.6.3
|
