Lists articles matching the given search criteria.

Parameters

Filtering

Other

NOTE: When using id parameter, orderby will be ignored, and articles will be returned in the same order that the IDs were given in.

Response

{
  "meta": {
    "offset": Integer,      // value of the offset parameter
    "limit": Integer,       // value of the limit parameter
    "count": Integer,       // number of articles in the response
    "total": Integer,       // total number of articles matching the search criteria
    "remaining": Integer    // number of articles after this result set
  },
  "data": Array[Article]      // articles of this result set
  "notifications": [
    { "message": "Query executed successfully." }
  ]
}

Examples

Get multiple articles by IDs

https://articles.api.yle.fi/v2/articles.json?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY&id=3-8103169,3-8104234

Find all articles published after 2015-06-25 12:00:00 (Finnish local time)

curl -XGET https://articles.api.yle.fi/v2/articles.json?published_after=2015-06-25T12:00:00+0300&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

The returned articles are ordered by the publish date in descending order.

Find IDs of all articles authored by ‘Yle Lahti’

curl -XGET https://articles.api.yle.fi/v2/articles.json?author=Yle%20Lahti&fields=id&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

The fields=id parameter instructs Articles API to include only the article ID in the results.

Find all articles using free text search for ‘“Sauli Niinistö”’

curl -XGET https://articles.api.yle.fi/v2/articles.json?q=%22Sauli%20Niinist%C3%B6%22&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

By redirecting browser to this endpoint, a registered client application requests Auth API:

• To establish user’s Yle Tunnus identity (by either verifying the Yle Tunnus login cookie already present in the request, or by redirecting the browser to Yle Tunnus login dialog and obtaining the login cookie after successful login).

• To gain user’s consent to the registered client application to use user’s data resources at a given scope for a predefined time period. This step can be skipped for Yle internal applications that operate within Yle Tunnus terms of service.

Query parameters

Response

302 Found on success

After receiving the request, Auth API proceeds to authenticate the user (if necessary), and obtain consent from the user for the requested scopes (again, if necessary - the consent may have already been granted explicitly or implicitly). Then, the browser is redirected to your application’s redirect URI.

When authorization was successful, and requested response_type was code, the redirect URI is appended with the following query parameters:

Your application can then proceed to request an access token with the authorization code.

If response_type was token instead, the redirect URI is appended with these parameters in the URI fragment:

Your application should parse the URI fragment, and then validate the access token and the state. It is your application’s responsibility to ensure that it only operates with valid access tokens! See About access tokens for more information about the access token.

302 Found on failures

If authorization request failed for some reason, the browser is still redirected to your application’s redirect URI (unless there was a problem with the redirect_uri parameter itself), but this time the redirect URI is appended with the following information. As with success response, these are appended as query parameters when response_type was code, and in URI fragment when response_type was token.

Your application should handle these failures in authorization gracefully, to ensure that the user experience remains pleasant.

400 Bad Request on failures with redirect URI

If the authorization failed because of a problem with the redirect_uri parameter itself, Auth API will not redirect browser to that URI. Instead, it responds with status code 400. The abovementioned error and error description are provided in response body as a JSON object like this:

{
  "error": invalid_request",
  "error_description": "Missing or invalid redirect_uri."
}

If the request included a redirect URI but you can’t figure out what the problem is, remember that each redirect URI has to be configured in the client configuration of your application. Otherwise it is rejected. Contact API support to check the configuration, if necessary.

Validates provided access token, and responds with JSON object that contains basic information about the token.

Query parameters

Response

200 OK when access token is valid

This response indicates that the token is valid and has not expired yet. Response is a JSON object with the following attributes:

Token can be used until it expires.

400 Bad Request when access token is not valid

This response indicates that the token is not valid, or that it has expired. Token must not be used.

Returns a list of subject keys of users removed between a given time range and client sector. It is recommended to use a short time range, for example, between 5 to 15 minutes.

Parameters

client_id, start_time and end_time are all mandatory parameters. start_time and end_time must conform to full ISO 8601 format. start_time and end_time must be no more than 30 days apart, and start_time must occur before end_time.

Example query (without app_id and app_key parameters):

curl 'https://auth.api.yle.fi/v1/subjects/removed?client_id=ylefiapp&start_time=2018-01-01T10:00:00Z&end_time=2018-01-01T10:05:00Z'

Response

200 OK when request was successful

Body contains a JSON object with a list of removed user IDs, in the attribute removed_user_ids:

{
  "removed_user_ids": ["cf088b65e4b72b7c8381089a", "31ebf9cd8db642aa26e4ec93"]
}

400 Bad Request when client_id is missing

400 Bad Request when start_time is greater than end_time, either time is invalid or missing, or the time difference is over 30 days

Retrieves accepted comments of the given topic.

Note: retrieving comments via this API supports threaded comment trees.

Legacy API for older client without threading support exists, too: Get accepted comments of a topic (legacy version).

API returns new or old style responses depending on the max_hierarchy_depth query parameter. Including it in the request triggers the new API response, leaving it out invokes legacy response.

Note on threading

Comment support for threading will be limited to n levels. Comments Plugin will show two levels (n = 2) of comments, but callers of the API can choose how many levels they want to see.

Users can reply to comments on all levels and API will store the relationship between original comment and its replies. Plugin UI will display comment threads limited to two levels: all replies to second-level replies (and further) will be shown on level two, sorted by creation time (earliest first).

The comments API handles the comment tree formatting to limit tree depth to max_hierarchy_depth.

URL parameters

Query parameters

Response

200 OK on success

Threaded response will contain an array of top-level comments under key data:

{
  "data": [{
    "id": "99c3f086-20fd-4f6d-821d-89cea8f7f8bb",
    ...
    }, {
    "id": "6b68cc3a-5b6e-4b03-810b-4f9c094a4e9f",
    ...
  }]
}

Each comment will have a children element, containing comments to be displayed as replies to this comment. Child comments may in turn contain children, within the limits of requested max_hierarchy_depth.

{
  "id": "99c3f086-20fd-4f6d-821d-89cea8f7f8bb",
  "children": [{
                 "id": "8b716535-370a-401c-bc11-2bb787ee40ba",
                 "parentId": "99c3f086-20fd-4f6d-821d-89cea8f7f8bb",
                 "children": [...]}],
                 ...
              }, {
                 "id": "ee3b6974-d708-4394-bd2b-c5e57881ba60",
                 "parentId": "99c3f086-20fd-4f6d-821d-89cea8f7f8bb",
                 "children": [...]}],
                 ...
              }]
 }

Each response comment will also contain a parentId element identifying the parent comment for which this comment is a response.

Note the difference: parentId refers to stored comment-reply relationship while the children array construction is for display purposes and obeys the requested max_hierarchy_depth.

400 Bad Request when request contains invalid parameter values

Examples:

{ "notifications": [
    { "message": "Invalid value provided for 'from_parent_id'." }
]}

{ "notifications": [
    { "message": "Illegal parameter value for 'order' provided. The allowed options are parent_created_at:asc or parent_created_at:desc" }
]}

{ "notifications": [
    { "message": "Illegal parameter value for 'parent_limit' provided. The allowed range is 1-100" }
]}

404 Not Found when topic is not found

{ "notifications": [
    { "message": "Requested topic not found" }
]}

cURL example

curl -X GET -H 'Content-Type: application/json' \
    "https://comments.api.yle.fi/v1/topics/1-1234567/comments/accepted?max_hierarchy_depth=2&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

Retrieves accepted comments of the given topic.

Note: this page documents the old API, prior to threading support in comments. Use this only API only if you need to.

Adding query parameter max_hierarchy_depth to query invokes the new API version. See Get accepted comments of a topic.

URL parameters

Query parameters

Response

200 OK on success

Response body is a JSON array that contains the accepted comments of the topic that match the search criteria.

400 Bad Request when request contains invalid parameter values

Examples:

{ "notifications": [
    { "message": "Invalid value provided for 'from_parent_id'." }
]}

{ "notifications": [
    { "message": "Illegal parameter value for 'order' provided. The allowed options are parent_created_at:asc or parent_created_at:desc" }
]}

{ "notifications": [
    { "message": "Illegal parameter value for 'parent_limit' provided. The allowed range is 1-100" }
]}

404 Not Found when topic is not found

{ "notifications": [
    { "message": "Requested topic not found" }
]}

cURL example

curl -X GET -H 'Content-Type: application/json' \
    "https://comments.api.yle.fi/v1/topics/1-1234567/comments/accepted?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

RESERVED FOR MODERATOR USE

Get all comments for a topic.

Note that this endpoint returns all comments, including unpublished comments that have not been moderated yet. Do not display these for all users!

This operation requires moderator privileges. The moderator must also be authorized to moderate the topic in question.

URL parameters

Response

200 OK on success

400 Bad Request if the topic does not exist

{ "notifications": [
    { "message": "Topic does not exist." }
]}

401 Unauthenticated when request is not authenticated

{ "notifications": [
  { "message": "This endpoint requires authentication." }
]}

403 Forbidden when authenticated user does not have moderator rights, is not active, or has not been authorized to moderate the topic

{ "notifications": [
  { "message": "user123456 (yle-tunnus/577e23e8e4a085db86ddeb43) has insufficient rights to perform this action." }
]}

Example request

curl --header 'Cookie: ylelogin=YOUR_VALID_LOGIN_COOKIE' \
"https://comments.api.yle.fi/v1/topics/33-3c9c2d2e-25cf-48ff-9715-8fb43459aff9/comments?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"
[
  {
    "rejectedAt": "2017-04-18T13:39:20+03:00",
    "content": "hähää",
    "moderatedBy": "Juha",
    "acceptedAt": null,
    "createdByModerator": false,
    "author": "Juha",
    "topicExternalId": "7-740449",
    "id": "33-fe950a7b-7c74-4f48-9a33-aed2ba1986d1",
    "parentId": null,
    "topicId": "33-3c9c2d2e-25cf-48ff-9715-8fb43459aff9",
    "anonymousComment": true,
    "createdAt": "2016-06-02T16:11:30+03:00",
    "createdByTrustedCommentAuthor": false
  }
]

RESERVED FOR MODERATOR USE

Get comments (including unpublished ones!) for all topics that the authenticated user is authorized to moderate.

Note: For perfomance reasons, accessing comments this way is limited to comments created in last 7 days.

Authenticated user must have moderator rights.

URL parameters

When neither created_after nor created_after_id are defined, the endpoint just returns the latest comments.

Response

200 OK on success

Response body is a JSON object with a data attribute. The data is an array of comments, sorted from oldest to newest (by creation time). See examples below for a detailed listing of attributes returned for each comment.

