Deprecation notice: The API endpoints mentioned in this tutorial will be disabled during the spring 2021.
Finding out what’s playing on the radio
In this tutorial we’ll find a radio station we’re interested in and check what’s on the air. We need to make two API calls to get the information we want: first to find the radio service’s id and then to use that id to find out the current programme.
Part 1: Finding a radio service
Let’s try to find out what’s playing on the Yle Radio 1 -station right now. First we will make an API call to get a list of Yle broadcasting services.
curl -v "https://external.api.yle.fi/v1/programs/services.json?type=radiochannel&limit=5&offset=0&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" | python -mjson.tool
We should get back a JSON document containing 5 radio services with offset 0. Changing the limit and offset parameters lets us browse
services until we find the one we want. We were lucky though–Yle Radio 1 is the first element in the data array of the response. We are interested in
its id field: "id": "yle-radio-1"
.
The services endpoint’s type parameter can be used to find different kinds of broadcasting services. It can have one of the following
values: tvchannel
, radiochannel
, ondemandservice
or webcastservice
. You can also call it by service id:
curl -v "https://external.api.yle.fi/v1/programs/services/{id}.json?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"
Next we’ll use the id we got to find out what’s playing on the station.
Part 2: Getting the currently playing song
To find out what’s playing on a radio channel, we have to make a call to the nowplaying API endpoint. Since we have the id of the station, everything is simple.
curl -v "https://external.api.yle.fi/v1/programs/nowplaying/yle-radio-1.json?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" | python -mjson.tool
This time the name of the json file should be a radio service’s id. There are two ways to check which
of the programmes is playing right now. The easier way is to check for a broadcast which has "delta": "1"
. The other way is to look at the
startTime
and endTime
fields. The content object includes the name of the programme and the performer(s). The partOf object tells us if the
current broadcast is part of a series.
The default response length is 5 programmes. With the start
and end
parameters you can select which programmes you want to see temporally. They default to
-2 and 2, giving a list of 3 previous, the current and next broadcast. Pay attention to the delta field again. Try it with different values yourself!
This concludes the what’s playing tutorial. Thanks for reading!