U.S. Department of Commerce

Access Data with the Census API

The Census Bureau API

To improve access to data and encourage innovation, the Census Bureau has begun to provide API access to some data sets. 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.

Now available: The Economic Indicators Time Series Database - see details

The Economic Indicator Database is now available via the API. This database includes statistics, primarily at the national level, for measuring key sectors of the U.S. economy.

Discovery Tool (in Beta)

http://api.census.gov/data.json

The machine-readable dataset discovery service is now available in beta release. The http://api.census.gov/data.json URI produces a JSON document describing all available datasets. The content of this JSON document is based largely on the Open Project Data Common Core Metadata Schema, and extended to include metadata specific to Census Bureau datasets. The http://api.census.gov/data.xml URI may be used to access the same information as XML.

In addition to the above URIs dataset discovery is available for the entire vintage/dataset hierarchy as well. For example, the http://api.census.gov/data/2010.json and http://api.census.gov/data/2010.xml URIs may be used to discover all datasets within the 2010 vintage.

The Open Project Data Common Core Metadata Schema Link to a non-federal Web site documentation is a good starting point for understanding the fields output by the discovery service. We will soon release our own documentation which includes information about Census specific fields.

This is a beta release. We'd like to hear what you think about our new dataset discovery service. Based on your feedback, and the feedback of others, we may make some changes. At some point down the line -- once we're confident that the kinks are worked out -- we'll announce that the discovery API is out of beta.

Happy discovering!

Accessing Data

Data are accessible to software developers through a stateless HTTP GET request. Up to 50 variables can be requested with a single API call. 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 2011 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/2011/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 PDF denotes a file in Adobe’s Portable Document Format. To view the file, you will need the Adobe® Reader® Off Site available free from Adobe.
This symbol Off Site 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.
Source: U.S. Census Bureau | ADCOM/IT | | Last Revised: February 24, 2014