400 Bad Request if given parameter values were not valid

{ "notifications": [
    { "message": "Limit must be a number between 1 and 100." }
]}

401 Unauthenticated when request is not authenticated

{ "notifications": [
  { "message": "This endpoint requires authentication." }
]}

403 Forbidden when authenticated user does not have moderator rights, or the user account has been inactivated

{ "notifications": [
  { "message": "user123456 (yle-tunnus/xxx) has insufficient rights to perform this action." }
]}

Example requests

Use case: present a list of latest automatically moderated comments to human moderators, and then update the list with new comments that have been posted and automatically moderated after the initial request.

First, fetch a list of latest 2 comments to keep the example size suitably small:

curl --header 'Cookie: ylelogin=YOUR_VALID_LOGIN_COOKIE' \
"https://comments.api.yle.fi/v1/comments?is_auto_moderated=true&limit=2&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

{
  "data": [
    {
      "acceptedAt": "2018-05-17T11:33:04+03:00",
      "anonymousComment": true,
      "author": "Anne",
      "content": "Kaikki ihmiset syntyvät vapaina ja tasavertaisina arvoltaan ja oikeuksiltaan.",
      "createdAt": "2018-05-11T11:33:03+03:00",
      "createdByModerator": false,
      "createdByTrustedCommentAuthor": false,
      "id": "33-dd50c506-d555-4350-ab5a-9bed308e004c",
      "moderatedBy": "Automatic Moderator",
      "parentId": null,
      "rejectedAt": null,
      "topicExternalId": "7-65467548",
      "topicId": "33-796d453d-f23b-4b48-af34-75b507294542",
      "autoModerationCategory": "PROBABLY_GOOD",
      "autoModerationProbabilityBad": 0.2
    },
    {
      "acceptedAt": null,
      "anonymousComment": false,
      "author": "Lasse",
      "content": "Blergh!",
      "createdAt": "2018-05-17T11:34:56+03:00",
      "createdByModerator": false,
      "createdByTrustedCommentAuthor": false,
      "id": "33-9f7eaf8f-57d6-4bfc-bb9e-4fb7e793507e",
      "moderatedBy": "Automatic Moderator",
      "parentId": null,
      "rejectedAt": "2018-05-17T11:34:57+03:00",
      "topicExternalId": "7-76334353",
      "topicId": "33-796d453d-f23b-4b48-af34-75b507236842",
      "autoModerationCategory": "PROBABLY_BAD",
      "autoModerationProbabilityBad": 0.95
    }
  ]
}

Note the "id": "33-9f7eaf8f-57d6-4bfc-bb9e-4fb7e793507e" attribute on the last ( = most recent) comment.

Now, let’s make another request a little later, to see if there are new comments. The created_after_id parameter is set to the value taken from the last comment’s id:

curl --header 'Cookie: ylelogin=YOUR_VALID_LOGIN_COOKIE' \
"https://comments.api.yle.fi/v1/comments?is_auto_moderated=true&created_after_id=33-9f7eaf8f-57d6-4bfc-bb9e-4fb7e793507e&limit=2&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

{
  "data": [
    {
      "acceptedAt": "2018-05-17T11:35:03+03:00",
      "anonymousComment": false,
      "author": "Paavo",
      "content": "Heille on annettu järki ja omatunto, ja heidän on toimittava toisiaan kohtaan veljeyden hengessä.",
      "createdAt": "2018-05-11T11:35:02+03:00",
      "createdByModerator": false,
      "createdByTrustedCommentAuthor": false,
      "id": "33-03f51218-4c64-450c-9c1c-08bb18056f9a",
      "moderatedBy": "Automatic Moderator",
      "parentId": null,
      "rejectedAt": null,
      "topicExternalId": "7-65467548",
      "topicId": "33-796d453d-f23b-4b48-af34-75b507294542",
      "autoModerationCategory": "PROBABLY_GOOD",
      "autoModerationProbabilityBad": 0.15
    },
    ...
  ]
}

To fetch new comments again later, you’d just pick up the id value from the last comment, and include it in your request as the created_after_id parameter. And so on.

Get all open notices for a topic.

This operation requires moderator privileges. The moderator must also be authorized to moderate the topic in question.

URL parameters

Response

200 OK on success

400 Bad Request if the topic does not exist

{ "notifications": [
    { "message": "Topic does not exist." }
]}

400 Bad Request if the status of the comments is not open

{ "notifications": [
    { "message": "Unsupported status" }
]}

401 Unauthenticated when request is not authenticated

{ "notifications": [
  { "message": "This endpoint requires authentication." }
]}

403 Forbidden when authenticated user does not have moderator rights, is not active, or has not been authorized to moderate the topic

{ "notifications": [
  { "message": "user123456 (yle-tunnus/577e23e8e4a085db86ddeb43) has insufficient rights to perform this action." }
]}

Example request

curl --request GET --header 'Cookie: yletestlogin=YOUR_VALID_LOGIN_COOKIE' \
"https://comments.api-test.yle.fi/v1/topics/33-3c9c2d2e-25cf-48ff-9715-8fb43459aff9/notices?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"
[
  {
    "content": "Asiaton kommentti",
    "reporterEmail": "ella.esimerkki@yle.fi",
    "closedBy": null,
    "status": "open",
    "id": "33-a164fe2d-e4d3-4cc4-9bb9-9179e720f0a1",
    "topicId": "33-3c9c2d2e-25cf-48ff-9715-8fb43459aff9",
    "commentId": "33-9cc9b160-ba66-438d-aadb-fe665760fdc8",
    "closedAt": null,
    "createdAt": "2017-05-09T10:46:53+03:00",
    "reporterName": "Ella Esimerkki"
  }
]

Retrieves IDs of comments in the given topic that the current user has liked.

URL parameters

Response

200 OK on success

Response will contain an array of comment ids. [ “99c3f086-20fd-4f6d-821d-89cea8f7f8bb”, “6b68cc3a-5b6e-4b03-810b-4f9c094a4e9f”, … ]

If the request isn’t authenticated, an empty array is returned.

404 Not Found when topic is not found

{ "notifications": [
    { "message": "Requested topic not found" }
]}

cURL example

curl -X GET --header 'Cookie: yletestlogin=YOUR_VALID_LOGIN_COOKIE' \
    "https://comments.api.yle.fi/v1/topics/1-1234567/comments/liked?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

Request parameters

Note

Caller’s Yle Tunnus session is used to filter results if both url and externalIds parameters are omitted.

Response

200 OK on success

[
    {
      "tags": [{"id": "33-b694c439-c648-43a7-811d-30c8e10c0693", "externalId": "svenska", "name": "Svenska"}],
      "oldestOpenModerationTaskCreatedAt": "2018-07-20T17:01:21+03:00",
      "title": "Radiohuset frågar: Vad får ett museibesök kosta?",
      "acceptedCommentsCount": 0,
      "id": "c3628d2e-1df2-41fc-986e-47dbf3105606",
      "latestModerationTaskFinishedAt": "2018-07-20T17:20:07+03:00",
      "url": "http://svenska.yle.fi/artikel/2016/03/20/radiohuset-fragar-vad-far-ett-museibesok-kosta",
      "isLocked": false,
      "isHidden": false,
      "externalId": 3-1234",
      "unprocessedNoticesCount": 0,
      "unmoderatedCommentsCount": 0,
      "postModerateComments": false,
      "autoModerateComments": false,
      "allowAnonymousCommenting": true
    }
]

OR when using externalIds parameter

{
    "data": [
        {
            "allowAnonymousCommenting": false,
            "tags": [{"id": "33-dd8cbebc-7035-4b2a-92a1-4dda9031f0c4", "externalId": "uutiset-prod", "name": "Uutiset"}],
            "oldestOpenModerationTaskCreatedAt": null,
            "postModerateComments": false,
            "title": "Itä-Suomen kaupungit lämpenevät ennätysvauhtia – vuotuinen keskilämpötilan muutos on toiseksi suurin Euroopassa",
            "externalId": "3-10419721",
            "autoModerationPlatform": "uutiset",
            "isLocked": false,
            "id": "33-2206b6b5-6ade-430c-a1d9-84999f92285c",
            "latestModerationTaskFinishedAt": "2018-09-24T13:54:47+03:00",
            "isHidden": false,
            "unmoderatedCommentsCount": 0,
            "url": "https://yle.fi/uutiset/3-10419721",
            "unprocessedNoticesCount": 0,
            "acceptedCommentsCount": 6
        }
    ]
}

Response

200 OK on success

{
  "tags": [{"id": "33-b694c439-c648-43a7-811d-30c8e10c0693", "externalId": "svenska", "name": "Svenska"}],
  "title": "Radiohuset frågar: Vad får ett museibesök kosta?",
  "acceptedCommentsCount": 0,
  "id": "c3628d2e-1df2-41fc-986e-47dbf3105606",
  "url": "http://svenska.yle.fi/artikel/2016/03/20/radiohuset-fragar-vad-far-ett-museibesok-kosta",
  "isLocked": false,
  "isHidden": false,
  "externalId": 3-1234",
  "unprocessedNoticesCount": 0,
  "unmoderatedCommentsCount": 0,
  "postModerateComments": false,
  "autoModerateComments": false,
  "allowAnonymousCommenting": true
}

cURL example

curl -X GET -H 'Content-Type: application/json' "https://comments.api.yle.fi/v1/topics/275eb144-8bf0-401b-9597-da7e33056faa?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

Get tags of the topic. This operation requires operator privileges.

Path parameters

Response

200 OK on success

[
    {
      "id": "33-d6cf70ba-5a61-4167-aeae-234e7a02a849"
      "name": "Lasten areena",
      "externalId": "lasten areena",
    },
    {
      "id": "33-22hf8r33-438h-vs98d-03jf-98gjdn3cg89"
      "name": "Ulkomaat",
      "externalId": "ulkomaat",
    }
]

400 Bad Request if the given topic does not exist

{"notifications":[{"message":"Topic does not exist."}]}

403 Forbidden when authenticated user does not have operator privileges, or is not active

Examples

$ curl -X GET -H 'Content-Type: application/json' \
  "https://comments.api.yle.fi/v1/topics/33-82a23a87-6631-4c3e-b937-ded991b7985e/tags?app_id=YOUR_ADD_ID&app_key=YOUR_APP_KEY"

Response

200 OK on success

[
    {
      "id": "33-d6cf70ba-5a61-4167-aeae-234e7a02a849"
      "name": "Lasten areena",
      "externalId": "lasten areena",
    },
    {
      "id": "33-22hf8r33-438h-vs98d-03jf-98gjdn3cg89"
      "name": "Ulkomaat",
      "externalId": "ulkomaat",
    }
]

