YLE API

API overview

Here are some general information about our APIs.

Content availability

Most of Areena’s content is available through API. However, for now we’ve had to limit access to some medias (most notably news content and DRM protected content). See documentation on detecting media’s availability for more information.

Base url

You should always make your API requests to https://external.api.yle.fi

HTTP works also, but you should always use HTTPS unless you have a good reason to not use it.

Response format

Unless otherwise stated, response format is JSON. XML is not supported.

The basic structure of API JSON response is:

{
  // meta data about request: how many hits, used parameters, ...
  "meta": {...},

  // entries matching your request, might also be an Object
  "data": [...], 

  // any notifications about the request (deprecation notices, etc.)
  "notifications":[...]
}

If there’s no content for certain field, the field is usually omitted.

In error scenarios (endpoint not found, authentication failure, …) the response body might be plain text.

JSONP support

All endpoints returning JSON support JSONP. Just supply callback parameter. CORS is not yet supported.

Gzip support

All APIs support gzip compression. To enable it, add Accept-Encoding: gzip header to your request.

Authentication

Each request to the API should be authenticated with a pair of app_id and app_key. These should be provided as query string parameters, like in this call:

curl -v https://external.api.yle.fi/v1/programs/items.json?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

There’s no need to hide your authentication credentials from end users. It’s fine to do API calls directly from browser, leaving the API keys visible in network inspector. However, you shouldn’t commit your credentials to public source code repositories.

In case you supply invalid credentials, the response status will be HTTP 403 Forbidden.

Media URL decryption key

In addition to app_id and app_key you are provided with a decryption key for Media URLs. You must keep this key secure: it shouldn’t be easily visible (JavaScript files, network inspector, …) to your end users or commited to public source code repositories.

See the tutorial on playing programs on how to decrypt media URLs using the key.

Rate limiting

The API is rate limited. You can expect to be able to do 10 requests/second to the API. If you exceed your quota, HTTP 401 Unauthorized response will be returned.

In this case, you should wait for a while before trying to make a new request.

Versioning

Currently used API version can be seen as the first request path element. We always document the most recent version of API. Different endpoints in API might have different versions.

Whenever we release a new major version of an endpoint, we’ll inform you about the changes. You should migrate to the new endpoint as soon as possible. We’ll continue supporting the old endpoint version for some time, but make no promises on how long we’ll be able to support it.

Some changes that warrant a new major version:

However, small changes can be done to existing versions: