Census Data

This page covers the use of the census reporter API to obtain census data: https://github.com/censusreporter/censusreporter

Note that the Census Map page also contains some similar information, but focuses on drawing maps with the resulting data. This page focuses specifically on the API and extracting data from the API.

Overview

Let's start with what we're obtaining from the API and what we need to draw a map.

The census API provides a gateway to census data, which is essentially a very large number of tables of data (the columns), broken down into components and sub-components, for hundreds of thousands of geographical entities (the rows). We can think of each piece of data about a particular location as a cell in a giant spreadsheet.

Both the data and the geographical entities are organized hierarchically. For example, a single table about poverty might have poverty statics broken down by demographics or education level, resulting in several dozen columns. The geographical entities are likewise organized in a hierarchy including the country, states, counties, and census tracts.

Geographical Information: References

Starting with some references:

The Census Reporter Geography page (https://censusreporter.org/topics/geography/) contains a list of codes for geographical hierarchies:

• 010 - United States
• 040 - States
• 050 - Counties
• 140 - Census tracts
• 310 - Metropolitan and micropolitan areas (cities)
• 500 - Congressional district
• 860 - Zip codes

The Missouri Census Data Center's Geography page has a much more extensive overview of codes (https://factfinder.census.gov/help/en/summary_level_code_list.htm) and hierarchies (http://mcdc.missouri.edu/geography/sumlevs/index.shtml), including congressional districts

The official census documentation contains a page on geographic terms and concepts: https://www.census.gov/geo/reference/gtc/gtc_cousub.html

Geographical Information: API

Provide Parent, Get Children

This section covers how to provide a geographical entity at one level of the hierarchy and receive a set of children geographical entities at another level of the hierarchy.

When we call the geo API, we have a lot of ways to obtain information. We must specify the following:

• What geographical hierarchy level do we want information about? (The final results will be aggregated by this hierarchy type)
• What geographical entity ID are we passing in? (We have to specify some entity with some ID to limit the results, so we decide what geographical hierarchy level)
• The specific ID of the geographical entity

The base API call looks like this:

http://api.censusreporter.org/1.0/geo/show/tiger2013?geo_ids=<level to return>|<level of geoid>00US<geoid>

Here is an example where we request geographical information about county-level boundaries. To limit the results, we specify that we will provide a geogrpahical entity that is a metropolitan-area code (310), then we provide the geoid of that entity (41860, corresponding to San Francisco)

http://api.censusreporter.org/1.0/geo/show/tiger2013?geo_ids=050|31000US41860
                                                             ^^^
                                                             050 return county level information

                                                                 ^^^
                                                                 310 use metro geoid that will be passed
                                                                     ^^ ^^ 
                                                                     00 US
                                                                         ^^^^^
                                                                         41860 your city metro ID (SF, in this case)

Provide/Receive Single Entity

If we wish to provide a single geographical entity and get its boundaries, we can do that by providing two pieces of information:

• Geographical hierarchy level of entity you will specify
• GeoID of entity you are specify

Then call the base API as follows:

curl "http://api.censusreporter.org/1.0/geo/tiger2016/<hierarchy level>000US<geoid>?geom=True

For example, to get a geojson file containing the boundaries of Yuma County, you can call the API as follows:

curl "http://api.censusreporter.org/1.0/geo/tiger2016/05000US04027?geom=True" > yuma.geojson