cURL example

curl -X GET -H 'Content-Type: application/json' 'https://comments.api.yle.fi/v1/tags?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY'

Request parameters

Response

200 OK on success

[
    {
      "id": "33-d6cf70ba-5a61-4167-aeae-234e7a02a849"
      "name": "Lasten areena",
      "externalId": "lasten areena",
    }
]

404 Not Found when a tag could not be found

{ "notifications": [
    { "message": "Could not find tag with name 'Not there'." }
]}

cURL example

curl -X GET -H 'Content-Type: application/json' 'https://comments.api.yle.fi/v1/tags?name=Lasten%20areena&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY'

Retrieves the data of a single user with given Yle Tunnus surrogate ID or 4scale id.

This endpoint supports (and requires) authentication either with Yle Tunnus session or 4scale app_id and app_key.

URL Parameter

Response

200 OK on success

{ "nick": "Juha",
  "createdAt": "2016-07-19T16:46:25+03:00",
  "externalId": "5499aa14f4b0b721913fbe34",
  "externalIdSource": "yle-tunnus",
  "id": "1351b15-ceee-41ec-b4fb-da6f3e219d0e",
  "isModerator": true,
  "isTrustedCommentAuthor": false,
  "isOperator": false,
  "isActive": true,
  "createdBy": null,
  "tags": [
    { "name": "Svenska",
      "externalId": "svenska-yle-fi",
      "id": "33-778f7cdf-c829-4c87-9eb9-1a093231d07c",
      "assignedAt": "2016-07-19T16:46:25+03:00",
      "assignedBy": "admin"
    }
  ]
}

400 Bad Request when externalIdSource is not valid

{ "notifications": [
  { "message": "Illegal value in key 'externalIdSource'. The allowed values are '4scale', 'yle-tunnus'." }
]}

401 Unauthenticated when not authenticated

{ "notifications": [
  { "message": "This endpoint requires authentication." }
]}

403 Forbidden when authenticated user does not have operator rights, or is not active

{ "notifications": [
  { "message": "user123456 (yle-tunnus/577e23e8e4a085db86ddeb43) has insufficient rights to perform this action." }
]}

404 Not Found when user is not found

{ "notifications": [
  { "message": "Could not find user with external id 'xyz123'." }
]}

cURL example

curl -X GET -H 'Content-Type: application/json' "https://comments.api.yle.fi/v1/users/yle-tunnus/5499aa14f4b0b721913fbe34?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

Retrieves the data of a single user by its Yle Tunnus email.

This endpoint supports (and requires) authentication either with Yle Tunnus session or 4scale app_id and app_key.

Query Parameter

Response

200 OK on success

{ "nick": "Juha",
  "createdAt": "2016-07-19T16:46:25+03:00",
  "externalId": "5499aa14f4b0b721913fbe34",
  "externalIdSource": "yle-tunnus",
  "id": "1351b15-ceee-41ec-b4fb-da6f3e219d0e",
  "isModerator": true,
  "isTrustedCommentAuthor": false,
  "isOperator": false,
  "isActive": true,
  "createdBy": null,
  "tags": [
    { "name": "Svenska",
      "externalId": "svenska-yle-fi",
      "id": "33-778f7cdf-c829-4c87-9eb9-1a093231d07c",
      "assignedAt": "2016-07-19T16:46:25+03:00",
      "assignedBy": "admin"
    }
  ]
}

401 Unauthenticated when not authenticated

{ "notifications": [
  { "message": "This endpoint requires authentication." }
]}

403 Forbidden when authenticated user does not have operator rights, or is not active

{ "notifications": [
  { "message": "user123456 (yle-tunnus/577e23e8e4a085db86ddeb43) has insufficient rights to perform this action." }
]}

404 Not Found when user with given email is not found from Yle Tunnus

{ "notifications": [
  { "message": "Could not find Yle Tunnus user with email 'mode.rator@yle.fi'." }
]}

404 Not Found when Yle Tunnus user is not found from Comments API

{ "notifications": [
  { "message": "Could not find user with external id 'xyz123'." }
]}

503 Service Unavailable when Yle Tunnus is not available

{ "notifications": [
  { "message": "Could not connect to Login API. Try again later." }
]}

cURL example

curl -X GET -H 'Content-Type: application/json' "https://comments.api.yle.fi/v1/users?email=mikko.mallikas@gmail.com?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

Retrieves the authenticated user’s own information.

This endpoint supports (and requires) authentication either with Yle Tunnus session or 4scale app_id and app_key.

Response

200 OK on success

{ "nick": "Juha",
  "createdAt": "2016-07-19T16:46:25+03:00",
  "externalId": "5499aa14f4b0b721913fbe34",
  "externalIdSource": "yle-tunnus",
  "id": "1351b15-ceee-41ec-b4fb-da6f3e219d0e",
  "isModerator": true,
  "isTrustedCommentAuthor": false,
  "isOperator": false,
  "isActive": true,
  "createdBy": null,
  "isBanned": false,
  "tags": [
    { "name": "Svenska",
      "externalId": "svenska-yle-fi",
      "id": "33-778f7cdf-c829-4c87-9eb9-1a093231d07c",
      "assignedAt": "2016-07-19T16:46:25+03:00",
      "assignedBy": "admin"
    }
  ]
}

401 Unauthenticated when not authenticated

{ "notifications": [
  { "message": "This endpoint requires authentication." }
]}

cURL example

curl -X GET -H 'Content-Type: application/json' -H 'Cookie: ylelogin=YOUR_YLE_SESSION_TOKEN' "https://comments.api.yle.fi/v1/users/me?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

Look up a user based on his/her current nickname to find out whether he/she is blocked or not.

This operation requires moderator rights.

This not an operation that is meant to be performed often: DB access is unoptimized, for example.

URL parameters

Response

200 OK on success

Example when user is not banned:

{
    "user": {
        "id": "0e81355d-b222-3c76-4b4d-b222-21c546fad41d",
        "isBanned": false,
        "nick":"Risto Reipas"
    },
    "block": null
}

Example when user is banned:

{
    "user": {
        "id": "0e81355d-b222-3c76-4b4d-b222-21c546fad41d",
        "isBanned": false,
        "nick":"Risto Reipas"
    },
    "block": {
        "blockedUserId": "0e81355d-b222-3c76-4b4d-b222-21c546fad41d",
        "reason": "Spämännyt keskusteluja jatkuvasti. \n\nPäättäjä: Aino            Admin, 10.12.2018.",
        "blockingUserId":"0e81355d-b222-3c76-4b4d-b222-21c546faaaaa",
        "createdAt": "2018-12-11T09:25:26+02:00"
    }
}

400 Bad Request when request does not include nickName

401 Unauthenticated when request is not authenticated

403 Forbidden when authenticated user does not have moderator rights, or is not active

404 Not Found when user with the given nickname is not found

Get all notification subscriptions of a user. For every subscription, both the internal and external id of the topic is returned.

URL parameters

Response

200 OK on success

400 Bad Request when user’s external id source is not ‘yle-tunnus’

{ "notifications": [
  { "message": "Illegal value in key 'externalIdSource'. The only allowed value is 'yle-tunnus'." }
]}

401 Unauthenticated when request is not authenticated

{ "notifications": [
  { "message": "This endpoint requires authentication." }
]}

403 Forbidden when authenticated user does not have operator rights, or is not active

{ "notifications": [
  { "message": "user123456 (yle-tunnus/577e23e8e4a085db86ddeb43) has insufficient rights to perform this action." }
]}

404 Not Found when user with the given external id is not found

{ "notifications": [
  { "message": "Could not find user with external id 'xyz123'." }
]}

Example request

curl -X GET \
     "https://comments.api.yle.fi/v1/users/yle-tunnus/5499aa14f4b0b721913fbe34/subscriptions?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

{"subscriptions": [
  {
    "topicExternalId": "7-123456",
    "topicId": "33-796d453d-f23b-4b48-af34-75b507294542"
  }
]}

Get the amount of page views for an article during the requested time period.

Parameters

Response

200 OK on success

400 Bad Request if the yle_id or period parameters are missing or invalid

404 Not Found if the requested article does not exist

Examples

$ curl "https://consumer-events.api.yle.fi/v2/articles/pageviews/delta.json?yle_id=3-7961541&period=1h&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
            "pageViews": 1373,
            "yleId": "3-7961541"
        }
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 1,
        "origin": "Consumer Events API",
        "period": "1h",
        "yle_id": "3-7961541"
    },
    "notifications": []
}

Get top 50 most read articles for given time period by publication & language

Parameters

Response

200 OK on success

400 Bad Request Missing or invalid required parameter value

Example

$ curl -XGET "https://consumer-events.api.yle.fi/v2/articles/pageviews/top.json?period=6h&language=fi&section.publication=urheilu&section.uname=nhl&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
            "score": 8850,
            "yleId": "3-7947199"
        },
        {
            "score": 5205,
            "yleId": "3-7947143"
        },
        {
            "score": 4013,
            "yleId": "3-7960844"
        },
        ...
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 50,
        "origin": "Consumer Events API",
        "language": "fi",
        "period": "6h",
        "section.publication": "urheilu",
        "section.uname": "nhl"
    },
    "notifications": []
}

Get all time page views for any number of articles

Parameters

Note! Multiple ids can be also given like this yle_id=3-123456&yle_id=3-234567&yle_id=3-345678

Response

200 OK on success

400 Bad Request if yle_id is missing or has invalid yle ids in it

404 Not Found if the document does not exist

Examples

$ curl -XGET "https://consumer-events.api.yle.fi/v2/articles/pageviews/total.json?yle_id=3-7961541&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
            "pageViews": 2190,
            "yleId": "3-7961541"
        }
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 1,
        "origin": "Consumer Events API",
        "yle_id": "3-7961541"
    },
    "notifications": []
}

Get the amount of stream starts for a program during the requested time period.

Parameters

Response

200 OK on success

400 Bad Request if the yle_id or period parameters are missing or invalid

404 Not Found if the requested program does not exist

Examples

$ curl "https://consumer-events.api.yle.fi/v2/programs/streamstarts/delta.json?yle_id=1-4226378&period=30min&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
            "streamStarts": 10,
            "yleId": "1-4226378"
        }
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 1,
        "origin": "Consumer Events API",
        "period": "30min",
        "yle_id": "1-4226378"
    },
    "notifications": []
}

Get top 50 most watched programs for given time period

Parameters

Response

200 OK on success

400 Bad Request Missing or invalid required parameter value

