Access Data with Census APIs

 Print | Share this page | Connect with us

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 6th. 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:

  http://api.census.gov/data/2010/sf1?key=b48301d897146e8f8efd9bef3c6eb1fcb864cf&get=P0010001,NAME&for=state:*

2) Example of the request URL for ACS 2010 5 Year data for Total Population for California and New York:

  http://api.census.gov/data/2010/acs5?key=b48301d897146e8f8efd9bef3c6eb1fcb864cf&get=B02001_001E,NAME&for=state:06,36

3) Example of the request URL for ACS 2010 5 Year data for Gross Rent as a Percentage of Household Income, 10.0 to 14.9 percent for all counties in CA:

  http://api.census.gov/data/2010/acs5?key=b48301d897146e8f8efd9bef3c6eb1fcb864cf&get=B25070_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

  http://api.census.gov/data/2010/sf1?key=[user 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:

[["P0010001","NAME","state"],
["710231","Alaska","02"],
["4779736","Alabama","01"],
["2915918","Arkansas","05"],
["6392017","Arizona","04"],
["37253956","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.

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:

  http://api.census.gov/data/2010/sf1?key=...&get=P0010001,NAME&for=state:06& jsonp=MY_FUNCTION_NAME.

[Census API Release 1.0]

[PDF] or denotes a file in Adobe’s Portable Document Format. To view the file, you will need the Adobe® Reader® available free from Adobe.

This symbol indicates a link to a non-government web site. Our linking to these sites does not constitute an endorsement of any products, services or the information found on them. Once you link to another site you are subject to the policies of the new site.