It’s probably clear by now that we here at Data Docs have a lot of love for AL/FRED, the vast web- and API-accessible economic data repository run by the St. Louis Fed.

It is fair to say, though, that we never loved all parts of AL/FRED equally; while the thoroughness, timeliness, and accuracy of its data have always been outstanding, the XML format in which that data was delivered was better suited suited to an earlier, less JavaScript-driven internet. It was a relatively small price to pay, but accessing AL/FRED API data in a JavaScript application meant always having to write the descriptive but tiresome (and verbose) getElementsByTagName() commands in your code in order to use the AL/FRED data. Always, that is, until a week ago Monday.
Data Docs is proud to be an early user of the AL/FRED API’s JSON format, which can be accessed by simply adding file_type=json to any API call.

Introducing JSON

So let’s say your original API call looks something like the below (for a complete guide to AL/FRED, see our previous blog post):

http://api.stlouisfed.org/fred/series/observations?series_id=PAYEMS
&observation_start=2013-01-01&units=chg&api_key=xxxxxxxxxxxxxxxxxx

Without the new file_type parameter, the above query will return the monthly non-farm payrolls figures from January, 2013 until the present in an XML format, with the first element describing the data you’ve asked for, and each of the next containing one month’s reading, like so:

<?xml version="1.0" encoding="utf-8" ?>
<observations realtime_start="2013-08-27" realtime_end="2013-08-27" 
observation_start="2013-01-01" observation_end="9999-12-31" units="chg"
output_type="1" file_type="xml"
order_by="observation_date" sort_order="asc"count="7" offset="0" limit="100000">

<observation realtime_start="2013-08-27" realtime_end="2013-08-27" 
date="2013-01-01" value="148"/>
.
.
.
<observation realtime_start="2013-08-27" realtime_end="2013-08-27"
date="2013-07-01" value="162"/>

</observations>

Just by adding the new file_type=json parameter and value anywhere in the original query, however, we get essentially the same data structure in a handy JSON format. So the query becomes:

http://api.stlouisfed.org/fred/series/observations?series_id=PAYEMS
&observation_start=2013-01-01&units=chg&file_type=json&api_key=xxxxxxxxxxxxxxxxxx

And the result becomes:

{
    "realtime_start": "2013-08-27",
    "realtime_end": "2013-08-27",
    "observation_start": "2013-01-01",
    "observation_end": "9999-12-31",
    "units": "chg",
    "output_type": 1,
    "file_type": "json",
    "order_by": "observation_date",
    "sort_order": "asc",
    "count": 7,
    "offset": 0,
    "limit": 100000,
    "observations": [
        {
            "realtime_start": "2013-08-27",
            "realtime_end": "2013-08-27",
            "date": "2013-01-01",
            "value": "148"
        },
.
.
.
        {
            "realtime_start": "2013-08-27",
            "realtime_end": "2013-08-27",
            "date": "2013-07-01",
            "value": "162"
        }
    ]
}

Curly Braces instead of Carrots – So What?

If you’re not a JavaScript developer, the difference between the two result sets above probably doesn’t seem that thrilling. Thanks to good formatting (hat tip to the essential JSON validation-and-reformat site, jsonlint.org), you might possibly have found the second result set a bit easier to read.

The big deal is that JSON (which not-coincidentally stands for JavaScript Object Notation) is infinitely easier for JavaScript to read, too, meaning programmers have to write less code in order to use data in this format.

So, for example, while using the observations from the XML-formatted results would mean writing out data.getElementsByTagName(“observations”), the same information can be accessed from the JSON format simply by writing data.observations. And as anyone who’s every texted “Trying 2 reach u” knows, saving even a handful of characters can really add up.