• Stars
    star
    569
  • Rank 77,818 (Top 2 %)
  • Language
    Python
  • License
    BSD 3-Clause "New...
  • Created over 12 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Python wrapper for the US Census API.

census

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()

More Repositories

1

usaddress

🇺🇸 a python library for parsing unstructured United States address strings into address components
Python
1,451
star
2

parserator

🔖 A toolkit for making domain-specific probabilistic parsers
Python
777
star
3

probablepeople

👪 a python library for parsing unstructured western names into name components.
Python
564
star
4

data-making-guidelines

📘 Making Data, the DataMade Way
HTML
285
star
5

site-launch-checklist

☑️ A checklist of miscellaneous tasks to do before launching a public website.
124
star
6

how-to

📚 Doing all sorts of things, the DataMade way
Python
86
star
7

my-reps

👥 Enter your address to find your elected representatives. Powered by the Google Civic Information API
JavaScript
67
star
8

searchable-map-template-csv

🌎 You want to put your data on a searchable, filterable map. This is a free, open source template using Leaflet & Turf to help you do it.
JavaScript
53
star
9

census_area

🔷 Get Census Data from the API for arbitrary areas
Python
43
star
10

million-dollar-blocks

💰 An interactive visualization of incarceration spending in Chicago
JavaScript
43
star
11

nyc-councilmatic

🗽 a web app for keeping tabs on city council activity in New York City
Python
38
star
12

look-at-cook

Explore Cook County's budget from 1993 to 2017 and learn how the money is being spent.
JavaScript
36
star
13

data-analysis-guidelines

📒 Analyzing Data, the DataMade Way
Makefile
36
star
14

second-city-zoning

🏙 2nd City Zoning is an interactive map that lets you find out how your building is zoned, learn where to locate your business and explore zoning patterns throughout Chicago
HTML
29
star
15

django-councilmatic

💗 Django app providing core functions for *.councilmatic.org
Java
26
star
16

vacant-building-finder

Searchable map of Chicago vacant and abandoned buildings, built using open 311 data.
JavaScript
25
star
17

ny-budget

📊 an explorable budget vizualization for New York state
JavaScript
24
star
18

chi-councilmatic

👀 keep tabs on Chicago city council
Java
20
star
19

searchable-map-template-carto

🌎 You want to put your data on a searchable, filterable map. This is a free, open source template using CARTO to help you do it.
JavaScript
19
star
20

dossier

Machine assisted dossiers
TeX
18
star
21

lascaux

🌐 Web API for printing high resolution PDF maps
Python
17
star
22

councilmatic-starter-template

📋 Starter code & documentation for new councilmatic instances
Python
16
star
23

code-challenge

A code challenge to recreate the address parsing form in DataMade's Parserator app.
Python
15
star
24

testing-guidelines

📕 Writing tests, the DataMade way
14
star
25

django-proxy-overrides

Python
12
star
26

pdf-textextract

Docker Container for a Make-based, PDF extraction using OCR
Python
10
star
27

school-report-cards

Tools for parsing annual school report card data from the state of Illinois
Makefile
10
star
28

mecharat

🐀 Robot Assisted Transcriptions
Python
10
star
29

readme-template

📖 A template for documenting your code.
10
star
30

scrapers-us-municipal

Scrapers for US municipal governments.
Python
10
star
31

probation-resources-map

Interactive, searchable map that helps people on probation find social, health, and cultural resources throughout Chicago
JavaScript
10
star
32

open-ee-meter

Data analysis & visualization of energy savings projects, to ultimately empower utilities and contractors to improve the efficacy of energy savings programs.
Python
9
star
33

flask_app_template

Generic Flask app template with basic database setup and user login
HTML
8
star
34

bankers-hours

Python decorators that only let a function or method run within specified times
Python
8
star
35

govinfo

Scrapes Congressional Hearings from the govinfo API
Python
8
star
36

repo-roundup

📝 python script that pulls a list of organization repos from the GitHub API into a CSV
Python
7
star
37

nyc-council-councilmatic

NYC Council version of Councilmatic
Python
7
star
38

clearstreets-processing

Converts GPX files to OSM (Open Street Map) and snaps lines to city street grid
Python
7
star
39

jekyll-html-hook

⚓ Webhook listener for deploying Jekyll or static HTML sites
Python
7
star
40

just-spaces

🏕 A tool from University City District and DataMade to promote better and more just public spaces
JavaScript
7
star
41

bigeasy-budget

📈 Budget visualization for the City of New Orleans. Based on Look at Cook.
JavaScript
6
star
42

la-metro-councilmatic

🚇 An instance of councilmatic for LA Metro
Python
6
star
43

clearstreets-web

Website that tracks where Chicago plows have been during a snowstorm.
JavaScript
6
star
44

chicago-municipal-elections

Chicago Municipal Elections
Python
6
star
45

django-geomultiplechoice

🗺 A Django widget to select multiple geographic areas
Python
5
star
46

leaflet-searchable-map-template

JavaScript
5
star
47

ward-demographics

Census Demographics of Chicago's Wards
Python
5
star
48

chicago-council-scrapers

Repo for running Chicago City Council Scrapers
Python
5
star
49