$ curl -XGET "https://consumer-events.api.yle.fi/v2/programs/streamstarts/top.json?period=6h&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
          "score": 7357,
          "yleId": "1-2351406"
        },
        {
          "score": 4430,
          "yleId": "1-2213834"
        },
        {
          "score": 3624,
          "yleId": "1-2449145"
        }
        ...
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 50,
        "origin": "Consumer Events API",
        "period": "6h"
    },
    "notifications": []
}

Get all time stream starts for any number of programs

Parameters

Response

200 OK on success

400 Bad Request if yle_id is missing or has invalid yle ids in it

404 Not Found if the document does not exist

Examples

$ curl -XGET "https://consumer-events.api.yle.fi/v2/programs/streamstarts/total.json?yle_id=1-2163411&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
            "streamStarts": 7942,
            "yleId": "1-2163411"
        }
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 1,
        "origin": "Consumer Events API",
        "yle_id": "1-2163411"
    },
    "notifications": []
}

Get the amount of page views for an article during the requested time period.

Parameters

Response

200 OK on success

400 Bad Request if the yle_id or period parameters are missing or invalid

If no data is found, data will be empty, and notifications will contain a message indicating yle_id had no view data for the period.

Examples

$ curl "https://consumer-events.api.yle.fi/v3/articles/pageviews/delta.json?yle_id=3-7961541&period=1h&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
            "pageViews": 1373,
            "yleId": "3-7961541"
        }
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 1,
        "origin": "Consumer Events API",
        "period": "1h",
        "yle_id": "3-7961541"
    },
    "notifications": []
}

Get all time page views for any number of articles

Parameters

Note! Multiple ids can be also given like this yle_id=3-123456&yle_id=3-234567&yle_id=3-345678

Response

200 OK on success

400 Bad Request if yle_id is missing or has invalid yle ids in it

If no data is found, data will be empty, and notifications will contain a message indicating the database found no logged view counts for the yle_id.

Examples

$ curl -XGET "https://consumer-events.api.yle.fi/v3/articles/pageviews/total.json?yle_id=3-7961541&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
            "pageViews": 2190,
            "yleId": "3-7961541"
        }
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 1,
        "origin": "Consumer Events API",
        "yle_id": "3-7961541"
    },
    "notifications": []
}

Get the amount of stream starts for a program during the requested time period.

Parameters

Response

200 OK on success

400 Bad Request if the yle_id or period parameters are missing or invalid

If no data is found, data will be empty, and notifications will contain a message indicating yle_id had no stream count data for the period.

Examples

$ curl "https://consumer-events.api.yle.fi/v3/programs/streamstarts/delta.json?yle_id=1-4226378&period=30min&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
            "streamStarts": 10,
            "yleId": "1-4226378"
        }
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 1,
        "origin": "Consumer Events API",
        "period": "30min",
        "yle_id": "1-4226378"
    },
    "notifications": []
}

Get all time stream starts for any number of programs

Parameters

Response

200 OK on success

400 Bad Request if yle_id is missing or has invalid yle ids in it

If no data is found, data will be empty, and notifications will contain a message indicating the database found no logged stream counts for the yle_id.

Examples

$ curl -XGET "https://consumer-events.api.yle.fi/v3/programs/streamstarts/total.json?yle_id=1-2163411&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" |python -mjson.tool
{
    "data": [
        {
            "streamStarts": 7942,
            "yleId": "1-2163411"
        }
    ],
    "meta": {
        "app_id": "YOUR_APP_ID",
        "app_key": "YOUR_APP_KEY",
        "count": 1,
        "origin": "Consumer Events API",
        "yle_id": "1-2163411"
    },
    "notifications": []
}

Request to this endpoint initiates an identification process for the currently logged in Yle Tunnus user, by strongly authenticating the user via an identity prodivder. This endpoint is meant to be used from a browser context.

Yle Tunnus user is identified by Yle login cookie, which must be present in the request.

Performance test results for this endpoint can be found here.

URL Parameters

Response

200 OK on success

Response body is a JSON object that contains a redirectTo attribute.

• redirectTo is an URL that points to the identity provider. To continue with the identification process, browser should be redirected to this URL. The URL must not be modified by the client.

Redirect URI is not provided as a regular 302 Redirect to allow the client to display some information to the end user, before the redirect takes place.

Example response body

{
  "redirectTo": "https://my-identity-provider.fi/SAML2/foobar"
}

400 Bad Request when returnToUrl is missing or invalid

401 Unauthorized when login cookie is missing or invalid

Request to this endpoint returns the status of an identification process that was initiated by calling the /v1/authenticate endpoint.

Yle Tunnus user is identified by Yle login cookie, which must be present in the request.

Performance test results for this endpoint can be found here.

Path parameters

Response

200 OK on success

Response body is a JSON object that contains a status attribute and an optional residenceInFinland attribute.

• status is one of the following:
  • "pending", if the identification process is still in progress
  • "failure", when the idenfication process did not complete successfully
  • "success", when the identification process has completed successfully
• residenceInFinland attribute exists when the status attribute is "success", in which case it is either:
  • true when user’s home municipality was confirmed to be located in Finland
  • false when user’s home municipality was not in Finland

Example response bodies

{
  "status": "pending"
}

{
  "status": "success",
  "residenceInFinland": true
}

{
  "status": "failure"
}

404 Not Found when an identification process was not found with the given event ID

401 Unauthorized when login cookie is missing or invalid

Retrieves the data of a single image by its ID.

Parameters

Response

200 OK on success

Response is a JSON document that contains the data of the requested image. Please refer to Cloudinary documentation (Browse Resources -> Details of a single resource) for more detailed description of the image attributes.

400 Bad Request if request was invalid or it could not be processed successfully

404 Not Found If an image is not found with the given id

Retrieve a single JSON document (that is not part of a collection).

If the document is an array, you can select a slice from it by using the limit and offset parameters.

Parameters

Response

200 OK on success

404 Not Found if the document doesn’t exist

Examples

Retrieve a stored JSON document

$ curl -XGET "https://json-storage.api.yle.fi/v1/storage/areenan-suosituimmat?app_id=YOUR_ADD_ID&app_key=YOUR_APP_KEY"
["Docventures", "A-Studio", "Prisma", "Uutisvuoto", "Kioski"]

Retrieve a stored JSON document (with limit)

$ curl -XGET "https://json-storage.api.yle.fi/v1/storage/areenan-suosituimmat?limit=3&app_id=YOUR_ADD_ID&app_key=YOUR_APP_KEY"
["Docventures", "A-Studio", "Prisma"]

Retrieve a stored JSON document (with limit and offset)

$ curl -XGET "https://json-storage.api.yle.fi/v1/storage/areenan-suosituimmat?limit=3&offset=1&app_id=YOUR_ADD_ID&app_key=YOUR_APP_KEY"
["A-Studio", "Prisma", "Uutisvuoto"]

Retrieve the JSON Schema of a single stored JSON document (that is not part of a collection).

Parameters

Response

200 OK on success

Response is a JSON object with data attribute that contains the schema JSON.

404 Not Found if the schema doesn’t exist

cURL example

curl "https://json-storage.api-test.yle.fi/v1/schema/areenan-suosituimmat?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

{"data":"{\"type\": \"array\"}"}

Retrieves the information of a collection.

Path parameters

Response

200 OK collection was created successfully

Response body contains a JSON object describing the collection (see example request below).

404 Not Found if the collection does not exist

Example request

$ curl -XGET "https://json-storage.api.yle.fi/v1/collection/ims-images?app_id=YOUR_ADD_ID&app_key=YOUR_APP_KEY"

{
  "documentCount": 1,
  "owner": "OTHER_APP_ID",
  "schema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "id": {
        "type": "string"
      }
    }
  }
}

Retrieves document from a collection.

Path parameters

Response

200 OK when successful

Response body contains the JSON document wrapped inside a data attribute.

404 Not Found if the document or collection does not exist

Examples

Get a JSON document

$ curl -XGET "https://json-storage.api.yle.fi/v1/collection/ims-images/document/33-123456?app_id=YOUR_ADD_ID&app_key=YOUR_APP_KEY"

Can be used to get location information.

Response

Possible keys in a successful response body can be one or more from the following: continent, country_code, region_code, asnum, eu.

200 OK on success

  {
    continent: "EU",
    country_code: "FI",
    asnum: "719",
    eu: true
  }

200 OK with an empty body ( {} ) if no location is found

cURL example

Get your current location

curl -XGET https://locations.api.yle.fi/v1/address/current?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Can be used to get location information by given IP address. Both IPv4 and IPv6 addresses are supported.

Response

Possible keys in a successful response body can be one or more from the following: country_code, continent, region_code, asnum, eu.

200 OK with a body containing location information on success

  {
    country_code: "FI",
    continent: "EU",
    asnum: "719",
    eu: true
  }

200 OK with an empty body ( {} ) if no location is found

400 Bad Request if the given IP address is invalid

cURL example

Get your current location

curl -XGET https://locations.api.yle.fi/v1/address/84.231.157.149?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Checks whether user is logged in and if user has successfully completed verification (meaning that the user is not likely a bot). Please note that the session expires may also be updated when this endpoint is called unless the refreshSession parameter is set to false.

Parameters

Request

The request must contain the ylelogin (or yletestlogin in the test environment) cookie to succeed.

Response

200 OK if user is logged in

{ "userId": "USERID",
  "username": "user@email.fi"
  "nick": "NICK",
  "nickUpdatedAt": "2018-08-22T09:58:09+0300",
  "verifications": [],
  "latestTermsOfServiceAccepted": true|false,
  "residenceInFinland": true|false,
  "initials": "US"}

verifications array contains a list of verification types that the user has successfully completed at some point. Currently the only supported verification type is 'sms'.

latestTermsOfServiceAccepted tells you if the latest Terms of Service has been accepted by the user.

The residenceInFinland attribute indicates whether the user’s municipality of residence is in Finland or not (as determined by Identification API). If the attribute is not present, the user has not verified their municipality of residence.

The initials attribute is generated from the username (email) and contains one or two letters. If for some reason initials cannot be generated from the email, the returned value will be “-“.

Note! If session has been created more than 24 hours ago and refreshSession is not set to false, session token will be updated using Set-Cookie header in response. Example:

Set-Cookie:ylelogin=YmUyNDUxMDQtYWNkNS20Y2QULTlHODAtOTY1YzliOWRjADkz; Domain=.yle.fi; HttpOnly; path=/; expires=Tue, 10 May 2016 04:32:43 GMT; secure

401 Unauthorized when user is not logged in

{"message": "The API call requires a valid session. Log in again", "errorCode": "no_session"}

Curl examples

