Access Data with Census APIs

Size: px

Start display at page:

Download "Access Data with Census APIs"

Cecily Fitzgerald
6 years ago
Views:

1 You are here: Census.gov APIs - US Census Bureau Access Data with Census APIs Census Bureau APIs To improve access to data and encourage innovation, the Census Bureau has begun to provide API access to some data sets, beginning with the 2010 Census Summary File 1 and the 2010 American Community Survey (five year data). We invite developers to use these APIs, join our Developer Forum, and provide feedback to help us move forward with continued API development. Please read the Terms of Service for using the API. Note on URL base: Please note the the URL of the API has changed to api.census.gov. The former URL will remain active until August 6 th [2012]. Please update your calls to reflect the new URL. Accessing Data Data are accessible to software developers through a stateless HTTP GET request. In order to access data, you will need to insert a key into the request URL in order for query results to be returned. If you do not have a key assigned to you, you will be directed to the Request a Key page where you can register for one. 1) Example of the request URL for 2010 Census SF1 data that has an assigned key inserted: ,NAME&for=state:* 2) Example of the request URL for ACS Year data for Total Population for California and New York: _001E,NAME&for=state:06,36 3) Example of the request URL for ACS Year data for Gross Rent as a Percentage of Household Income, 10.0 to 14.9 percent for all counties in CA: From August 2012