occrp-timeline-tool

Help reporters organize and analyze data about sequential events and related data
Python
5
star
50

school-boundary-merge

Scripts and source data to create one file with all the attendance boundaries for all public schools in Chicago
Python
4
star
51

arrests

Chicago Police Arrests
Python
4
star
52

eitc-map

Earned Income Tax Credit Map for Voices for Illinois Children
JavaScript
4
star
53

probableparsing

Common methods for probable parsers
Python
4
star
54

look-at-washington

Budget transparency site for the State of Washington
JavaScript
4
star
55

justice-divided

⚖ Youth of all races break the law. Youth of color are more likely to be punished.
JavaScript
4
star
56

bga-payroll

💰 How much do your public officials make?
JavaScript
4
star
57

la-metro-dashboard

An Airflow-based dashboard for LA Metro
Python
3
star
58

schema_matching

Notes for schema matching
TeX
3
star
59

chicago-lots

Explore City-owned lots in Chicago
JavaScript
3
star
60

where-we-work

visualizing Chicago employment data
JavaScript
3
star
61

process-mining-toolkits

Evaluating Process Mining Toolkits
Makefile
3
star
62

openness-project-nmid

The Openness Project - New Mexico In Depth Campaign Finance Explorer
Python
3
star
63

where-we-work-api

💼 Scripts and API to process and analyze LODES data for where-we-work
Python
3
star
64

macoupin-budget

📊 Budget visualization for Macoupin County, IL. Based on Look at Cook
JavaScript
3
star
65

my-reps-pbp

Look up who represents you at various levels of government.
JavaScript
3
star
66

illinois-criminal-justice

Data extractions tools from Illinois State Reports on the Criminal Justice System
Makefile
3
star
67

mote-0-bike

A bicycle-based sensing and data gathering project, intended to better map the urban environment as it is experienced by the bicyclist and pedestrian. GFRY design objects studio project by Colin Hutton
JavaScript
3
star
68

chicago-elections

API for local chicago election
Python
2
star
69

court-scrapers

Python
2
star
70

chicago-newsarticles

Python
2
star
71

chicago-openelex

Chicago Open Election Scraper
Python
2
star
72

wopr-data

Deprecated: Scripts for creating and updating datasets for plenario
Python
2
star
73

python-chicago-elections

Python Scraper for Chicago Elections
HTML
2
star
74

opmaalinger

Completed development projects in Denmark
JavaScript
2
star
75

alderman-factors

Estimating the poltical structure of the Chicago council from campaign contributions
JavaScript
2
star
76

ipeds-db

Build a Postgres DB from IPEDS Access files
Makefile
2
star
77

django-pldp

Reusable Django app that implements data models for PLDP
Python
2
star
78

disasters

Data on the current and forecasted conditions for storms, flooding, earthquakes, fires, and other disasters
2
star
79

million-dollar-blocks-analysis

public repo with analysis for the Chicago million dollar blocks project
Python
2
star
80

car-scraper

💲Make spreadsheets out of Chicago Association of REALTORS® reports
Python
2
star
81

ihs-price-index

Price Index Visualization for The DePaul Institute for Housing Studies
JavaScript
2
star
82

how-to-recharts

A learning repo for setting up Recharts with Gatsby
CSS
2
star
83

illinois-ucr

Tools for working with Illinois crime reports.
Python
2
star
84

semabot

Whomping up a webhook for notifications for semaphor
Python
2
star
85

bravest-map-ever

Searchable map highlighting places that inspire, and encourage bravery and kindness in your community for the Born This Way Foundation.
JavaScript
2
star
86

bga-pensions

🏦 Funding public-employee pension systems is perhaps the most vexing emergency facing Illinois taxpayers. @bettergov hopes to bring clarity to this important topic by gathering and centralizing data from the largest public pension systems in the state.
CSS
2
star
87

sra

Mirror of Security Risk Assessment Tool from HHS
HTML
2
star
88

coordinated-entry-screening

A pre-screening tool for Coordinated Entry Access for the Corporation for Supportive Housing (CSH)
Python
2
star
89

cps-data

Repository of data on the Chicago Public Schools and District, complement to https://github.com/datamade/school-report-cards
Makefile
1
star
90

gary-counts-hhmap

Map of the Hardest Hit properties in the City of Gary, IN
CSS
1
star
91

large-lots-staging

Staging site for LargeLots.org
JavaScript
1
star
92

property-image-cache

🏠 A Flask app to cache images from the Cook County Property info site
Python
1
star
93

django-councilmatic-notifications

Notifications app for Django Councilmatic
Python
1
star
94

where-to-drink

Where can I get a drink around here?
Makefile
1
star
95

legistar-people

Using the legistar-scraper to get a list of elected officials
Python
1
star
96

govqa-py

Python
1
star
97

plats

Federal Township Plat Map for Cook County
Makefile
1
star
98

nwss-data-standard

💧 A marshmallow schema for the National Wastewater Surveillance System
Python
1
star
99

static-app-template

A template for creating static apps with Gatsby.
1
star
100

990-db

ETL for IRS 990 Filings on AWS
Makefile
1
star