$ curl --header 'Cookie: ylelogin=YOUR_VALID_LOGIN_COOKIE' "https://login.api.yle.fi/v1/user/login?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"

Check if given nick is available.

Query parameters

These parameters should be transmitted in query string.

Nick must be at least 2 and at most 50 characters long. It must match pattern ^[\w \d \- äöåÄÖÅÀÂÆÇÈÉÊËÌÍÎÏÒÓÔØÙÚÛÜàâæçèéêëìíîïòóôøùúûüÿĄąĆćĘꣳŃńŒœŚŜŠśŝšŸŹźŻż_]+$. Also, it must not begin with words anonyymi or anonym (case-insensitive) which are reserved for automatically generated nicks.

Request

The request must contain ylelogin cookie.

Response

200 OK if nick is available

{ "status": "OK" }

401 Unauthorized Request when user is not logged in

{"message": "The API call requires a valid session. Log in again","errorCode": "no_session"}

400 Bad Request Errors

The endpoint will return 400 error with specific errorCode when nick is already reserved or not a valid nick.

Example response:

{ "message": "Missing parameter 'nick'", "errorCode": "parameter_nick_is_missing" }

Possible error codes in the table below.

Examples

Check if a nick is available

curl -X GET --header 'Cookie: ylelogin=YOUR_VALID_LOGIN_COOKIE' 'https://login.api.yle.fi/v1/account/checkNickAvailability?nick=thisNickIsFree&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY'

Lists the number of registered users, as defined in the parameters.

Parameters

Filtering

Dates must be in format yyyy-MM-dd.

Other

Examples

Get total number of registered users

https://login.api.yle.fi/v1/stats/accounts?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

Response:

{
    "data":
    [
        {
            "count": 155717
        }
    ]
}

Get number of registered users in a single month

https://login.api.yle.fi/v1/stats/accounts?registered_after=2015-12-01&registered_before=2015-12-31&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

Response:

{
    "data":
    [
        {
            "count": 30614
        }
    ]
}

Get number of registered users by service

https://login.api.yle.fi/v1/stats/accounts?group_by=app_id&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

Response:

{
    "data":
    [
        {
            "registeredAppId": "5rMM3hDK",
            "count": 2562
        },
        {
            "registeredAppId": "6BeEWqbT",
            "count": 473
        },
        {
            "registeredAppId": "9EsTfMhL",
            "count": 11
        },
        {
            "registeredAppId": "hJzAsh68",
            "count": 6532
        },
    ]
}

Get number of registered users by service and registration date

https://login.api.yle.fi/v1/stats/accounts?group_by=app_id,registration_date&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

Response:

{
    "data":
    [
        {
            "registeredAppId": "5rMM3hDK",
            "data":
            [
                {
                    "registrationDate": "2015-12-01",
                    "count": 14
                },
                {
                    "registrationDate": "2015-12-02",
                    "count": 25
                },
                ...
            ]
        },
        ...
    ]
}

Check if given token is valid and available.

Query parameters

These parameters should be transmitted in query string.

Response

200 OK if token is available

{ "status": "OK" }

400 Bad Token Errors

The endpoint will return 400 error with specific errorCode when token is not available or has been expired.

Example response:

{"message":"Not a valid token","errorCode":"bad_token"}

Example

curl -X GET 'https://login.api.yle.fi/v1/account/checkToken?token=abcd1234&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY'

This endpoint is used to activate and log in an inactive user that has been initialized with a normal registration flow.

Body parameters

These parameters must be transmitted in the request body (not as query parameters). Remember to set the Content-Type: application/x-www-form-urlencoded; charset=utf-8 header.

Response

200 OK with an HTML body describing successful activation, if everything went well.

Example body:

<html>
<head>
  <meta http-equiv="refresh" content="0; url=https://tunnus.yle.fi/tervetuloa" />
  <title>Yle Tunnus</title>
</head>
<body>
Yle Tunnuksesi on aktivoitu.
</body>
</html>

401 Unauthorized with an HTML body describing the error, if token has been already used or is not found.

Example body:

<html>
<head>
  <title>Yle Tunnus</title>
</head>
<body>
Aktivointilinkkisi Yle Tunnuksessa on joko käytetty tai vanhentunut.
</body>
</html>

Returns list of users paired devices.

Parameters

The request must contain a ylelogin cookie.

For example:

curl -v -XGET --header 'Cookie: ylelogin=YOUR_VALID_LOGIN_COOKIE' 'https://login.api.yle.fi/v1/device?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY'

Response

200 OK

{
  "devices" : [{
    "id": "57baf0b1e4b016e39e4cfc86",
     "externalId": "8BF9BBE3-2EC8-4C82-A537-421184CC3F0A"
     "deviceName": "My AppleTV"
     "lastLogin": "2017-10-11T11:23:03Z"
  }]
}  

403 Unauthorized

DEPRECATED Will be removed in future versions. This endpoint is not in use, except by one auth-api client. Thus, a new similar endpoint has been implemented in auth-api that returns PPID sector specific ids. The new endpoint and its documentation have be found here

Returns a list of surrogate keys of users removed between a given time range. It is recommended to use a short time range, for example, between 5 to 15 minutes.

Parameters

Both start_time and end_time are mandatory parameters, and they must conform to full ISO 8601 format. They must be no more than 30 days apart, and start_time must occur before end_time.

Example query (without app_id and app_key parameters):

curl 'https://login.api.yle.fi/v2/accounts/removed?start_time=2018-01-01T10:00:00Z&end_time=2018-01-01T10:05:00Z'

Response

200 OK when request was successful

Body contains a JSON object with a list of removed user IDs, in the attribute removed_user_ids:

{
  "removed_user_ids": ["cf088b65e4b72b7c8381089a", "31ebf9cd8db642aa26e4ec93"]
}

400 Bad Request when start_time is greater than end_time, either time is invalid or missing, or the time difference is over 30 days

Exchange a temporary token to a session token.

If you call /v1/user/login with with_token=true, the response includes a temporary token that can be exchanged to a session token. This is intended to be used by the mobile applications that need to use header-based authentication.

Parameters

Response

200 OK if token exchange succeeded

{ "yleTunnus": "SESSION TOKEN" }

401 Unauthorized if the temporary token is invalid or expired

{ "message": "Temp token invalid", "errorCode": "token_invalid_or_expired" }

Used to get stream URL for media. The urls returned from this API are encrypted using the secret key associated with your application.

How to use

First, you need a mediaId. You can get that from Programs API by finding the item’s current publication event. It’s the type == 'OnDemandPublication' and temporalStatus == 'currently' one

Then, query playouts.json:

https://media.api.yle.fi/v1/MEDIAID/playouts.json?protocol=[HLS|HDS|PMD|RTMPE]&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

For example:

$ curl https://media.api.yle.fi/v1/6-35af958db127424fbf43694a14ece041/playouts.json?protocol=HLS&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY
{
  "notifications": {},
  "data": [
    {
          "multibitrate": true,
          "height": 396,
          "formatOf": "6-35af958db127424fbf43694a14ece041",
          "type": "VideoObject",
          "protectionType": "DEFAULT",
          "url": "CwAArk9txSGpZeJEf1PZV1+b9qt6Q65wtIr5UVINKzvV/GVYtYxGMCYnVkYYVocPWsDrk03trz91cdK9pXMbV5LdWi2/awoXyL64uHaZdeEWvU6fIZfnt1cGIWuHskl673ypyLUQAOJkViqo0D1UjOzthDn4GeupiuhT7mvY0Pjh1BxMZLssYQfjWfiWGshxjAHpZO1yL4fWqRwZcuo0Yd4t/dt0Kou2F/VjICkNtLQbx8vvw9vQe8HLjdp8hG+uo7qgyK2krhU7fIjRAuYgBp8ZEOQ/BsVaWu6MErSaVvc2WkWm1IGQrG08xppAG2BrNQ2nRHXGSOn65p2F86hEokiarINIrGzByVGfLjqL6A9GLE92D4NP2HV8jOKbHn85FRDYcaUXQzfnpk8uufPs69fUh2Cvv0c2MaMfwAoDNWs=",
          "subtitles": [],
          "protocol": "HLS",
          "live": false,
          "width": 704
        }
      ],
      "meta": {
        "id": "6-35af958db127424fbf43694a14ece041"
      }
    }
  ]
}

Now you can use your secret key to decrypt the url

$ node decrypt-url.js $SECRET $URL

To verify the URL works, you can copy paste it into QuickTime

NOTE: The URL decrypted from the above example response won’t work anymore. The links generated by Media API expire soon after they’ve been generated.

This endpoint is used to get download URL’s for medias set to be downloadable. URL’s are not encrypted in any way, and are downloadable as long as the media is viewable in Areena. Media is always served in the format that it is encoded in Mediakanta. By default this means that videos are in mp4-format and audios in mp3-format.

How to use

First, you need at least one mediaId that is set to be downloadable. You can get that from Programs API by finding the item’s current publication event. This endpoint can handle multiple id requests at the same time. In these cases you have to submit a comma separated list as the ids-parameter. You can also specify if you want to have video files that have hard subtitles included. This can be done by specifying hardsubtitles=[true|false] parameter. Default value for this is ‘false’.

Then, query downloads.json:

https://media.api.yle.fi/v1/downloads.json?ids=[comma-separated-list-of-ids]&hardsubtitles=[true|false]&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY

For example:

