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!