YLE API

GET /v1/programs/items.json Search programs, clips and episodes

Returns a collection of items (programs, episodes or clips) matching a specified query.

Parameters

NameDescription
idReturns items containing the specified ID. Multiple IDs can be passed as a comma separated list.
typeReturns items matching the given type. E.g. All clips(tv and radio): "/v1/items.json?type=clip", all radioprograms and radioclips: "/v1/items.json?type=radiocontent", all tvprograms: "/v1/items.json?type=tvprogram". Allowed values for type are: "program", "clip", "tvcontent", "tvprogram", "tvclip", "radiocontent", "radioprogram", "radioclip"
qReturns items matching the given keyword. E.g. Items matching search criteria \"muumi\": /v1/items.json?q=muumi
mediaobjectReturns items according to media type (video or audio). E.g. All audio objects: "/v1/items.json?mediaobject=audio". Allowed values are: "audio" and "video".
categoryReturns items linked to a specified category. Multiple category IDs can be passed as a comma separated list.
seriesReturns items containing the given series ID. Multiple IDs can be passed as a comma separated list.
availabilityReturns items matching the given availability status. \"ondemand\": returns items whose ondemand publication is currently valid and media object is available. \"future-ondemand\" returns items will become available on demand in the future. \"future-scheduled\" return items that will be broadcasted in the future. \"in-future\" returns the items that will either be broadcasted or become available as on demand in the future. Allowed values are: "ondemand", "future-ondemand", "future-scheduled" and "in-future".
downloadableReturns items that can be downloaded (and not just streamed). If this parameter is used, the value of this parameter must be 'true'.
languageReturns items with audio track or subtitle language matching the given language. Allowed values are "fi" and "sv".
regionReturns items that contain a publication event with the given region. Allowed values are "fi" and "world".
serviceReturns items containing the given service.
publisherReturns items originally published by the given service.
contentprotectionReturns items that contain a publication event with the content protection. Multiple content protection IDs can be passed as a comma separated list.
orderReturns items in specified order. Allowed order parameters are:
  • "playcount.6h:asc",
  • "playcount.6h:desc",
  • "playcount.24h:asc",
  • "playcount.24h:desc",
  • "playcount.week:asc",
  • "playcount.week:desc",
  • "playcount.month:asc",
  • "playcount.month:desc",
  • "publication.starttime:asc",
  • "publication.starttime:desc",
  • "publication.endtime:asc",
  • "publication.endtime:desc",
  • "updated:asc",
  • "updated:desc"
  • limitSets limit for the size of the returned collection
    offsetSets offset for the collection

    Response

    200 OK on success

    Response contains a JSON document with programs. Maximum number of programs returned is limited by limit parameter.

    400 Bad Request if parameters have illegal values

    cURL example

    Free text search example

    curl -XGET "https://external.api.yle.fi/v1/programs/items.json?q=muumit&limit=1&app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID"
    
    {
        "data": [
    	{
    	    "alternativeId": [
    		"12-1022-4-253311"
    	    ],
    	    "audio": [
    		{
    		    "format": [
    			{
    			    "inScheme": "mediaformat-classification",
    			    "key": "stereo",
    			    "type": "Concept"
    			}
    		    ],
    		    "language": [
    			"fi"
    		    ],
    		    "type": "AudioTrack"
    		}
    	    ],
    	    "collection": "main",
    	    "contentRating": {
    		"reason": [],
    		"title": {}
    	    },
    	    "countryOfOrigin": [],
    	    "creator": [],
    	    "description": {
    		"fi": "Mit\u00e4 on lohturuoka? Milloin sana ilmestyi ensimm\u00e4isen kerran lehtien palstoille? Toimittaja Kaisa Pulakka pohtii lohturuoan olemusta. Lohturuoka liittyy lapsuuteen ja siin\u00e4 maistuu nostalgia.\r\n\r\nLohturuoka voi my\u00f6s toimia siltana menneeseen. The Sopranos TV-sarjassa ruoka vahvistaa italialaista identiteetti\u00e4. Ohjelmasta selvi\u00e4\u00e4 my\u00f6s, millaisia lohturuoan popsijoita ovat Viisikoiden lapset, Nalle Puh ja Tove Janssonin Muumi-hahmot.\r\n\r\nToimittajana Kaisa Pulakka. Lukijana Pietari Kylm\u00e4l\u00e4."
    	    },
    	    "duration": "PT19M21S",
    	    "id": "1-2700948",
    	    "image": {
    		"available": true,
    		"id": "13-1-2700948",
    		"type": "ImageObject"
    	    },
    	    "indexDataModified": "2015-06-01T09:14:07.142+03:00",
    	    "itemTitle": {
    		"fi": "Nalle Puh, Muumit ja Sopranosit sy\u00f6v\u00e4t lohturuokaa"
    	    },
    	    "originalTitle": {},
    	    "partOfSeries": {
    		"@id": "http://programs.api.yle.fi/v1/id/1-2704918",
    		"availabilityDescription": {
    		    "fi": "Maanantaisin klo 17.40."
    		},
    		"countryOfOrigin": [],
    		"coverImage": {
    		    "available": true,
    		    "id": "13-1-2704918-cover",
    		    "type": "ImageObject"
    		},
    		"creator": [],
    		"description": {
    		    "fi": "\"Minuun iski ruoka-ahdistus. Tuntui, ett\u00e4 l\u00e4hikaupasta ei voi en\u00e4\u00e4 ostaa mit\u00e4\u00e4n.\" Ruoka on jatkuvasti tapetilla niin perinteisess\u00e4 kuin sosiaalisessakin mediassa. Ruoka ja sy\u00f6minen n\u00e4ytt\u00e4ytyv\u00e4t portteina henkiseen hyvinvointiin, mutta jatkuva ruokahypetys voi my\u00f6s aiheuttaa pahoinvointia. Toimittaja Kaisa Pulakka peilaa sarjassa ajatuksiaan kulttuurihistoriaan. 12-osainen radioesseiden sarja."
    		},
    		"id": "1-2704918",
    		"image": {
    		    "available": true,
    		    "id": "13-1-2704918",
    		    "type": "ImageObject"
    		},
    		"interactions": [
    		    {
    			"title": {
    			    "fi": "Yle Areena Ruoka-Suomi"
    			},
    			"type": "WebPage",
    			"url": "http://areena.yle.fi/tv/2417961"
    		    },
    		    {
    			"title": {
    			    "fi": "Yle Kulttuuri"
    			},
    			"type": "WebPage",
    			"url": "http://yle.fi/aihe/kulttuuri"
    		    },
    		    {
    			"title": {
    			    "fi": "Yle Ruoka"
    			},
    			"type": "WebPage",
    			"url": "http://yle.fi/aihe/ruoka"
    		    },
    		    {
    			"title": {
    			    "fi": "Sy\u00f6d\u00e4\u00e4n ensin! Ohjelman oma sivu"
    			},
    			"type": "WebPage",
    			"url": "http://yle.fi/aihe/ohjelma/syodaan-ensin"
    		    }
    		],
    		"subject": [
    		    {
    			"broader": {
    			    "id": "5-218"
    			},
    			"id": "5-217",
    			"inScheme": "areena-content-classification",
    			"key": "kulttuuri",
    			"title": {
    			    "fi": "Kulttuuri",
    			    "sv": "Kulturprogram"
    			},
    			"type": "Concept"
    		    },
    		    {
    			"id": "5-263",
    			"inScheme": "areena-analytics-classification",
    			"key": "kulttuuri",
    			"title": {
    			    "fi": "Kulttuuri"
    			},
    			"type": "Concept"
    		    }
    		],
    		"title": {
    		    "fi": "Sy\u00f6d\u00e4\u00e4n ensin!"
    		},
    		"type": "RadioSeries"
    	    },
    	    "publicationEvent": [
    		{
    		    "duration": "PT19M22S",
    		    "endTime": "2015-05-09T23:04:26+03:00",
    		    "id": "4-4229816",
    		    "media": {},
    		    "region": "World",
    		    "service": {
    			"id": "yle-radio-1"
    		    },
    		    "startTime": "2015-05-09T22:45:04+03:00",
    		    "temporalStatus": "in-past",
    		    "type": "ScheduledTransmission"
    		},
    		{
    		    "duration": "PT19M21S",
    		    "endTime": "2015-05-04T18:00:07+03:00",
    		    "id": "4-4211782",
    		    "media": {},
    		    "region": "World",
    		    "service": {
    			"id": "yle-radio-1"
    		    },
    		    "startTime": "2015-05-04T17:40:46+03:00",
    		    "temporalStatus": "in-past",
    		    "type": "ScheduledTransmission"
    		},
    		{
    		    "duration": "P1MT14H44M59S",
    		    "endTime": "2015-06-04T23:59:59+03:00",
    		    "id": "4-4360824",
    		    "media": {
    			"available": true,
    			"contentProtection": [
    			    {
    				"id": "22-0",
    				"type": "ContentProtectionPolicy"
    			    }
    			],
    			"downloadable": false,
    			"duration": "PT19M24S",
    			"id": "6-ef0f1296ffaa4c94873e94bfb15a7214",
    			"type": "AudioObject"
    		    },
    		    "publisher": [
    			{
    			    "id": "yle-radio-1"
    			}
    		    ],
    		    "region": "Finland",
    		    "service": {
    			"id": "yle-areena"
    		    },
    		    "startTime": "2015-05-04T09:15:00+03:00",
    		    "temporalStatus": "currently",
    		    "type": "OnDemandPublication"
    		}
    	    ],
    	    "subject": [
    		{
    		    "broader": {
    			"id": "5-200"
    		    },
    		    "id": "5-218",
    		    "inScheme": "areena-content-classification",
    		    "key": "faktajakulttuuri",
    		    "title": {
    			"fi": "Fakta ja Kulttuuri",
    			"sv": "Fakta och kultur"
    		    },
    		    "type": "Concept"
    		},
    		{
    		    "broader": {
    			"id": "5-218"
    		    },
    		    "id": "5-217",
    		    "inScheme": "areena-content-classification",
    		    "key": "kulttuuri",
    		    "title": {
    			"fi": "Kulttuuri",
    			"sv": "Kulturprogram"
    		    },
    		    "type": "Concept"
    		},
    		{
    		    "id": "5-263",
    		    "inScheme": "areena-analytics-classification",
    		    "key": "kulttuuri",
    		    "title": {
    			"fi": "Kulttuuri"
    		    },
    		    "type": "Concept"
    		},
    		{
    		    "id": "21-4",
    		    "inScheme": "finnpanel-genre-classification",
    		    "notation": [
    			{
    			    "value": "3.2",
    			    "valueType": "finnpanel-notation"
    			}
    		    ],
    		    "title": {
    			"en": "Cultural",
    			"fi": "Kulttuuriohjelmat"
    		    },
    		    "type": "Concept"
    		}
    	    ],
    	    "subtitling": [],
    	    "title": {
    		"fi": "Sy\u00f6d\u00e4\u00e4n ensin!: Nalle Puh, Muumit ja Sopranosit sy\u00f6v\u00e4t lohturuokaa"
    	    },
    	    "type": "RadioProgram",
    	    "typeCreative": "Program",
    	    "typeMedia": "RadioContent",
    	    "video": {}
    	}
        ],
        "meta": {
    	"clip": 8,
    	"count": 59,
    	"limit": "1",
    	"offset": "0",
    	"program": 51,
    	"q": "muumit"
        }
    }
    

    GET /v1/programs/items/{id}.json Get a single program, clip or episode

    Returns the program, episode or clip. E.g. /v1/items/1-2.json

    Parameters

    Name Description
    id The ID of the desired program, episode or clip

    Response

    200 OK on success

    Response contains a JSON document with one program.

    400 Bad Request if required parameters are missing

    404 Not Found If the id given is not a valid program id

    cURL example

    Details about a program

    curl -XGET "https://external.api.yle.fi/v1/programs/items/1-200102.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID"
    
    {
        "data": {
    	"@id": "http://programs.api.yle.fi/v1/id/1-200102",
    	"alternativeId": [
    	    "16-1-0650408"
    	],
    	"audio": [
    	    {
    		"format": [
    		    {
    			"inScheme": "mediaformat-classification",
    			"key": "stereo",
    			"type": "Concept"
    		    }
    		],
    		"language": [
    		    "fi"
    		],
    		"type": "AudioTrack"
    	    }
    	],
    	"collection": "main",
    	"contentRating": {
    	    "reason": [],
    	    "title": {}
    	},
    	"countryOfOrigin": [
    	    "Suomi"
    	],
    	"creator": [
    	    {
    		"name": "YLE",
    		"type": "Organization"
    	    }
    	],
    	"description": {
    	    "fi": "Kokki Anu valmistaa broiler-aterian uudella tavalla.",
    	    "sv": "Kocken Anu tillreder en broilerr\u00e4tt p\u00e5 ett nytt s\u00e4tt."
    	},
    	"duration": "PT13M5S",
    	"id": "1-200102",
    	"image": {
    	    "available": true,
    	    "id": "13-1-200102",
    	    "type": "ImageObject"
    	},
    	"indexDataModified": "2015-05-09T12:37:23.117+03:00",
    	"itemTitle": {},
    	"originalTitle": {},
    	"partOfSeries": {
    	    "@id": "http://programs.api.yle.fi/v1/id/1-200275",
    	    "countryOfOrigin": [],
    	    "creator": [],
    	    "description": {},
    	    "id": "1-200275",
    	    "image": {},
    	    "indexDataModified": "2015-05-09T00:36:24.419+03:00",
    	    "subject": [],
    	    "title": {
    		"fi": "POPsis!",
    		"sv": "POPsis!"
    	    },
    	    "type": "TVSeries"
    	},
    	"productionId": "51026301000",
    	"publicationEvent": [
    	    {
    		"duration": "P1MT15H26M59S",
    		"endTime": "2012-10-03T23:59:59+03:00",
    		"id": "4-2331952",
    		"media": {
    		    "available": true,
    		    "contentProtection": [
    			{
    			    "id": "22-1",
    			    "type": "ContentProtectionPolicy"
    			}
    		    ],
    		    "downloadable": false,
    		    "duration": "PT13M5S",
    		    "id": "6-b155e9ce6373450a8874cf3dadccfa78",
    		    "type": "VideoObject"
    		},
    		"publisher": [
    		    {
    			"id": "yle-tv2"
    		    }
    		],
    		"region": "Finland",
    		"service": {
    		    "id": "yle-areena"
    		},
    		"startTime": "2012-09-03T08:33:00+03:00",
    		"temporalStatus": "in-past",
    		"type": "OnDemandPublication"
    	    },
    	    {
    		"duration": "PT16M2S",
    		"endTime": "2012-06-04T08:50:02+03:00",
    		"id": "4-2184750",
    		"media": {},
    		"region": "Finland",
    		"service": {
    		    "id": "yle-tv2"
    		},
    		"startTime": "2012-06-04T08:34:00+03:00",
    		"temporalStatus": "in-past",
    		"type": "ScheduledTransmission"
    	    },
    	    {
    		"duration": "PT13M22S",
    		"endTime": "2009-08-01T09:39:22+03:00",
    		"id": "4-312581",
    		"media": {},
    		"region": "World",
    		"service": {
    		    "id": "yle-tv2"
    		},
    		"startTime": "2009-08-01T09:26:00+03:00",
    		"temporalStatus": "in-past",
    		"type": "ScheduledTransmission"
    	    },
    	    {
    		"duration": "PT13M8S",
    		"endTime": "2012-09-03T08:46:08+03:00",
    		"id": "4-2331951",
    		"media": {},
    		"region": "Finland",
    		"service": {
    		    "id": "yle-tv2"
    		},
    		"startTime": "2012-09-03T08:33:00+03:00",
    		"temporalStatus": "in-past",
    		"type": "ScheduledTransmission"
    	    },
    	    {
    		"duration": "PT14M27S",
    		"endTime": "2009-08-05T08:34:27+03:00",
    		"id": "4-320330",
    		"media": {},
    		"region": "World",
    		"service": {
    		    "id": "yle-tv2"
    		},
    		"startTime": "2009-08-05T08:20:00+03:00",
    		"temporalStatus": "in-past",
    		"type": "ScheduledTransmission"
    	    },
    	    {
    		"duration": "P1MT15H25M59S",
    		"endTime": "2012-07-04T23:59:59+03:00",
    		"id": "4-2184751",
    		"media": {
    		    "available": true,
    		    "contentProtection": [
    			{
    			    "id": "22-1",
    			    "type": "ContentProtectionPolicy"
    			}
    		    ],
    		    "downloadable": false,
    		    "duration": "PT13M5S",
    		    "id": "6-b155e9ce6373450a8874cf3dadccfa78",
    		    "type": "VideoObject"
    		},
    		"region": "Finland",
    		"service": {
    		    "id": "yle-areena"
    		},
    		"startTime": "2012-06-04T08:34:00+03:00",
    		"temporalStatus": "in-past",
    		"type": "OnDemandPublication"
    	    },
    	    {
    		"duration": "PT16M9S",
    		"endTime": "2009-08-01T09:46:09+03:00",
    		"id": "4-312773",
    		"media": {},
    		"region": "World",
    		"service": {
    		    "id": "tv-finland"
    		},
    		"startTime": "2009-08-01T09:30:00+03:00",
    		"temporalStatus": "in-past",
    		"type": "ScheduledTransmission"
    	    }
    	],
    	"subject": [
    	    {
    		"broader": {
    		    "id": "5-130"
    		},
    		"id": "5-195",
    		"inScheme": "areena-content-classification",
    		"key": "lapset",
    		"title": {
    		    "fi": "Lapset",
    		    "sv": "Barn"
    		},
    		"type": "Concept"
    	    },
    	    {
    		"id": "21-10",
    		"inScheme": "finnpanel-genre-classification",
    		"notation": [
    		    {
    			"value": "8",
    			"valueType": "finnpanel-notation"
    		    }
    		],
    		"title": {
    		    "en": "Children programs",
    		    "fi": "Lastenohjelmat"
    		},
    		"type": "Concept"
    	    }
    	],
    	"subtitling": [],
    	"title": {
    	    "fi": "POPsis!",
    	    "sv": "POPsis!"
    	},
    	"type": "TVProgram",
    	"typeCreative": "Program",
    	"typeMedia": "TVContent",
    	"video": {
    	    "format": [
    		{
    		    "inScheme": "mediaformat-classification",
    		    "key": "16:9",
    		    "type": "Concept"
    		}
    	    ],
    	    "language": [],
    	    "type": "VideoTrack"
    	}
        },
        "meta": {
    	"id": "1-200102"
        }
    }
    

    GET /v1/programs/categories.json Get categories

    Returns a collection of categories matching the query

    Parameters

    Name Description
    scheme Returns categories attached to the specified category scheme.
      Allowed values: “areena-content-classification”, “areena-analytics-classification”
    limit Sets limit for the size of the returned collection
    offset Sets offset for the collection

    Response

    200 OK on success

    Response contains a JSON document with the series.

    404 Not Found if id does not match a series object.

    cURL example

    Category example

    curl -XGET "https://external.api.yle.fi/v1/programs/categories.json?limit=1&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"
    
    {
        "data": [
    	{
    	    "id": "5-130",
    	    "inScheme": "areena-content-classification",
    	    "indexDataModified": "2015-03-26T10:25:23.307+02:00",
    	    "key": "tv",
    	    "title": {
    		"fi": "Tv",
    		"sv": "Tv"
    	    },
    	    "type": "Concept"
    	}
        ],
        "meta": {
    	"count": 148,
    	"limit": "1",
    	"offset": "0"
        }
    }
    

    GET /v1/program/services.json Get services

    Returns a collection of services matching the query

    Parameters

    Name Description
    type Returns services matching the given type
      Allowed values: “tvchannel”, “radiochannel”,
      “ondemandservice”, “webcastservice”
    limit Sets limit for the size of the returned collection
    offset Sets offset for the collection

    Response

    200 OK on success

    Response contains a JSON document with the services.

    400 Bad Request if parameters have illegal values

    cURL example

    Get radio services example

    curl -XGET "http://external.api.yle.fi/v1/programs/services.json?type=radiochannel&limit=1&app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID"
    
    {
        "data": [
    	{
    	    "active": true,
    	    "audio": [
    		{
    		    "format": [
    			{
    			    "inScheme": "mediaformat-classification",
    			    "key": "stereo",
    			    "type": "Concept"
    			}
    		    ],
    		    "language": [
    			"fi"
    		    ],
    		    "type": "AudioTrack"
    		}
    	    ],
    	    "displayOrder": 1000,
    	    "homepage": {
    		"serviceProvider": "http://yle.fi",
    		"title": {
    		    "fi": "Kotisivu",
    		    "sv": "Hemsida"
    		},
    		"type": "WebPage",
    		"url": "http://yle.fi/radio1"
    	    },
    	    "id": "yle-radio-1",
    	    "indexDataModified": "2015-03-26T10:25:23.569+02:00",
    	    "interaction": [
    		{
    		    "hasVersion": [
    			{
    			    "device": "mobile",
    			    "serviceProvider": "http://twitter.com",
    			    "title": {
    				"fi": "Twitter"
    			    },
    			    "type": "WebPage",
    			    "url": "https://mobile.twitter.com/yleradio1"
    			}
    		    ],
    		    "serviceProvider": "http://twitter.com",
    		    "title": {
    			"fi": "Twitter"
    		    },
    		    "type": "WebPage",
    		    "url": "https://twitter.com/yleradio1"
    		},
    		{
    		    "hasVersion": [
    			{
    			    "device": "mobile",
    			    "serviceProvider": "http://facebook.com",
    			    "title": {
    				"fi": "Facebook"
    			    },
    			    "type": "WebPage",
    			    "url": "https://m.facebook.com/yleradio1"
    			}
    		    ],
    		    "serviceProvider": "http://facebook.com",
    		    "title": {
    			"fi": "Facebook"
    		    },
    		    "type": "WebPage",
    		    "url": "https://facebook.com/yleradio1"
    		}
    	    ],
    	    "language": [
    		"fi"
    	    ],
    	    "outlet": [
    		{
    		    "media": {
    			"id": "10-6",
    			"type": "AudioObject"
    		    },
    		    "region": "Finland",
    		    "type": "Webcast"
    		},
    		{
    		    "media": {
    			"id": "10-6",
    			"type": "AudioObject"
    		    },
    		    "region": "World",
    		    "type": "Webcast"
    		}
    	    ],
    	    "programGuide": [
    		{
    		    "serviceProvider": "http://yle.fi",
    		    "title": {
    			"fi": "Ohjelmaopas",
    			"sv": "Programguide"
    		    },
    		    "type": "WebPage",
    		    "url": "http://ohjelmaopas.yle.fi/radio/opas"
    		}
    	    ],
    	    "region": "Finland",
    	    "title": {
    		"fi": "Yle Radio 1"
    	    },
    	    "type": "RadioChannel",
    	    "typeCreative": "Channel",
    	    "typeMedia": "RadioContent"
    	}
        ],
        "meta": {
    	"count": 32,
    	"limit": "1",
    	"offset": "0",
    	"type": "radiochannel"
        }
    }
    

    GET /v1/programs/services/{id}.json Get a service

    Returns a single service by the ID parameter

    Parameters

    Name Description
    id The ID of the desired service.

    Response

    200 OK on success

    Response contains a JSON document with the service.

    404 Not Found if id does not match a service object.

    cURL example

    Service example

    curl -XGET "https://external.api.yle.fi/v1/programs/services/yle-teema.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID"
    
    {
        "data": {
    	"active": true,
    	"audio": [
    	    {
    		"format": [
    		    {
    			"inScheme": "mediaformat-classification",
    			"key": "stereo",
    			"type": "Concept"
    		    }
    		],
    		"language": [
    		    "fi"
    		],
    		"type": "AudioTrack"
    	    },
    	    {
    		"language": [
    		    "fi"
    		],
    		"type": "AudioSubtitling"
    	    }
    	],
    	"displayOrder": 14000,
    	"hasFormat": [
    	    {
    		"audio": [
    		    {
    			"format": [
    			    {
    				"inScheme": "mediaformat-classification",
    				"key": "dolby-digital-2.0-stereo",
    				"type": "Concept"
    			    }
    			],
    			"language": [
    			    "fi"
    			],
    			"type": "AudioTrack"
    		    },
    		    {
    			"language": [
    			    "fi"
    			],
    			"type": "AudioSubtitling"
    		    }
    		],
    		"id": "yle-teema-hd",
    		"subtitling": [
    		    {
    			"language": [
    			    "fi"
    			],
    			"type": "Subtitling"
    		    }
    		],
    		"title": {
    		    "fi": "Yle Teema HD"
    		},
    		"type": "TVChannel",
    		"typeCreative": "Channel",
    		"typeMedia": "TVContent",
    		"video": {
    		    "format": [
    			{
    			    "inScheme": "mediaformat-classification",
    			    "key": "HD",
    			    "type": "Concept"
    			},
    			{
    			    "inScheme": "mediaformat-classification",
    			    "key": "16:9",
    			    "type": "Concept"
    			}
    		    ],
    		    "type": "VideoTrack"
    		}
    	    }
    	],
    	"homepage": {
    	    "serviceProvider": "http://yle.fi",
    	    "title": {
    		"fi": "Kotisivu",
    		"sv": "Hemsida"
    	    },
    	    "type": "WebPage",
    	    "url": "http://teema.yle.fi"
    	},
    	"id": "yle-teema",
    	"indexDataModified": "2015-03-26T10:25:23.569+02:00",
    	"language": [
    	    "fi"
    	],
    	"outlet": [
    	    {
    		"media": {
    		    "id": "10-3",
    		    "type": "VideoObject"
    		},
    		"region": "Finland",
    		"type": "Webcast"
    	    },
    	    {
    		"media": {
    		    "id": "10-40",
    		    "type": "VideoObject"
    		},
    		"region": "World",
    		"type": "Webcast"
    	    }
    	],
    	"programGuide": [
    	    {
    		"serviceProvider": "http://yle.fi",
    		"title": {
    		    "fi": "Ohjelmaopas",
    		    "sv": "Programguide"
    		},
    		"type": "WebPage",
    		"url": "http://ohjelmaopas.yle.fi/tv/opas"
    	    }
    	],
    	"region": "Finland",
    	"subtitling": [
    	    {
    		"language": [
    		    "fi"
    		],
    		"type": "Subtitling"
    	    }
    	],
    	"title": {
    	    "fi": "Yle Teema"
    	},
    	"type": "TVChannel",
    	"typeCreative": "Channel",
    	"typeMedia": "TVContent",
    	"video": {
    	    "format": [
    		{
    		    "inScheme": "mediaformat-classification",
    		    "key": "SD",
    		    "type": "Concept"
    		},
    		{
    		    "inScheme": "mediaformat-classification",
    		    "key": "16:9",
    		    "type": "Concept"
    		}
    	    ],
    	    "type": "VideoTrack"
    	}
        },
        "meta": {
    	"id": "yle-teema"
        }
    }
    

    GET /v1/programs/schedules.json Get program schedules

    Returns a collection of publication events. The publication events present a schedule for the given service, media type, time frame, category and so on.

    Parameters

    NameDescription
    serviceReturn items belonging to the given service.
    mediaobjectReturn schedules according to media type. Allowed values are "video" and "audio".
    starttimeReturn items that are published after this time. If not defined, default value is current date and starting from 6 AM. Value must be in format "yyyy-MM-dd'T'HH:mm:ss.SSSZZ".
    endtimeReturn items that are published before this time. If not defined, default value is the day after current date and ending at midnight. Value must be in format "yyyy-MM-dd'T'HH:mm:ss.SSSZZ".
    categoryReturn schedules linked to a specified category. Multiple category IDs can be passed as a comma separated list. To exclude schedules that belong to a specific category, add '-' before the id. E.g. category=1,2,-3,-4 returns schedules that belong to either category 1 or 2 AND do NOT belong to categories 3 AND 4.
    regionReturn schedules that contain a publication event with the given region. Allowed values are "fi" and "world".
    idReturn items with the given ID. Multiple IDs can be passed as a comma separated list.
    seriesReturn schedules containing the given series ID. Multiple IDs can be passed as a comma separated list.
    limitSets limit for the size of the returned collection.
    offsetSets offset for the collection.

    Response

    200 OK on success

    Response contains a JSON document with publication events. Maximum number of publication events returned is limited by limit parameter.

    400 Bad Request if parameters have invalid values

    cURL example

    curl -XGET "https://external.api.yle.fi/v1/programs/schedules.json?service=yle-areena \
      &mediaobject=video&limit=1&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"
    
    {
        "meta": {
            "count": 7,
            "endtime": "2017-01-26T03:59:59+0200",
            "limit": "1",
            "mediaobject": "video",
            "offset": "0",
            "service": "yle-areena",
            "starttime": "2017-01-25T04:00:00+0200"
        },
        "data": [
            {
                "content": {
                    "alternativeId": [
                        "16-0-16535"
                    ],
                    "audio": [
                        {
                            "format": [],
                            "language": [
                                "sv"
                            ],
                            "type": "AudioTrack"
                        }
                    ],
                    "description": {
                        "sv": "Damernas kortprogram i Ostrava, Tjeckien."
                    },
                    "duration": "PT6H10M",
                    "id": "1-3950537",
                    "image": {
                        "available": true,
                        "id": "13-1-3950537",
                        "type": "ImageObject",
                        "version": 1485280657
                    },
                    "publicationEvent": [
                        {
                            "duration": "PT6H10M",
                            "endTime": "2017-01-25T18:05:00+02:00",
                            "id": "4-6588804",
                            "media": {
                                "available": true,
                                "contentProtection": [
                                    {
                                        "id": "22-1",
                                        "type": "ContentProtectionPolicy"
                                    }
                                ],
                                "downloadable": false,
                                "duration": "PT6H10M",
                                "id": "15-1-3950537",
                                "type": "VideoObject",
                                "version": 2
                            },
                            "region": "Finland",
                            "service": {
                                "id": "yle-areena"
                            },
                            "startTime": "2017-01-25T11:55:00+02:00",
                            "temporalStatus": "in-future",
                            "type": "ScheduledTransmission",
                            "version": 2
                        }
                    ],
                    "subject": [
                        {
                            "id": "31-1-3",
                            "inScheme": "yle-content-main-classification",
                            "title": {
                                "fi": "Urheilu"
                            },
                            "type": "Concept"
                        },
                        {
                            "id": "31-2-3.3",
                            "inScheme": "yle-content-format-classification",
                            "title": {
                                "fi": "Muut"
                            },
                            "type": "Concept"
                        },
                        {
                            "id": "31-3-3.75",
                            "inScheme": "yle-content-topic-classification",
                            "title": {
                                "fi": "Luistelu"
                            },
                            "type": "Concept"
                        },
                        {
                            "broader": {
                                "id": "5-164"
                            },
                            "id": "5-189",
                            "inScheme": "areena-content-classification",
                            "key": "taitoluistelu",
                            "title": {
                                "fi": "Taitoluistelu",
                                "sv": "Konståkning"
                            },
                            "type": "Concept"
                        },
                        {
                            "id": "5-267",
                            "inScheme": "areena-analytics-classification",
                            "key": "urheilu",
                            "title": {
                                "fi": "Urheilu"
                            },
                            "type": "Concept"
                        }
                    ],
                    "subtitling": [],
                    "title": {
                        "sv": "EM i konståkning, damernas kortprogram"
                    },
                    "type": "TVProgram",
                    "typeCreative": "Program",
                    "typeMedia": "TVContent",
                    "video": {
                        "format": [
                            {
                                "inScheme": "mediaformat-classification",
                                "key": "16:9",
                                "type": "Concept"
                            }
                        ],
                        "language": [
                            "sv"
                        ],
                        "type": "VideoTrack"
                    }
                },
                "duration": "PT6H10M",
                "endTime": "2017-01-25T18:05:00+02:00",
                "id": "4-6588804",
                "indexDataModified": "2017-01-24T19:57:37.588+02:00",
                "media": {
                    "available": true,
                    "contentProtection": [
                        {
                            "id": "22-1",
                            "type": "ContentProtectionPolicy"
                        }
                    ],
                    "downloadable": false,
                    "duration": "PT6H10M",
                    "id": "15-1-3950537",
                    "type": "VideoObject",
                    "version": 2
                },
                "region": "Finland",
                "service": {
                    "id": "yle-areena"
                },
                "startTime": "2017-01-25T11:55:00+02:00",
                "temporalStatus": "in-future",
                "type": "ScheduledTransmission",
                "version": 2
            }
        ]
    }
    

    GET /v1/programs/schedules/now.json Get the current broadcast

    Returns currently running programs, optionally with previous and upcoming programs. Can return multiple programs that are running simultaneously. For example, Yle Areena may have multiple webcasts running at a time.

    Parameters

    NameDescription
    serviceReturn programs currently running on specified service(s). Multiple service IDs can be passes as a comma separated list.
    startDefines how many previous programs will be returned. Allowed values range from -10 to 0. -1 means that the previous program will be included in the response.
    endDefines how many upcoming programs will be returned. Allowed values range from 0 to 10. 1 means that the next program will be included in the response.
    mediaobjectReturn currently playing programs according to media type. Allowed values are "video" and "audio".

    Response

    200 OK on success

    Response contains a JSON document with the current broadcast.

    404 Not Found if search parameters do not match any publications.

    cURL example

    curl -XGET "https://external.api.yle.fi/v1/programs/schedules/now.json? \
      service=yle-teema&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"
    
    {
        "meta": {
            "end": 0,
            "service": "yle-teema",
            "start": 0
        },
        "data": [
            {
                "content": {
                    "alternativeId": [
                        "16-6-588747093200003a00413f12"
                    ],
                    "description": {
                        "sv": "Teemainfo"
                    },
                    "duration": "PT12H59M11S",
                    "id": "1-3949608",
                    "publicationEvent": [
                        {
                            "duration": "PT13H",
                            "endTime": "2017-01-25T17:00:00+02:00",
                            "id": "4-6587714",
                            "region": "Finland",
                            "service": {
                                "id": "yle-teema"
                            },
                            "startTime": "2017-01-25T04:00:00+02:00",
                            "temporalStatus": "currently",
                            "type": "ScheduledTransmission",
                            "version": 1
                        }
                    ],
                    "title": {
                        "fi": "Teematieto",
                        "sv": "Teematieto"
                    },
                    "type": "TVProgram",
                    "typeCreative": "Program",
                    "typeMedia": "TVContent",
                    "video": {
                        "format": [
                            {
                                "inScheme": "mediaformat-classification",
                                "key": "16:9",
                                "type": "Concept"
                            }
                        ],
                        "language": [],
                        "type": "VideoTrack"
                    }
                },
                "duration": "PT13H",
                "endTime": "2017-01-25T17:00:00+02:00",
                "id": "4-6587714",
                "region": "Finland",
                "service": {
                    "id": "yle-teema"
                },
                "startTime": "2017-01-25T04:00:00+02:00",
                "temporalStatus": "currently",
                "type": "ScheduledTransmission",
                "version": 1
            }
        ]
    }
    

    GET /v1/programs/nowplaying/{service}.json Get the currently playing song on a radio service

    Returns information of currently ongoing song in chosen service. It is also possible to get previous and next songs with start and end parameters.

    Parameters

    Name Description
    service The service from which to get the current current song. This parameter is required.
    start Sets onset for the collection. Not required.
    end Sets offset for the collection.

    Response

    200 OK on success

    Response contains a JSON document with the currently ongoing song.

    400 Bad Request if parameters have illegal values.

    404 Not Found if service does not match a service object.

    cURL example

    Now playing example

    curl -XGET "http://external.api.yle.fi/v1/programs/nowplaying/yle-radio-1.json?start=0&stop=0&app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID"
    
    {
        "data": [
    	{
    	    "content": {
    		"description": {
    		    "unknown": "Porter: Get out of town (Mel Torme ja Artie Shawn orkesteri)."
    		},
    		"id": "12-1022-2-72745",
    		"performer": [
    		    {
    			"name": "Mel Torme, laulu",
    			"type": "agent"
    		    },
    		    {
    			"name": "Artie Shaw and his Orchestra",
    			"type": "agent"
    		    }
    		],
    		"title": {
    		    "unknown": "Get out of town"
    		},
    		"type": "MusicRecording"
    	    },
    	    "delta": "0",
    	    "duration": "PT194S",
    	    "endTime": "2015-06-04T09:55:19+0300",
    	    "partOf": {
    		"id": "12-1022-4-256469",
    		"title": {
    		    "fi": "Muistojen bulevardi"
    		},
    		"type": "RadioProgram"
    	    },
    	    "service": {
    		"active": true,
    		"audio": [
    		    {
    			"format": [
    			    {
    				"inScheme": "mediaformat-classification",
    				"key": "stereo",
    				"type": "Concept"
    			    }
    			],
    			"language": [
    			    "fi"
    			],
    			"type": "AudioTrack"
    		    }
    		],
    		"displayOrder": 1000,
    		"homepage": {
    		    "serviceProvider": "http://yle.fi",
    		    "title": {
    			"fi": "Kotisivu",
    			"sv": "Hemsida"
    		    },
    		    "type": "WebPage",
    		    "url": "http://yle.fi/radio1"
    		},
    		"id": "yle-radio-1",
    		"indexDataModified": "2015-03-26T10:25:23.569+02:00",
    		"interaction": [
    		    {
    			"hasVersion": [
    			    {
    				"device": "mobile",
    				"serviceProvider": "http://twitter.com",
    				"title": {
    				    "fi": "Twitter"
    				},
    				"type": "WebPage",
    				"url": "https://mobile.twitter.com/yleradio1"
    			    }
    			],
    			"serviceProvider": "http://twitter.com",
    			"title": {
    			    "fi": "Twitter"
    			},
    			"type": "WebPage",
    			"url": "https://twitter.com/yleradio1"
    		    },
    		    {
    			"hasVersion": [
    			    {
    				"device": "mobile",
    				"serviceProvider": "http://facebook.com",
    				"title": {
    				    "fi": "Facebook"
    				},
    				"type": "WebPage",
    				"url": "https://m.facebook.com/yleradio1"
    			    }
    			],
    			"serviceProvider": "http://facebook.com",
    			"title": {
    			    "fi": "Facebook"
    			},
    			"type": "WebPage",
    			"url": "https://facebook.com/yleradio1"
    		    }
    		],
    		"language": [
    		    "fi"
    		],
    		"outlet": [
    		    {
    			"media": {
    			    "id": "10-6",
    			    "type": "AudioObject"
    			},
    			"region": "Finland",
    			"type": "Webcast"
    		    },
    		    {
    			"media": {
    			    "id": "10-6",
    			    "type": "AudioObject"
    			},
    			"region": "World",
    			"type": "Webcast"
    		    }
    		],
    		"programGuide": [
    		    {
    			"serviceProvider": "http://yle.fi",
    			"title": {
    			    "fi": "Ohjelmaopas",
    			    "sv": "Programguide"
    			},
    			"type": "WebPage",
    			"url": "http://ohjelmaopas.yle.fi/radio/opas"
    		    }
    		],
    		"region": "Finland",
    		"title": {
    		    "fi": "Yle Radio 1"
    		},
    		"type": "RadioChannel",
    		"typeCreative": "Channel",
    		"typeMedia": "RadioContent"
    	    },
    	    "startTime": "2015-06-04T09:52:05+0300",
    	    "type": "NowPlaying"
    	}
        ],
        "meta": {
    	"count": 1,
    	"end": 0,
    	"service": "yle-radio-1",
    	"start": 0
        }
    }
    

    GET /v1/media/playouts.json Retrieving Stream URL for OnDemand program

    Using the combination of program id and media ID, you can retrieve URL to the media. You also must provide the protocol, in our example we use HLS (HTTP Live Streaming) but you can alternatively use HDS (HTTP Dynamic Streaming).

    Parameters

    Name Description
    program_id  
    media_id  
    protocol possible values are HLS, HDS, PMD or RTMPE

    Optional parameters

    Name Description
    hardsubtitles Burn subtitles (if available) into the stream, possible values: true, false
    multibitrate possible values: true, false

    GET /v1/tracking/streamstart Report your usage

    This endpoint is used to report your usage of media streams. Each time you or one of your users starts playing a video, you should report it via this API.

    Send a request to this API only on the first time per each page load. If you pause, and then resume watching, this API should not be requested again. But if the page is refreshed and media stream starts playing again, it should be reported.

    Parameters

    Name Description
    program_id ID of the program whose media stream is being consumed.
    media_id ID of the media that is being consumed.

    cURL example

    curl -v "https://external.api.yle.fi/v1/tracking/streamstart?program_id=1-820561&media_id=6-8e9d45c1221544f3be76394fa1a6a102&app_id=YOUR_APP_ID&app_key=YOUR_APP_KEY"