{"id":963,"date":"2013-01-20T11:05:28","date_gmt":"2013-01-20T17:05:28","guid":{"rendered":"http:\/\/www.mooreds.com\/wordpress\/?p=963"},"modified":"2013-01-22T22:26:12","modified_gmt":"2013-01-23T04:26:12","slug":"a-tutorial-for-the-census-data-api","status":"publish","type":"post","link":"https:\/\/www.mooreds.com\/wordpress\/archives\/963","title":{"rendered":"A tutorial for the Census Data API"},"content":{"rendered":"

I’ve been exploring APIs<\/a> ever since attending the hackathon at Gluecon<\/a> last year.\u00a0 Since I work for a real estate firm, I’m interested in APIs with a geographic component.\u00a0 I had heard that USA Today had APIs for census data.\u00a0 They do<\/a>.\u00a0 I also wondered if the census bureau had any APIs available.\u00a0 They do<\/a>.\u00a0 However, the USA Today APIs are much much friendlier.<\/p>\n

But the USA Today APIs have some limitations.\u00a0 Also, the data sets of these two APIs intersect, but neither is a subset of the other.\u00a0 So, I thought it’d be useful to have a quick start for the census data API.<\/p>\n

    \n
  1. First, register for an API key<\/a>.\u00a0 This only requires an email address and a name.\u00a0 The key got sent to my spam folder, so make sure you check that if you don’t see the email about five minutes after you submit.<\/li>\n
  2. Decide what type of information you want to find.\u00a0 There are two sets of information–the 2010 census summary file or thee American community survey<\/a> (for the last five orsix years).\u00a0 Since the ACS is not available in the USA Today\u00a0 API, that’s what I’ll explore, but the methodology is similar for the summary file.<\/li>\n
  3. The first place to look is the variables XML file showing you what data is available.\u00a0 Here is the ACS variables file for the most recent five years<\/a>, and here is the census summary variables file<\/a>.\u00a0 For a high level overview of what you can find, you’ll want to focus on the ‘concept’ tags.\u00a0 You’ll see names like “C24070.\u00a0 Industry by Class of Worker for the Civilian Employed Population 16 Years and Over” and “B24123.\u00a0 Detailed Occupation by Median Earnings for the Full-Time, Year-Round Civilian Employed Female Population 16 Yrs and Over”.\u00a0 While the Census has documents explaining what each of these mean, this website seems to have aggregated the metadata<\/a> that will let you explore the types of data available.<\/li>\n
  4. OK, you’ve found your interesting data.\u00a0 I’m going to look at the concept “B08126.\u00a0 MEANS OF TRANSPORTATION TO WORK BY INDUSTRY” for the rest of this example.\u00a0 You need to pick a variable from the concept, so I’ll pick B08126_003E\/Construction and some subsets: B08126_018E\/Car, truck, or van – drove alone, B08126_033E\/Car, truck, or van – carpooled, and B08126_048E\/Public transportation (excluding taxicab). As you see, you can request multiple variables at once.<\/li>\n
  5. Now you need to find the area that you want to look at.\u00a0 The census developer site has examples<\/a> which I found to be massively confusing when I first looked at them.\u00a0 What you need to do is decide what level of geography you want, and then find the appropriate code.\u00a0 Here are state codes<\/a>.\u00a0 If you want anything more detailed, you’ll probably want a FIPS code<\/a> which ranges from states to as small as the Census data is gathered. \u00a0Here’s a list of valid geographic delineations<\/a>.\u00a0 You may have the information if you are interested in a county, but if all you have is a lat\/lng (as if, say, you are looking at a property listing), you can look up the FIPS code<\/a>.\u00a0 If you need to get a lat\/lng for a city, I’d suggest google.<\/li>\n
  6. I’m going to look up Lafayette, CO, which google tells me is at 39.9936, -105.0892.\u00a0 So, the FIPS request looks like http:\/\/data.fcc.gov\/api\/block\/find?latitude=39.9936&longitude=-105.0892&showall=false&format=json and reveals that the FIPS code for this lat\/lng is 080130608005010.<\/li>\n
  7. A FIPS code is broken into sections.\u00a0 The first two numbers are the state, so 08 is Colorado’s code.\u00a0 The next three are the county, so 013 represents Boulder county.\u00a0 The next six are the tract code, so 060800 is the tract that we are looking at (tracts “provide a stable set of geographic units for the presentation of decennial census data”)<\/a>.\u00a0 You can see tracts on maps<\/a>, and our specific tract [pdf]<\/a>.\u00a0 After the tract comes the block, which is an even smaller subsection of homes.\u00a0 The block is 5010.\u00a0 Apparently FIPS codes are on their way out, in favor of GNIS codes<\/a>.\u00a0 I couldn’t find a lat\/lng to GNIS code service, however.<\/li>\n
  8. Now you know what area you are looking at.\u00a0 Rather than the county, I want to examine census data based on the tract I’ve found (good old tract 060800).<\/li>\n
  9. Next step is to build the URL for the API request.\u00a0 Here’s where the examples come in handy.\u00a0 For tract level data for the ACS, we look at this example<\/a>, and see the format of the call: http:\/\/api.census.gov\/data\/2011\/acs5?get=[the data code that you found above]&for=tract:[tract code or *]&in=state:[state code]+county:[county code]&key=[your key]<\/li>\n
  10. Therefore, my API request looks like http:\/\/api.census.gov\/data\/2011\/acs5?get=B08126_033E,B08126_018E,B08126_048E&for=tract:060800&in=state:08+county:013&key=… and I get something like this: [[“B08126_003E”,”B08126_033E”,”B08126_018E”,”B08126_048E”,”state”,”county”,”tract”],[“309″,”57″,”188″,”0″,”08″,”013″,”060800”]] stating that there are 309 construction jobs reported in this tract that answered the transportation question, and that no one took public transport, but more carpooled than drove alone.<\/li>\n<\/ol>\n

    Note that I ignored the margin of error fields, but they are there.\u00a0 Now you have the data, you can use something like d3.js<\/a> to display it.<\/p>\n

    Note that the TOS of the Census APIs don’t mention explicit limits but if you are planning to make a lot of calls, consider downloading the full dataset and using that instead.<\/p>\n

    Finally, you can sign up for the Census API developer forums<\/a>, though this seems to be more of a feature request forum and less of a technical help arena.\u00a0 And there doesn’t appear to be anonymous browsing of forums–you have to sign in to view anything.<\/p>\n

    Update 1\/22: From the developer forums comes the comment<\/a> that the forums are meant to be both technical support and feature requests.<\/strong><\/p>\n","protected":false},"excerpt":{"rendered":"

    I’ve been exploring APIs ever since attending the hackathon at Gluecon last year.\u00a0 Since I work for a real estate firm, I’m interested in APIs with a geographic component.\u00a0 I […]<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[62],"tags":[],"class_list":["post-963","post","type-post","status-publish","format-standard","hentry","category-apis"],"_links":{"self":[{"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/posts\/963","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/comments?post=963"}],"version-history":[{"count":5,"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/posts\/963\/revisions"}],"predecessor-version":[{"id":968,"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/posts\/963\/revisions\/968"}],"wp:attachment":[{"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/media?parent=963"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/categories?post=963"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.mooreds.com\/wordpress\/wp-json\/wp\/v2\/tags?post=963"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}