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.