API overview

Here is some general information about our APIs.

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.

Test environment

There is also a test environment available at https://external.api-test.yle.fi.

Just take notice of these few things:

  • You need a separate Yle Tunnus account in test environment. This can be created in https://tunnus-test.yle.fi.
  • Test environment access keys are also separate from production. Keys can be requested in https://tunnus-test.yle.fi/api-avaimet.
  • Test environment content differs from production.
  • Test environment is not as stable as production environment. Unannounced downtime can occur.

Response format

Unless otherwise stated, response format is JSON.

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

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

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/teletext/pages/400.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 a 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.

Rate limiting

The API is rate limited. You can expect to be able to do 10 requests/second, 300 requests/hour and 7200 requests/day 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

The current API version is included as the first element in a request path. 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:

  • new required parameters
  • renaming or removing fields from response JSON

However, small changes can be done to existing versions:

  • new optional parameters can be added
  • new fields and content can be added to response JSON