2 5070_003E,NAME&for=county:*&in=state:06 4) Example of the request URL for 2010 Census SF1 white population of 12 year olds in Alabama key]&get=pct012a015,pct012a119&for=state:01 Query Response The response for all queries is formatted as a two dimensional JSON array where the first row provides column names and subsequent rows provide data values. An example query response looks like this: [["P ","NAME","state"], ["710231","Alaska","02"], [" ","Alabama","01"], [" ","Arkansas","05"], [" ","Arizona","04"], [" ","California","06"], Each query response will include an HTTP status code. The table below lists the status codes and what they mean. HTTP Status Code Descriptions 200 Indicates success. The response body will contain a JSON array as described above. 204 Indicates the request succeeded but no records matched your query. 400 Indicates that the request was not valid. Examples include queries for unknown variables or unknown geographies. A message describing the error will be included in the response body. 500 Indicates that there was a server-side error while processing the request. Please wait a few minutes and try your query again. From August 2012

3 JavaScript While the API may be used from any language capable of issuing HTTP requests (Java, PHP, Perl, Python, C, etc.) two features that have been added to allow JavaScript to issue requests without violating same-origin security checks are CORS and JSONP. If you're writing a browser-based web application for modern web browsers with support for CORS then you may simply use an XMLHttpRequest as usual, without any changes. All HTTP responses generated by the API will include the necessary CORS headers. If you're writing a browser-based web application for legacy browsers without support for CORS then your request URL query string may include a jsonp argument. If present, this prefix will be wrapped around the response, allowing you to capture the result of the query. For example: jsonp=my_function_name. [Census API Release 1.0] From August 2012

4 Available Data Share on print Print More Sharing ServicesShare this page Connect with us The following data sets are currently available through the API 2010 Census Summary File 1 (SF1) Summary File 1 (SF 1) contains the data compiled from the questions asked of all people and about every housing unit. Population items include sex, age, race, Hispanic or Latino origin, household relationship, household type, household size, family type, family size, and group quarters. Housing items include occupancy status, vacancy status, and tenure (whether a housing unit is owner-occupied or renter-occupied). SF 1 includes population and housing characteristics for the total population, population totals for an extensive list of race (American Indian and Alaska Native tribes, Asian, and Native Hawaiian and Other Pacific Islander) and Hispanic or Latino groups, and population and housing characteristics for a limited list of race and Hispanic or Latino groups. Population and housing items may be cross-tabulated. Selected aggregates and medians also are provided. The API provides access to a majority of SF1 tables, but not all. SF1 includes population tables (identified with a ''P'') and housing tables (identified with an ''H'') shown down to various levels of geography. The call to the API for this data set is American Community Survey Year Data The American Community Survey (ACS) is an ongoing survey that provides data every year -- giving communities the current information they need to plan investments and services. The ACS covers a broad range of topics about social, economic, demographic, and housing characteristics of the U.S. population. Much of the ACS data provided on the Census Bureau's Web site are available separately by age group, race, Hispanic origin, and sex. The 5-year estimates from the ACS are "period" estimates that represent data collected over a period of time. The primary advantage of using multiyear estimates is the increased statistical reliability of the data for less populated areas and small population subgroups. The call to the API for this data set is ACS Web site Documentation, main/ From August 2012

5 Geography Every query must include a geography, and this API supports both FIPS and GNIS geography codes. To query the API your request URL query string must include a for argument which defines the geography level and FIPS code(s). For example: will find the total population for the state of California. The "for" argument may include additional FIPS codes, separated by a comma. For example: will find the total population for the states of California and Maryland. In some cases you must also include an in argument to fully qualify the geography. For example: in=state:06 will find the total population for Alameda County in the state of California. Geocoding The APIs accept calls using a geographic FIPS code. These codes are available recursively through the API but if you have an application that produces a geographic coordinate point, here are two ways you can convert that to a FIPS code. 1. See the TIGERWeb Mapping Web Service [ 2. Use the FCC's Census Block Conversions API [ More on Census Geography Geographic Area Concepts [PDF] [ Understanding Place in Census Bureau Products [PDF] [ From August 2012

Poverty Map This app from the Cornell Program on Applied Demographics uses the API to

6 App Gallery Age Finder This Census Bureau app uses the API to allow users to retrieve age statistics from SF1 for defined and custom age ranges. Poverty Map This app from the Cornell Program on Applied Demographics uses the API to map poverty statistics from the American Community Survey. From August 2012

7 Accessing Data Data are accessible to software developers through a stateless HTTP GET request. In order to access data, you will need to insert a key into the request URL in order for query results to be returned. If you do not have a key assigned to you, you will be directed to the Request a Key page where you can register for one. See the API website at o Here is an example of the request URL for 2010 Census SF1 data that has an assigned key inserted: o Here is an example of the request URL for ACS Year data for Total Population for California and New York: o Here is an example of the request URL for ACS Year data for Gross Rent as a Percentage of Household Income, 10.0 to 14.9 percent for all counties in CA: o 2010 Census SF1 white population of 12 year olds in Alabama key]&get=pct012a015,pct012a119&for=state:01

8 SF1 Examples and Supported Geographies 40 state state-county state-countycounty subdivision state-countycounty subdivisionsubminor civil subdivision state-countytract-block state-county-tract

9 150 state-countytract-block group state-place state-alaska native regional corporation state-american indian area/alaska native area/hawaiian home land state-american indian area-tribal subdivision 320 statemetropolitan statistical area/micropolitan statistical area

10 323 statemetropolitan statistical area/micropolitan statistical areametropolitan division 340 state-combined statistical area 500 statecongressional district 510 statecongressional district-county 511 statecongressional district-countytract 521 statecongressional district-county

11 county subdivision statecongressional district-place 550 statecongressional district-american indian area/alaska native area/hawaiian home land 560 statecongressional district-alaska native regional corporation 610 state-state legislative district (upper chamber)

12 620 state-state legislative district (lower chamber) 871 state-zip code tabulation area

13 ACS Examples and Supported Geography 10 us state state-county state-countycounty subdivision state-countycounty subdivisionsubminor civil subdivision state-countycounty subdivisionplace

14 80 state-countycounty subdivisionplace-tract 91 state-countycounty subdivisionplace-tractblock group state-countytract 150 state-countytract-block group state-place stateamerican indian area/alaska native

15 area/hawaiian home land stateamerican indian area/alaska native area (reservation or statistical entity only) statecongressional district

Using American FactFinder

Using American FactFinder John DeWitt Lisa Neidert Project Manager Data Services Social Science Data Analysis Network Population Studies Center What is American FactFinder? http://factfinder.census.gov