$ curl https://media.api.yle.fi/v1/downloads.json?ids=6-f8b88966fd394e5a8ee9914465cf32bd,6-18b6cf6756234cbc99e3bab359ef4fd4&hardsubtitles=true&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY
{
  meta: {
    ids: "6-f8b88966fd394e5a8ee9914465cf32bd,6-18b6cf6756234cbc99e3bab359ef4fd4",
    count: 2
  },
  data: [
    {
      id: "6-f8b88966fd394e5a8ee9914465cf32bd",
      type: "VideoObject",
      mediaObjects: [
        {
          audioBitrateKbps: 128,
          videoBitrateKbps: 650,
          width: 640,
          height: 360,
          hardsubtitle: {
            lang: "fi",
            type: "translation"
          },
          downloadLink: "http://areena-pdl-world.edgesuite.net/be/be937cb9b231257ce9f55cc2b9475ad6_634880.mp4"
        },
        {
          audioBitrateKbps: 48,
          videoBitrateKbps: 400,
          width: 480,
          height: 270,
          hardsubtitle: {
            lang: "fi",
            type: "translation"
          },
          downloadLink: "http://areena-pdl-world.edgesuite.net/be/be937cb9b231257ce9f55cc2b9475ad6_14746.mp4"
        },
        {
          audioBitrateKbps: 48,
          videoBitrateKbps: 400,
          width: 480,
          height: 270,
          hardsubtitle: {
            lang: "fi",
            type: "translation"
          },
          downloadLink: "http://areena-pdl-world.edgesuite.net/be/be937cb9b231257ce9f55cc2b9475ad6_200704.mp4"
        },
        {
          audioBitrateKbps: 128,
          videoBitrateKbps: 650,
          width: 640,
          height: 360,
          downloadLink: "http://areena-pdl-world.edgesuite.net/e9/e9331dc82142449b9b6131c90b74460f.mp4"
        }
      ]
    },
    {
      id: "6-18b6cf6756234cbc99e3bab359ef4fd4",
      type: "VideoObject",
      mediaObjects: [
        {
          audioBitrateKbps: 128,
          videoBitrateKbps: 1000,
          width: 704,
          height: 396,
          downloadLink: "http://areena-pdl-world.edgesuite.net/b2/b252b810baeb7b8e70d45525bf16834f_1001472.mp4"
        },
        {
          audioBitrateKbps: 128,
          videoBitrateKbps: 650,
          width: 640,
          height: 360,
          downloadLink: "http://areena-pdl-world.edgesuite.net/b2/b252b810baeb7b8e70d45525bf16834f_661504.mp4"
        },
        {
          audioBitrateKbps: 128,
          videoBitrateKbps: 400,
          width: 480,
          height: 270,
          downloadLink: "http://areena-pdl-world.edgesuite.net/b2/b252b810baeb7b8e70d45525bf16834f_404480.mp4"
        },
        {
          audioBitrateKbps: 48,
          videoBitrateKbps: 400,
          width: 480,
          height: 270,
          downloadLink: "http://areena-pdl-world.edgesuite.net/b2/b252b810baeb7b8e70d45525bf16834f_143360.mp4"
        }
      ]
    }
  ],
  notifications: { }
}

NOTE

It is possible to define downloadable filename by setting a ‘filename’-parameter to the Akamai download URL. Like this: http://areena-pdl-world.edgesuite.net/b2/b252b810baeb7b8e70d45525bf16834f_143360.mp4?filename=renamedfile.mp4

Parameters

• Please note that exactly one of the parameters “subject” or “related_content” is required.

Response

200 OK on success

{
  "meta": {
    "subject": "18-4498",
    "language": "sv",
    "count": 222
  },
  "data":[
    { "type": "Article", "id": "7-849353" },
    { "type": "Article", "id": "7-848623" },
    ...
  ]
}

To get title and other details for a piece of content, query the API correspondingto content type. For example, in the above example, you could query Articles API for IDs 7-849353 and 7-848623.

400 Bad Request if required parameters are missing

You need to specify language. It is currently not possible to list content in all languages.

cURL example

List all Swedish content about Formula 1 (concept id 18-4498)

curl -XGET https://meta.api.yle.fi/v1/content.json?subject=18-4498&language=sv&app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Finds concepts from Meta-api only (concept_search.json searches also external ontology services)

Parameters

Either yle_id, subjectof, exactmatch or combination q with lang (or language) parameter is required.

Response

200 OK on success

{
  "meta": {
    "subjectof": "7-846362",
    "count": 4
  },
  "data": [
    {
      "id": "18-4428",
      "alternativeIds": ["18-5323", "18-3455"],
      "types": ["Concept"],
      "exactMatch": ["finto:http://www.yso.fi/onto/koko/p7135"],
      "title": { "fi": "autourheilu", "sv": "bilsport", "en": "car sport"},
      "description": {
        "fi": "Urho Kaleva Kekkonen oli suomalainen poliitikko",
        "sv": "Urho Kaleva Kekkonen, född 3 september 1900",
        "en": "Urho Kaleva Kekkonen was a Finnish politician"
      },
      "imageId": "13-18-4428-1",
      "updated": "2017-08-27T19:37:15+03:00"
    },
    {
      "id": "18-4431",
      "alternativeIds": [],
      "types": ["Organization", "Concept", "Agent"],
      "exactMatch": ["freebase:/m/02xz2"],
      "title": { "fi": "Formula 1", "sv": "Formel 1" },
      "description": {
        "fi": "formula",
        "sv": null
      },
      "updated": "2017-08-27T19:37:15+03:00"
    },
    ...
  ]
}

400 Bad Request when required parameters are missing

Exactly one of the parameters subjectof, exactmatch, q or yle_id must be provided, and language must be valid.

cURL example

List all concepts for svenska.yle.fi article 7-846362

https://meta.api.yle.fi/v1/concepts.json?subjectof=7-846362&app_key=YOUR_APP_ID&app_id=YOUR_APP_KEY

Known issues

This endpoint can suffer from increased response times nightly at 01:30 (Finnish time). This is because of a scheduled maintenance operation that is executed in the database at that time. Duration of this operation is usually about 20-30 seconds.

Search concepts from meta-api AND external ontology services using free-text search.

Currently concepts are queried from Finto, the Meta API database and Wikidata. Only concepts considered valid by Meta API are returned. Also returns the number of times (contentHits) the concept is used in Yle content (articles etc.). A score (a measure of how well the concept matches the query; on a scale of 0-1000) is included in the response when the debug parameter is set to true.

The optional lang parameter can be used to specify in which languages to query the external ontologies and the Meta API database. Please note that not all sources support all languages (Meta API currently only supports fi and sv, and Wikidata will only be queried in the first given language).

Parameters

Response

200 OK is success

{ "meta: {
  "q: "kekkonen",
  "timeout.secs": 3,
  "services": {
    "finto": {
      "requestStatus": "ok"
    },
    "wikidata": {
      "requestStatus": "ok"
    },
    "yle": {
      "requestStatus": "ok"
    }
  }
}, "data": [ {
  "type": "TagResult",
  "score": 25.197794,
  "title": "Urho Kekkonen",
  "disambiguationHint": "Poliitikko",
  "lang": "fi",
  "exactMatch": [
    "freebase:/m/07w5w"
  ],
  "types": [
    "Concept",
    "Person",
    "Agent"
  ],
  "contentHits": 14,
  "vocabulary": "freebase"
  }
...]}

400 Bad Request when required parameters are missing

cURL example

List all concepts for ‘Kekkonen’

https://meta.api.yle.fi/v1/concept_search.json?q=kekkonen&lang=fi&app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Known issues

This endpoint can suffer from increased response times nightly at 01:30 (Finnish time). This is because of a scheduled maintenance operation that is executed in the database at that time. Duration of this operation is usually about 20-30 seconds.

DEPRECATED!

Use the Get content endpoint instead.

Can be used to produce needed tracking variable for media..

Parameters

Response

200 OK on success

{
    "data": {
        "category": "nettiradio",
        "ns_st_dt": "20141201",
        "ns_st_ty": "liveradio",
        "ns_st_st": "yle x3m",
        "yle_ss_mediaid": "10-18",
        "yle_language": "sv",
        "ns_st_cl": "0",
        "ns_st_el": "0",
        "ns_st_li": "1",
        "yle_metrics_api_data_version": "v2.0",
        "ns_st_ep": "20141201",
        "content_type": "liveradio",
        "ns_st_pr": "nettiradio.liveradio.yle x3m.null",
        "countername": "nettiradio.liveradio.yle x3m.null",
        "ns_st_pl": "nettiradio.liveradio.yle x3m.null.20141201"
    }
}

400 Bad Request if required parameters are missing

cURL example

Get comScore params for service Yle X3m and media 10-18

curl -XGET https://metrics.api.yle.fi/v2/labels/stream/services/yle-x3m/10-18.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Details about service

curl -XGET https://programs.api.yle.fi/v1/services/yle-x3m.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Can be used to produce needed tracking variable for media in comScore format.

Parameters

Response

200 OK on success

{
    "data": {
        "category": "nettiradio",
        "ns_st_dt": "20141201",
        "ns_st_ty": "liveradio",
        "ns_st_st": "yle x3m",
        "yle_ss_mediaid": "10-18",
        "yle_language": "sv",
        "ns_st_cl": "0",
        "ns_st_el": "0",
        "ns_st_li": "1",
        "yle_metrics_api_data_version": "v2.0",
        "ns_st_ep": "20141201",
        "content_type": "liveradio",
        "ns_st_pr": "nettiradio.liveradio.yle x3m.null",
        "countername": "nettiradio.liveradio.yle x3m.null",
        "ns_st_pl": "nettiradio.liveradio.yle x3m.null.20141201"
    }
}

400 Bad Request if required parameters are missing

cURL example

Get comScore params for service Yle X3m and media 10-18

curl -XGET https://metrics.api.yle.fi/v2/labels/stream/services/yle-x3m/10-18/comscore.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Details about service

curl -XGET https://programs.api.yle.fi/v1/services/yle-x3m.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Can be used to produce needed tracking variable for media in Akamai Sola format.

Parameters

Response

200 OK on success

{
    "data": {
        "title": "nettiradio.liveradio.yle x3m",
        "category": "nettiradio",
        "show": "20141201.yle x3m",
        "contentLength": "0",
        "contentType": "liveradio"
    }
}

400 Bad Request if required parameters are missing

cURL example

Get comScore params for service Yle X3m and media 10-18

curl -XGET https://metrics.api.yle.fi/v2/labels/stream/services/yle-x3m/10-18/akamai-sola.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Details about service

curl -XGET https://programs.api.yle.fi/v1/services/yle-x3m.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Can be used to produce needed tracking variable for media in multiple formats.

Parameters

Query parameters

Response

200 OK on success

{
    "data": [
        {
            "comscore": {
                "category": "nettiradio",
                "ns_st_dt": "20141201",
                "ns_st_ty": "liveradio",
                "ns_st_st": "yle x3m",
                "yle_ss_mediaid": "10-18",
                "yle_language": "sv",
                "ns_st_cl": "0",
                "ns_st_el": "0",
                "ns_st_li": "1",
                "yle_metrics_api_data_version": "v2.0",
                "ns_st_ep": "20141201",
                "content_type": "liveradio",
                "ns_st_pr": "nettiradio.liveradio.yle x3m.null",
                "countername": "nettiradio.liveradio.yle x3m.null",
                "ns_st_pl": "nettiradio.liveradio.yle x3m.null.20141201"
                }
        },
        {
            "akamai-sola": {
                "title": "nettiradio.liveradio.yle x3m",
                "category": "nettiradio",
                "show": "20141201.yle x3m",
                "contentLength": "0",
                "contentType": "liveradio"
            }
        }
    }]
}

400 Bad Request if required parameters are missing

cURL example

Get comScore and akamai-sola params for service Yle X3m and media 10-18

