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

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:


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:


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.


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

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

Same limiting and offsetting options are also available for series


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

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.