Detecting media’s availability

Unfortunately, not all content can be made available through our APIs yet. We’ve had to limit access to certain medias for copyright and contractual reasons.

Through the programs endpoint, you’ll sometimes get programs that don’t have a media that’s accessible through our API. There are two ways to detect such scenario:

  1. Try retrieving the media URL (see playing a program tutorial for instructions). If the media isn’t accessible to the public, you’ll get HTTP 403 Forbidden when trying this. However, you still need to check media for region restrictions by yourself (see below).

  2. Detect restricted content using the criteria below

Depending on your use case, either one of the solutions might be valid. However, if you want to show a listing of playable programs, you might want to do the filtering by yourself according to following criteria:

Criteria to determine if media can be accessed

In short:

  • Media for programs in these categories/subjects can’t be retrieved through the API:

    • 5-162 (news)
    • 5-164 (sports news)
    • 5-226 (radio news) or
    • 5-228 (radio sports news). In other words, news media isn’t available.
  • If publication event has region: "Finland", the media is only accessible in Finland. When region: "World" is present, the media can be accessed anywhere.

  • Also, only media with the following content protection levels can be accessed:

    • 22-0 (none)
    • 22-1 (default)

    22-2 (DRM protected) and 22-3 (SecureHD) are not available through the API.

You can use contentprotection=22-0,22-1 filter when listing programs to filter out SecureHD and DRM protected content. You can also use region=fi or region=world parameter to return only programs viewable from your region. Unfortunately, there’s no way to exclude certain categories from programs listing currently. More information about listing and filtering programs can be found from the tutorial.

To check whether the program is in one of the excluded categories, you need to manually scan through its subject array. It looks like this for program 1-2797656:

    "key": "uutisohjelmat",
    "type": "Concept",
    "inScheme": "areena-content-classification",
    "broader": {
      "id": "5-162"
    "title": {
      "sv": "Nyhetsprogram",
      "fi": "Uutisohjelmat"
    "id": "5-163"
    "key": "uutiset",
    "type": "Concept",
    "inScheme": "areena-analytics-classification",
    "title": {
      "fi": "Uutiset"
    "id": "5-268"

If any of the subjects have id that’s excluded from API, you can’t access the media. You must also check the field for each subject. Here, the first subject has "5-162", which is for news, meaning the media is not available through API.

Now, if you used the filtering parameters above, you’re done. However, for the sake of it, lets detect the region and content protection information from program’s details.

For this, you need the program object and the publication event. Finding this is explained in playing a program tutorial. At the time of writing, the currently available publication event looks like this for 1-2197187:

  "temporalStatus": "currently",
  "publisher": [
      "id": "yle-fem"
  "id": "4-4230821",
  "startTime": "2015-05-03T21:00:00+03:00",
  "region": "Finland",
  "duration": "P14DT2H59M59S",
  "service": {
    "id": "yle-areena"
  "endTime": "2015-05-17T23:59:59+03:00",
  "type": "OnDemandPublication",
  "media": {
    "downloadable": false,
    "type": "VideoObject",
    "available": true,
    "contentProtection": [
        "type": "ContentProtectionPolicy",
        "id": "22-1"
    "duration": "PT1H28M46S",
    "id": "6-539d1fb3bea04cfaa603443fc0208297"

Because the publication event has region: "Finland", its media is not available outside of Finland. You can use an online service to detect your user’s location by IP address. One such service is Telize.

Last, you need to check media’s content protection. Here, the media has of 22-1 (default). Both 22-0 and 22-1 are available through API, so this media can be accessed.