curl -XGET https://metrics.api.yle.fi/v2/labels/stream/services/yle-x3m/10-18/analytics.json?formats=comscore,akamai-sola&app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Details about service

curl -XGET https://programs.api.yle.fi/v1/services/yle-x3m.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Can be used to produce needed tracking variables for media.

Parameters

Response

200 OK on success

{
    "data": {
        "ns_st_pl": "draama.vod.yle tv1.top of the lake.20140212.4",
        "ns_st_ep": "20140212.4",
        "ns_st_pr": "draama.vod.yle tv1.top of the lake",
        "ns_st_dt": "20140212",
        "ns_st_ty": "vod",
        "ns_st_st": "yle tv1",
        "countername": "draama.vod.yle tv1.top of the lake",
        "content_type": "vod",
        "yle_dayssincepublish": "14",
        "yle_language": "en",
        "yle_ss_mediaid": "6-073b0b2f5352460da3ce21beac78ed5e",
        "yle_ss_ohjusid": "1-2127750",
        "yle_ss_prodnumber": "55162204000",
        "yle_title": "top of the lake",
        "yle_stickytitle": "top of the lake",
        "category": "draama",
        "ns_st_cl": "3508000",
        "ns_st_el": "3508000",
        "yle_truelength": "3508000",
        "ns_st_ci": "16-1-0798588",
        "yle_metrics_api_data_version": "v2.1",
        "ns_st_ge": "ulkomainen fiktio",
        "yle_genreid": "6",
        "yle_alternativeid": "16-1-0798588",
        "yle_category": "sarjatjaelokuvat;jannitys;ulkomaisetsarjat",
        "fp_bd": "20140212",
        "fp_ty": "video_tv_program",
        "fp_clnr": "20001",
        "fp_prod_id": "na",
        "fp_ch": "fp101",
        "yle_productfamily": "top of the lake"
    }
}

400 Bad Request if required parameters are missing

cURL example

Get comScore params for program Top Of The Lake and publication event 4-3245278

curl -XGET https://metrics.api.yle.fi/v2/labels/stream/programs/1-376/4-3245278.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Can be used to produce needed tracking variables for media.

Parameters

Response

200 OK on success

{
    "data": {
        "ns_st_pr": "viihde.vod.yle tv2.pasila",
        "ns_st_ep": "20140123",
        "ns_st_pl": "viihde.vod.yle tv2.pasila.20140123",
        "ns_st_dt": "20140123",
        "ns_st_ty": "vod",
        "ns_st_st": "yle tv2",
        "countername": "viihde.vod.yle tv2.pasila",
        "content_type": "vod",
        "yle_dayssincepublish": "312",
        "yle_language": "fi",
        "yle_ss_mediaid": "6-09c3f94215c046bfbab8515f5d2b23dc",
        "yle_ss_ohjusid": "1-376",
        "yle_ss_prodnumber": "54454005000",
        "yle_title": "pasila",
        "category": "viihde",
        "ns_st_cl": "1603000",
        "ns_st_el": "1603000",
        "yle_truelength": "1603000",
        "ns_st_ci": "1-376",
        "yle_metrics_api_data_version": "v2.1",
        "ns_st_ge": "viihde/kevyt musiikki/reality",
        "yle_genreid": "10",
        "yle_alternativeid": "16-1-0655053",
        "yle_productfamily": "pasila"
    }
}

400 Bad Request if required parameters are missing

cURL example

Get comScore params for program Pasila and publication event 4-3245278

curl -XGET https://metrics.api.yle.fi/v2/labels/stream/programs/1-376/4-3245278/comscore.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Can be used to produce needed tracking variables for media.

Parameters

Response

200 OK on success

{
    "data": {
        "title": "20140123.viihde.n/a.yle tv2.pasila",
        "category": "viihde",
        "show": "viihde.n/a.yle tv2.",
        "contentLength": "1603000",
        "contentType": "n/a"
    }
}

400 Bad Request if required parameters are missing

cURL example

Get Akamai Sola params for program Pasila and publication event 4-3245278

curl -XGET https://metrics.api.yle.fi/v2/labels/stream/programs/1-376/4-3245278/akamai-sola.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Can be used to produce needed tracking variables for media in multiple formats.

Parameters

Query parameters

Response

200 OK on success

{
    "data": [{
        "comscore": {
            "ns_st_pr": "viihde.vod.yle tv2.pasila",
            "ns_st_ep": "20140123",
            "ns_st_pl": "viihde.vod.yle tv2.pasila.20140123",
            "ns_st_dt": "20140123",
            "ns_st_ty": "vod",
            "ns_st_st": "yle tv2",
            "countername": "viihde.vod.yle tv2.pasila",
            "content_type": "vod",
            "yle_dayssincepublish": "312",
            "yle_language": "fi",
            "yle_ss_mediaid": "6-09c3f94215c046bfbab8515f5d2b23dc",
            "yle_ss_ohjusid": "1-376",
            "yle_ss_prodnumber": "54454005000",
            "yle_title": "pasila",
            "category": "viihde",
            "ns_st_cl": "1603000",
            "ns_st_el": "1603000",
            "yle_truelength": "1603000",
            "ns_st_ci": "1-376",
            "yle_metrics_api_data_version": "v2.1",
            "ns_st_ge": "viihde/kevyt musiikki/reality",
            "yle_genreid": "10",
            "yle_alternativeid": "16-1-0655053",
            "yle_productfamily": "pasila"
        }
    },
    {
        "akamai-sola": {
            "title": "20140123.viihde.n/a.yle tv2.pasila",
            "category": "viihde",
            "show": "viihde.n/a.yle tv2.",
            "contentLength": "1603000",
            "contentType": "n/a"
        }
    }]
}

400 Bad Request if required parameters are missing

cURL example

Get comScore and akaimai-sola params for program Pasila and publication event 4-3245278

curl -XGET https://metrics.api.yle.fi/v2/labels/stream/programs/1-376/4-3245278/analytics.json?formats=comscore,akamai-sola&app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

Can be used to produce needed tracking variables for an article or multiple articles.

Parameters

Response

200 OK on success

{
    "data": {
        "3-9905944": {
            "yle_pubtime": "06-42",
            "yle_pubweek": "2017-43",
            "yle_language": "fi",
            "yle_contenttype": "article",
            "yle_organization": "1441-ajankohtaiset",
            "yle_pub": "2017-10-29",
            "yle_pagetype": "newscontent-news",
            "yle_mediatype": "image",
            "yle_articleid": "9905944",
            "countername": "tekniikka.posti_paljastaa_mainostajille_milloin_muutat_ja_trafi_sen_milloin_tarvitset_uuden_auton.sivu",
            "yle_stickytitle": "posti_paljastaa_mainostajille_milloin_muutat_ja_trafi_sen_milloin_tarvitset_uuden_auton",
            "yle_artby": "rigatsa",
            "yle_topic": "tekniikka",
            "yle_dayssincepublish": "1",
            "yle_system": "escenic",
            "yle_origin": "uutiset",
            "yle_id": "3-9905944",
            "yle_schemaid": "3"
        }
    }
}

400 Bad Request if required parameters are missing

cURL example

curl -XGET https://metrics.api.yle.fi/v2/labels/pageload/articles.json?id=3-9905944&app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID

List publications for an event schedule. An event is defined by one or more concepts.
The requested concepts and other filtering criteria are given as request parameters.

This API is so called id-API meaning that the responses don’t contain rich data but basically only IDs of result objects.

OVP = online video platfrom for program meta data.

Parameters

Response

200 OK on success

{
  "meta": {
    "count": "2"
  },
  "data": [
    {
      "id": "4-123",
      "type": "ScheduledTransmission",
      "content": {
        "id": "1-1456",
        "series": {
          "id": "1-1789"
        }
      }
    },
    {
      "id": "4-456",
      "type": "ScheduledTransmission",
      "content": {
        "id": "1-2456",
        "series": {
          "id": "1-2789"
        }
      }
    }
  ]
}

List current publications by concept(s)
The requested concepts and other filtering criteria are given as request parameters.

This API is so called id-API meaning that the responses don’t contain rich data but basically only IDs of result objects.

OVP = online video platfrom for program meta data.

Parameters

Response

200 OK on success

{
  "meta": {
    "count": "2"
  },
  "data": [
    {
      "id": "4-123",
      "type": "ScheduledTransmission",
      "content": {
        "id": "1-1456",
        "series": {
          "id": "1-1789"
        }
      }
    },
    {
      "id": "4-456",
      "type": "ScheduledTransmission",
      "content": {
        "id": "1-2456",
        "series": {
          "id": "1-2789"
        }
      }
    }
  ]
}

List future publications by concept(s).
The requested concepts and other filtering criteria are given as request parameters.

This API is so called id-API meaning that the responses don’t contain rich data but basically only IDs of result objects.

OVP = online video platfrom for program meta data.

Parameters

Response

200 OK on success

{
  "meta": {
    "count": "2"
  },
  "data": [
    {
      "id": "4-123",
      "type": "ScheduledTransmission",
      "content": {
        "id": "1-1456",
        "series": {
          "id": "1-1789"
        }
      }
    },
    {
      "id": "4-456",
      "type": "ScheduledTransmission",
      "content": {
        "id": "1-2456",
        "series": {
          "id": "1-2789"
        }
      }
    }
  ]
}

Returns series and single programs that belong to the package in alphabetical order, sorted by title.

Parameters

Check https://packages.api.yle.fi/swagger/index.html for details.

Returns episodes and single programs that belong to package in order of expiry, i.e. earliest expiration date first.

Parameters

Check https://packages.api.yle.fi/swagger/index.html for details.

Returns package’s recommendations, followed by the package’s most popular series and single programs in popularity order, i.e. recommendations.json + popular.json without duplicates.

Parameters

Check https://packages.api.yle.fi/swagger/index.html for details.

Returns package’s broadcasts and webcasts that start in the future, earliest first.

Parameters

Check https://packages.api.yle.fi/swagger/index.html for details.

Returns series and single programs that belong to package in reverse chronological order, i.e. latest first.

Parameters

Check https://packages.api.yle.fi/swagger/index.html for details.

Returns the most popular programs and series that belong to package, most popular first.

Parameters

Check https://packages.api.yle.fi/swagger/index.html for details.

Returns package’s recommendations. Recommendations are hand-picked content that are most relevant to that package at any given moment.

Parameters

Check https://packages.api.yle.fi/swagger/index.html for details.

General

Yle Areena uses packages for organizing content so that end users could find relevant content easily. Packages has few different ways content is attached to them.

Genres

