Examples: Simple API

examples/simple_api

live demo

The simple api DataDocs example shows how you can use the data returned by an application programming interface (API) call in your DataDocs video. The trick here is to make sure that you create one (or more) empty <div> tags in your HTML file either by writing them directly into the "overlays" div as you would in the simple text example, but leave them empty. Alternatively, you can add the necessary <div> tags with JavaScript or jQuery, as we have in this example.

Once the empty div has been added to your "overlays" div, you will call data_doc.addSalt as usual, followed by a $.get request for the JSON file that has your data. It is then up to you to write a callback function that extracts the data you want from the JSON file and adds it to the <div> tag of your choice.

Note: Due to browser security restrictions, it is generally not possible to load data directly from an API into your DataDoc. In order to include data in your DataDoc that updates itself regularly, you will have to set up what is known as a "cron" job on your server. For an overview of setting up cron jobs, see the code box below.

A "cron" (as in "chronic") job is a script that lives on a web server and runs at specified intervals. It is often used to 
retrieve and save copies of API data on your own domain; this lets your web pages (and DataDocs!) 
load this data while avoiding cross-domain browser security restrictions and also generally prevents your 
applications from being rate-limited (i.e. blocked) by your data provider for calling the API too frequently.

For specifics on how to set up a cron job on your server, you'll need to consult your web hosting
provider, both to make sure that your account supports curl scripts (a common method of retrieving data
from other domains) and on how activate and/or use them with your particular provider. 

In general, you can set up a cron job by doing a variation of the following: ssh into your hosting account,
and then type "crontab -e" and hit enter. The beginning of any cron job specifies the when the script runs using 
the following 5 parameters, as follows (an asterisk means run the script on every one of that interval):

    minute: 0-59
    hour: 0-23
    day of month: 1-31
    month: 1-12
    day of week: 0-7 (0 and 7 both Sunday)

So, for example, a crontab line that begins with 

    0,15,30,45 12 * * * 

Would run the script on that line at 12, 12:15, 12:30, & 12:45 every day of every month all year long. 

After you've specified the frequency, you'll write something like 
    curl /usr/bin/curl -o ~outputfilePath/outputfileName.json http://applicationProgrammingInterfaceCallHere

In the above command, "curl /usr/bin/curl" is the curl command, plus the path that our particular hosting
provider requires that we use for curl itself. the "-o" parameter specifies that the name of the output file
will be different than that of the URL being called. The "~outputfilePath/outputfileName.json" parameter specifies where the 
copied data should be saved, and with what name. Finally the "http://applicationProgrammingInterfaceCallHere" 
is the actual URL from which you want to copy the data.

As an example, here's an example of what one of the DataDocs prototype curl commands looks like: 

    * 8,9 * * 5 /usr/bin/curl -o ~/datadocs.org/prototype/dataFiles/MonthlyJobsChanges.json http://api.stlouisfed.org/fred/series/observations?series_id=PAYEMS&observation_start=2010-10-01&units=chg&api_key=XXXXXX&file_type=json

The above command specifies that the script should run every minute in the hours of 8am and 9am on every Friday of the year,
and save as the file datadocs.org/prototype/dataFiles/MonthlyJobsChanges.json the data that copied from
http://api.stlouisfed.org/fred/series/observations?series_id=PAYEMS&observation_start=2010-10-01&units=chg&api_key=XXXXXX&file_type=json.
Note that this example won't work in your browser directly becausewe have scrubbed out our API key. 
But the folks at FRED would be happy to give you your own for free!

To add API data to your DataDoc, do the following:

1. Make sure you have a copy of your desired data in your assets/dataFiles folder. Open up your main.js file and add one or more <div> tags to your "overlays" div via JavaScript or jQuery, duplicating and modifying the example code as necessary. Alternatively, you can simply add <div> tags directly inside the "overlays" div in the dd_simple_api.html file.

2. As in the simple text example, modify the data_doc.addSalt call(s) in main.js to target your specific <div> tags.

3. Modify the $.get function call to point to your own data file and specify the name of your callback function. It is up to you to write a callback function that pulls the necessary information from your data file and adds it to your target <div> using either JavaScript or jQuery.

4. Open up dd_simple_api.html on your computer in FireFox and check out your new data-driven video!