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 media accessible through our API. There are two ways to detect such a 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:

• 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. More information about listing and filtering programs can be found from the tutorial.

Now, if you used the filtering parameters above, you’re done. However, for the sake of it, let’s detect the region and content protection information from a 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 contentProtection.id of 22-1 (default). Both 22-0 and 22-1 are available through API, so this media can be accessed.