Package might have one or more classifications attached to it. For example there might be Package for Forest. That package then could have classifications ‘nature’ and ‘animals’ included and maybe a ‘news content’ excluded from it. Then when you are requesting items that belong to that Package you get all content that have nature or animals classification in it but is not considered to be news.

Recommendations

There is also recommended content in most of the packages. Those recommendations are hand-picked by Yle staff. Picked items are most relevant content for that package at any time. Those recommendations might change or priorities between items might change multiple times a day depending how much new content is coming out.

Relations

Packages may also have seeAlso relations to other packages. So for example ‘Movie package’ could have a seeAlso relation to ‘Finnish movies’ and ‘Foreign movies’ packages.

GET Package by id.

Returns basic information about package by id.

Parameters and details.

Check https://packages.api.yle.fi/swagger/index.html for details.

Returns package’s relations to other packages. Package might have different relation types (SeeAlso and Narrower). SeeAlso is used to relate similar packages to each other. Narrower is used to indicate a sub-package relation.

Parameters

Check https://packages.api.yle.fi/swagger/index.html for parameters.

Returns a list of available packages from Packaging-api.

Parameters

Check https://packages.api.yle.fi/swagger/index.html for details.

Returns names of performers played in service.

Query parameters

Response

200 OK on success

Everything went OK. Body contains all performer names in data array matching given performer_prefix.

Response example:

{
  "meta": {
    "service": "ylex",
    "limit": 50,
    "offset": 0,
    "performer_prefix": "pap"
  },
  "data": [
    "PAPA ROACH",
    "PAPERI T"
  ]
}

400 Bad Request invalid parameters

Invalid request parameters. Do not retry the request without fixing the problems with the request parameters.

500 Internal server error

Unexpected error occured. You can try retrying the request in a while.

cURL example

curl "http://playlist.api-test.yle.fi/v1/performers.json?service=ylex&performer_prefix=me&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"
{
  "meta": {
      "limit": 50,
      "offset": 0,
      "performer_prefix": "me",
      "service": "ylex"
  },
  "data": [
      "ME & MY",
      "MEANWHILE",
      "MEAT LOAF",
      "MEEK MILL",
      "MEGADETH",
      "MEGAPHONE STATE",
      "MEGHAN TRAINOR",
      "MELANIE C",
      "MELODIE MC",
      "MEREDITH BROOKS",
      "METALLICA",
      "METRO STATION",
      "MEW"
  ]
}

Returns playout events of service sorted descending by startTime.

Query parameters

Response

200 OK on success

Everything went OK. Body contains all playout events in data array matching given service.

400 Bad Request invalid parameters

Invalid request parameters. Do not retry the request without fixing the problems with the request parameters.

500 Internal server error

Unexpected error occured. You can try retrying the request in a while.

cURL example

Note the limit param, these jsons can be huge. By default 50 latest events are returned.

curl "http://playlist.api-test.yle.fi/v1/playout_events.json?service=ylex&limit=2&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"
{
	"meta": {
		"offset": 0,
		"limit": 2,
		"service": "ylex"
	},
	"data": [{
		"partOf": {
			"radiomanId": "12-1025-4-119368",
			"type": "RadioProgram",
			"title": {
				"fi": "Poikelus ja Hätönen"
			}
		},
		"service": "ylex",
		"startTime": "2017-09-13T14:47:47+0300",
		"endTime": "2017-09-13T14:51:24+0300",
		"type": "NowPlaying",
		"content": {
			"playoutEventCount": 137,
			"duration": "PT217S",
			"performer": [{
				"name": "BIFFY CLYRO",
				"type": "agent"
			}],
			"radiomanId": "12-1025-2-17776",
			"type": "MusicRecording",
			"title": {
				"unknown": "Re-arrange"
			}
		}
	}, {
		"partOf": {
			"radiomanId": "12-1025-4-119368",
			"type": "RadioProgram",
			"title": {
				"fi": "Poikelus ja Hätönen"
			}
		},
		"service": "ylex",
		"startTime": "2017-09-13T14:42:50+0300",
		"endTime": "2017-09-13T14:46:27+0300",
		"type": "NowPlaying",
		"content": {
			"playoutEventCount": 19,
			"duration": "PT217S",
			"performer": [{
				"name": "ANNA PUU",
				"type": "agent"
			}],
			"radiomanId": "12-1025-2-18668",
			"type": "MusicRecording",
			"title": {
				"unknown": "Nälkäinen sydän"
			}
		}
	}]

Returns information about songs played in service. Data includes, but is not limited to, lates playout event for song and total playout count.

Query parameters

Response

200 OK on success

Everything went OK. Body contains all songs with playout count matching query.

400 Bad Request invalid parameters

Invalid request parameters. Do not retry the request without fixing the problems with the request parameters.

500 Internal server error

Unexpected error occured. You can try retrying the request in a while.

cURL example

curl "http://playlist.api-test.yle.fi/v1/songs.json?service=ylex&performer_name=METALLICA&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"
{
	"meta": {
		"offset": 0,
		"limit": 50,
		"service": "ylex",
		"performer_name": "METALLICA"
	},
	"data": [{
		"lastPlayoutEvent": {
			"partOf": {
				"radiomanId": "12-1025-4-103750",
				"type": "RadioProgram",
				"title": {
					"fi": "Parasta ennen!"
				}
			},
			"service": "ylex",
			"startTime": "2016-09-16T21:35:18+0300",
			"endTime": "2016-09-16T21:41:43+0300",
			"type": "NowPlaying"
		},
		"playoutEventCount": 2,
		"duration": "PT385S",
		"performer": [{
			"name": "METALLICA",
			"type": "agent"
		}],
		"radiomanId": "12-1025-2-1560",
		"type": "MusicRecording",
		"title": {
			"unknown": "NOTHING ELSE MATTERS"
		}
	}, {
		"lastPlayoutEvent": {
			"partOf": {
				"radiomanId": "12-1025-4-102181",
				"type": "RadioProgram",
				"title": {
					"fi": "YleX Kesätoiveet"
				}
			},
			"service": "ylex",
			"startTime": "2016-07-12T18:49:25+0300",
			"endTime": "2016-07-12T18:54:01+0300",
			"type": "NowPlaying"
		},
		"playoutEventCount": 3,
		"duration": "PT276S",
		"performer": [{
			"name": "METALLICA",
			"type": "agent"
		}],
		"radiomanId": "12-1025-2-37",
		"type": "MusicRecording",
		"title": {
			"unknown": "WHISKEY IN THE JAR"
		}
	}, {
		"lastPlayoutEvent": {
			"partOf": {
				"radiomanId": "12-1025-4-98660",
				"type": "RadioProgram",
				"title": {
					"fi": "Parasta ennen!"
				}
			},
			"service": "ylex",
			"startTime": "2016-03-18T21:20:16+0200",
			"endTime": "2016-03-18T21:29:32+0200",
			"type": "NowPlaying"
		},
		"playoutEventCount": 1,
		"duration": "PT556S",
		"performer": [{
			"name": "METALLICA",
			"type": "agent"
		}],
		"radiomanId": "12-1025-2-927",
		"type": "MusicRecording",
		"title": {
			"unknown": "THE UNFORGIVEN"
		}
	}, {
		"lastPlayoutEvent": {
			"partOf": {
				"radiomanId": "12-1025-4-82658",
				"title": {
					"fi": "YleX Jatkot"
				},
				"type": "RadioProgram"
			},
			"service": "ylex",
			"startTime": "2015-03-10T20:09:52+0200",
			"endTime": "2015-03-10T20:15:24+0200",
			"type": "NowPlaying"
		},
		"playoutEventCount": 2,
		"duration": "PT332S",
		"performer": [{
			"name": "METALLICA",
			"type": "agent"
		}],
		"radiomanId": "12-1025-2-353",
		"title": {
			"unknown": "ENTER SANDMAN"
		},
		"type": "MusicRecording"
	}]
}

Returns all features and their data for a given service.

URL parameters

NOTE! Filtering byt field value does not support other than “string” types at the moment

Response

Example request

curl "https://profiles.api.yle.fi/v1/api/USER_ID/SERVICE_ID?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" \
  --cookie "ylelogin=COOKIE_VALUE"

200 OK on success

{"feature1": [{"id": "1234567",
               "dataItemName": "foo"} ...],
 "feature2": [],
 ...}

400 Bad Request if any serviceId does not match existing data

401 Unauthorized when cookie is not valid or missing

Returns an array of all data items in a feature.

URL parameters

NOTE! Filtering by field values that aren’t “string” types requires a json-schema to function correctly.

Response

Example request

curl "https://profiles.api.yle.fi/v1/api/USER_ID/SERVICE_ID/FEATURE_ID?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" \
  --cookie "ylelogin=COOKIE_VALUE"

200 OK on success

[
    {"id": "fFSFsdF9sdfj9098329rhfHNSDJKvSNFSjFK",
     "dataItemName": "foo",
     ...},
    {"id": "vndHFDSFIEho344nfkjVNKSJOFI2384scnjd",
     ...}
]

400 Bad Request if any serviceId or featureId does not match existing data

401 Unauthorized when cookie is not valid or missing

Returns a single item with the given ID.

URL parameters

Response

Example request

curl "https://profiles.api.yle.fi/v1/api/USER_ID/SERVICE_ID/FEATURE_ID/DATA_ID?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" \
  --cookie "ylelogin=COOKIE_VALUE"

200 OK on success

{"id": "fFSFsdF9sdfj9098329rhfHNSDJKvSNFSjFK",
 "dataItemName": "foo",
 ...}

400 Bad Request if any serviceId or featureId does not match existing data

401 Unauthorized when cookie is not valid or missing

Returns all features and their data for a given service.

URL parameters

Response

Example request

curl "https://profiles.api.yle.fi/v2/api/SERVICE_ID?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" \
  --cookie "ylelogin=COOKIE_VALUE"

200 OK on success

{"feature1": [{"id": "1234567",
               "dataItemName": "foo"} ...],
 "feature2": [],
 ...}

400 Bad Request if any serviceId does not match existing data

401 Unauthorized when cookie is not valid or missing

Returns an array of all data items in a feature.

URL parameters

Response

Example request

curl "https://profiles.api.yle.fi/v2/api/SERVICE_ID/FEATURE_ID?app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY" \
  --cookie "ylelogin=COOKIE_VALUE"

200 OK on success

[
    {"id": "fFSFsdF9sdfj9098329rhfHNSDJKvSNFSjFK",
     "dataItemName": "foo",
     ...},
    {"id": "vndHFDSFIEho344nfkjVNKSJOFI2384scnjd",
     ...}
]

400 Bad Request if any serviceId or featureId does not match existing data

401 Unauthorized when cookie is not valid or missing