Documentation

Usage instructions, and the endpoints that are available

Authentication

All requests to the API will need to be signed with a private keyfile which Radioplayer will issue end-users with, as well as an apiKey. An example of a signed request (sent using Node JS's https package) will look something like the following...

var apiKey = [CLIENT WILL BE ISSUED WITH API KEY ID];
var key = fs.readFileSync([PATH TO PRIVATE API KEY] + '.pem', 'ascii');
var options = {     host: //[..etc]   };
var request = https.request(options, function(obj) {
  var chunks = [];
  obj.on('data', function (chunk) {
    chunks.push(chunk);
  });

  obj.on('end', function () {
    // process data: JSON.parse(chunks)
  });
});

httpSignature.sign(request, {
  key: key,
  keyId: apiKey
});

request.on('error', function(err) {
  // handle error
});

request.end();
        

A bash script that executes an authenticated curl script would look something like the following...

now=$(date -u "+%a, %d %h %Y %H:%M:%S GMT")
sig=$(echo "date:" $now | \
tr -d '\n' | \
openssl dgst -sha256 -sign "/Users/josholdham/58ad7ede2dee2770cb89a1cf.pem" | \
openssl enc -e -a | tr -d '\n')

curl -sS "http://api.radioplayer.org/stations/826101""$@" -H "date: $now"  \
          -H "Authorization: Signature keyId=\"58ad7ede2dee2770cb89a1cf\",algorithm=\"rsa-sha256\",signature=\"$sig\""
        

You can apply for API Access / keyfiles by emailing [email protected].


Versioning

Any major or breaking changes to the API will result in a new version being released. Different/newer versions of the API can be specified in your requests, by prepending a version indicator to the start of endpoint URLs.

For example, to explicitly call version 2 of the API, you prepend v2/ at the start of your endpoint, eg api.radioplayer.org/v2/stations/826100.

If no version is explictly specified, your request will be defaulted to the oldest available version.

We will support old versions for at least six months after they are replaced by a newer version, and aim to support two versions back (eg, if we update to v5, we will aim to support v3, v4, and v5).


Countries

In some cases, a country code is required to specify which country's data you wish to retrieve. Where possible we have tried to make requests able to be country-agnostic, but given the structure of the data we are working with this isn't efficient in all cases. At the moment, we support the following countries (listed with their corresponding numeric ISO code).

  • UK: 826
  • Germany: 276
  • Austria: 040
  • Canada: 124
  • Ireland: 372

Limits

To be confirmed


Response Structure

Every response is contained by an envelope. The format of this envelope is pretty uniform, and as a basic rule we should expect to see an object with two fields; a data array, and a meta object. The meta object will contain information about the data being returned (ie pagination information, where relevant), while the data array will contain data relating to the request made. A simple envelope will be structured as follows...

{
  "meta": {
    "paginated": false,
    "count": 270
  },
  "data": [
    { OBJECT },
    { OBJECT },
    ...
  ]
}
        

There will be cases in which this envelope has slightly more complexity. In some instances, meta objects may contain a flag of nesting set to true. Whenever this occurs, it means that the corresponding data array will contain an array of objects which themselves contain meta and data fields. A pseudo-response in this style would look like...

{
  "meta": {
    "paginated" : false,
    "nesting": true,
    "count": 2
  },
  "data": [
    {
      "meta": {
        "paginated": false,
        "nesting": false,
        "count": 2
      },
      "data": [
        {OBJECT},
        ...
      ]
    },
    { ... }
  ]
}
        

At the moment, the logic for this pattern of data is when we have requested information about items that could potentially relate to multiple different 'parent' groups. For instance when we request schedule information, we can request schedules for multiple different stations all at once. Each station will return its own paginated subset of schedule data. We therefore organise the top level data field into an array of these different stations: with each of these child items containing a data array of schedule items, and a meta object with corresponding pagination information.


Caching

Server-side caching is used to improve the performance of our APIs. The meta object returned in API responses will contain a key fromCache to indicate if the response data has come from the cache or not. The meta object will also include a field cacheExpiresAt, indicating when this data's cache will expire (UNIX timestamp format). Data that was not itself returned from the cache will still contain this cacheExpiresAt field, as the request will be cached on the server before it is returned to the client.


XML Support

The default response format is JSON, but basic support for XML responses is included. To receive your response as XML add an xml=true parameter to your URL, or set a request header of Accept: 'application/xml'.


Endpoints