Fork me on GitHub
Loading...

JSON Data API

All data used by this application is retrieved via JSON from a server which you can use for your own applications. If you know the GeoID for a census geography of interest, it is easy to retrieve the data. If all of this seems kind of complicated, you may prefer to start with the documentation for our javascript library which hides some of these details.

What's a GeoID?

For every distinct geography in a census summary level, it is possible to construct a unique identifier. These identifiers can be found in TIGER shapefiles and can also be looked up for a given latitude/longitude using our experimental Boundary Location API..

What do I do with the GeoID I have?

For any GeoID, it is very simple to create a URL with which you can retrieve a bundle of census data:

http://censusdata.ire.org/SS/GEOID.jsonp
with the following substitutions:

SS
The two-digit State FIPS code
GEOID
The two-to-eleven-digit GEOID.

What's with this JSONP?

(A full explanation of the "same origin" security policy used by most web browsers is outside the scope of this document. Consult the Wikipedia entry on JSONP for more information.)

When javascript in a web browser wants to retrieve JSON-formatted data from a site other than the one which served the original page, JSONP must be used. Commonly, web data APIs allow users to specify whether they want data in JSON or JSONP.

Because census data does not change once it is released, we have chosen to architect this "API" as a series of static files rather than generating responses dynamically upon request. This means that we can not selectively return either JSON or JSONP: we have to choose one. Because the primary use case for the JSON data is web browsers, and because it's trivial to strip the JSONP padding in most programming languages, we've created the static files as JSONP.

What does that mean for me if I'm trying to use the data in a web browser?

Begin by selecting a modern JavaScript toolkit which has built-in handling for JSONP. One of those, jQuery, is used to build this site. Then, know that when using JSONP, a callback function name must be specified. Usually with jQuery, developers are advised to not explicitly set the JSONP callback, or to set it to "?", which is a special value which lets jQuery know that it should randomly select a callback, and should coordinate with the remote server to use that callback. However, with our static-file API, the remote server cannot dynamically change the callback to a unique value. Instead, each file you will retrieve has a well-defined callback which you must give to jQuery as part of setting up the data connection.

Here's a basic example using jQuery. It is assumed that the jQuery library has already been loaded.
        function alert_handler(sf1) {
            alert("The 2010 population of "+ sf1['metadata']['NAME'] + " was " + sf1['data']['2010']['P1']['P001001'] + ".");
        }
        function fetch_data(geoid, success_handler) {
            callback = 'geoid_' + geoid;
            url = 'http://censusdata.ire.org/' + geoid.substr(0,2) + '/' + geoid + '.jsonp';
            console.log('calling: ' + url);
            $.ajax(url, {
                dataType: "jsonp",
                jsonpCallback: callback,
                success: success_handler
            });
        }
        fetch_data('1571550',alert_handler);
    

If the code above is included in a page, then when the data is loaded, a simple alert pop-up will appear indicating the total population for the Urban Honolulu CDP (Census Designated Place)

The beginnings of a javascript library which encapsulates this and other basic data access can be found at the IRE Census GitHub repository. The code there is fully usable, but has minimal documentation. Feel free to fork it and improve it!

What does JSONP mean for me if I'm trying to use the data in a non-JavaScript programming language?

First, consider whether the JSON API is right for you in the first place. In most cases, we guess that you might actually prefer our bulk data in CSV format.

Next, note that for web-efficiency, data on the server is gzip-encoded. Most browsers decode this automatically, but many http client libraries do not.

If you're sure you want to use our JSON data, it should be pretty simple to strip the javascript function call from the string which is returned from the URL call. Here's a basic example in Python:

        import json, gzip
        from StringIO import StringIO
        from urllib2 import urlopen
        def fetch_sf1_data(geoid):
            url = 'http://censusdata.ire.org/%s/%s.jsonp' % (geoid[:2],geoid)
            gzdata = StringIO(urlopen(url).read())
            gzfile = gzip.GzipFile(fileobj=gzdata,mode='rb')
            data_str = gzfile.read()
            paren_idx = data_str.find('(')
            data_str = data_str[paren_idx+1:-1]
            return json.loads(data_str)

        sf1 = fetch_sf1_data('1571550')
        print "The 2010 population of %s was %s." % (sf1['metadata']['NAME'],sf1['data']['2010']['P1']['P001001'])
    

What about metadata?

In addition to the data, there are two other data sources available.

http://censusdata.ire.org/SF1_labels.jsonp

A structure which can be used to look up human readable labels for the table and field codes which are in the geodata. The JSONP callback for this data is labels_SF1

http://censusdata.ire.org/states.jsonp

A list of the states for which SF1 data is currently available. The list is the name of each state. You must convert the name to a FIPS code through some other means. The JSONP callback for this data is states.