Deprecation notice: The API endpoints mentioned in this tutorial will be disabled during the spring 2021.

Listing programs

In this tutorial we briefly explain how you can list and search programs. First off, the endpoint we’ll be using throughout this tutorial unless explictly specified is

https://external.api.yle.fi/v1/programs/items.json

If you give that url a whirl (do remember that you must provide your app_id and app_key with each request) you get a list of 25 first programs. At the root of that response is a meta block:

"meta": {
    "offset": "0",
    "limit": "25",
    "count": 2117675,
    "program": 1993056,
    "clip": 124609
}

That tells us that there are (at the time of writing) a total of 2117675 items out of which 1993056 are programs and 124609 are clips and that we are viewing the first 25. You get the next 25 items if you add the offset=25 parameter.

But.. browsing through all those programs page by page would be rather foolish, so maybe we should filter the result somehow to make it more manageable.

Filtering and sorting

We don’t want to get programs that we actually can’t play right now. We can use the availability=ondemand parameter to filter out all but currently playable content. And to get only video or audio content, we can use mediaobject parameter. For example:

availability=ondemand&mediaobject=video

All filters are chainable.

Let’s say that we are looking for an episode of immensely popular (at least in age group 7 years and younger) series Oktonautit, we may do a free-text search by supplying the q=oktonautit parameter.

Speaking of popularity, you can order the result by popularity by using the order parameter, for example:

order=playcount.24h:desc

That gives us the list of most watched programs from last 24 hours. Other duration possibilities are 6h, week and month. You can also get ascending order by using asc.

Series

You might notice that each episode of Oktonautit contains following section

partOfSeries": {
    "id": "1-2523689"
}

but if you try to find that id by calling

https://external.api.yle.fi/v1/programs/items/1-2523689.json

you get 404 Not Found. That is because there is a specific endpoint for series

https://external.api.yle.fi/v1/series/items/1-2523689.json

Same limiting and offsetting options are also available for series

https://external.api.yle.fi/v1/series/items.json?limit=1&offset=2

Categories

So what if we want to get only movies? That’s where we use the category=5-135 parameter and out comes just the movies. “But wait, how am I supposed to know that 5-135 means movies?”, you may ask. That information can be queried from categories.json endpoint

https://external.api.yle.fi/v1/programs/categories.json?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

from the result

"id": "5-135",
"title": {
    "fi": "Elokuvat",
    "sv": "Filmer"
},
"broader": {
    "id": "5-131"
},
"inScheme": "areena-content-classification",
"type": "Concept",
"key": "elokuvat",
"indexDataModified": "2015-03-26T10:25:23.307+02:00"

we see that key elokuvat (movies in finnish) corresponds to id 5-135. Filtering results by category works exactly the same way with series.

This concludes our tutorial on listing and filtering programs.