API Tutorial

The HiSPARC API (Application Programming Interface) simplifies metadata access from other applications. In this tutorial, we’ll give some examples of how this data can be accessed and used with Javascript (jQuery) and Python. We’ll show you how to do some neat things. How can you get a list of all HiSPARC stations in Denmark? What is the position of station 201? Which stations had data on 20 October 2010? How does the number of measured events change during a few weeks? This tutorial will give you an overview of some of possibilities with the HiSPARC API. For details on all available classes and methods, please see the API Reference.

Note

We’ll require you to know some basic programming, i.e. to understand what an if statement is and for loop does. If you are new to coding you can try a tutorial online, for instance Codeacademy, we recommend learning Python or jQuery.

First look

First we will just look at what this API is. The API can be accessed via the internet by opening urls. Instead of a website you get data as a response. This data is formatted as a JSON (JavaScript Object Notation), this format can be understood by many programming languages.

To see what options the API has we will look at it in a browser. Open the following link in your browser (this will not work in Internet Explorer): http://data.hisparc.nl/api/.

You should now see some text, like this:

{"base_url": "http://data.hisparc.nl/api/",
 "clusters": "clusters/",
 "clusters_in_country": "countries/{country_id}/",
 "configuration": "station/{station_id}/config/{year}/{month}/{day}/",
 "countries": "countries/",
 "has_data": "station/{station_id}/data/{year}/{month}/{day}/",
 ...
 "subclusters_in_cluster": "clusters/{cluster_id}/"}

This is the JSON, it is a dictionary (indicated by the { and } enclosing brackets): an object which has keys and values. Each key ("clusters", "has_data") refers to a value ("clusters/", "station/{station_id}/data/{year}/{month}/{day}/").

Cluster list

This tells us that if we want a list of all clusters we need to use the clusters option by appending "clusters/" to the base url, resulting in the following: http://data.hisparc.nl/api/clusters/.

With this result:

[{"name": "Amsterdam",
  "number": 0},
 {"name": "Utrecht",
  "number": 1000},
 ...
 {"name": "Karlsruhe",
  "number": 70000}]

This JSON is a list (indicated by the [ and ] enclosing brackets) of dictionaries, one for each cluster. Each dictionary contains the name and number of a cluster. This way information about the network of stations can be retrieved.

Javascript example

The following code example will generate a webpage which will use the API to get an up-to-date list of stations. It will then show a drop-down menu from which a station can be selected, once you have chosen a station you can click the Get info button to make Javascript get the station information. To try this you can either use this example page: jsFiddle or create your own HTML file with this code:

<html>
<head>
<script src="http://code.jquery.com/jquery-1.11.1.min.js"></script>
<script>
    $(function() {
        // Get an up-to-date list of HiSPARC stations
        $.getJSON(
            'http://data.hisparc.nl/api/stations/',
            function(data) {
                // Create the drop-down menu
                var select = $('<select>');
                var id, name;
                for (var i in data) {
                    id = data[i].number;
                    name = data[i].name;
                    select.append($('<option>').attr('value', id).text(id + ' - ' + name));}
                $('#station_list').append(select);});

        // Attach a function to the Get info button
        $('#get_station').on('click', function() {
            var id = $('#station_list').find('select').val();
            // Get info for selected station and display it in a nice way
            $.getJSON('http://data.hisparc.nl/api/station/' + id + '/',
                      function(data) {
                          $('#station_info').text(JSON.stringify(data, undefined, 4));
                      });
            });
        });
</script>
</head>
<body style="font-family: sans-serif;">
    <h2>Station info</h2>
    <p id="station_list">Choose a station: </p>
    <input type="submit" id="get_station" value="Get info">
    <pre id="station_info"></pre>
</body>
</html>

Python example

In this example we will use several standard Python libraries and the popular plotting library matplotlib (pylab). We start by importing the required libraries, one to get data from the urls, one to make working with dates easy and the plotting library. Then define the start values and perpare two empty lists in which the data can be placed. Then a while loop is used to loop over all days between datum and end_datum, reading each corresponding url. Finally a plot is made, setting the dates against their values.

Start Python and type (or copy/paste without the >>>) the following lines of code:

>>> from urllib2 import urlopen
>>> from datetime import date, timedelta
>>> from pylab import plot, show
>>> id = 501
>>> datum = date(2010, 10, 1)
>>> end_datum = date(2011, 2, 1)
>>> base = 'http://data.hisparc.nl/api/station/%d/num_events/%d/%d/%d'
>>> events = []
>>> dates = []
>>> while datum < end_datum:
...     url = urlopen(base % (id, datum.year, datum.month, datum.day))
...     events.append(url.read())
...     dates.append(datum)
...     datum += timedelta(days=1)
...
>>> step(dates, events)
>>> show()

SAPPHiRE

The HiSPARC Python framework SAPPHiRE includes an API module. This module simplifies access to the API. See the SAPPHiRE documentation for more information: http://docs.hisparc.nl/sapphire/.