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ä on lohturuoka? Milloin sana ilmestyi ensimmäisen kerran lehtien palstoille? Toimittaja Kaisa Pulakka pohtii lohturuoan olemusta. Lohturuoka liittyy lapsuuteen ja siinä maistuu nostalgia.\r\n\r\nLohturuoka voi myös toimia siltana menneeseen. The Sopranos TV-sarjassa ruoka vahvistaa italialaista identiteettiä. Ohjelmasta selviää myös, millaisia lohturuoan popsijoita ovat Viisikoiden lapset, Nalle Puh ja Tove Janssonin Muumi-hahmot.\r\n\r\nToimittajana Kaisa Pulakka. Lukijana Pietari Kylmälä."
    	    },
    	    "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övät lohturuokaa"
    	    },
    	    "originalTitle": {},
    	    "partOfSeries": {
    		"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ä lähikaupasta ei voi enää ostaa mitään.\" Ruoka on jatkuvasti tapetilla niin perinteisessä kuin sosiaalisessakin mediassa. Ruoka ja syöminen näyttäytyvät portteina henkiseen hyvinvointiin, mutta jatkuva ruokahypetys voi myös 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ödään 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ödään 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ödään ensin!: Nalle Puh, Muumit ja Sopranosit syövät 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": {
    	"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ätt p\u00e5 ett nytt sätt."
    	},
    	"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": {
    	    "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/series/items.json Search series

    Returns a collection of series matching the specified query. E.g. Series in category 5-137: /v1/series/items.json?category=5-137

    Parameters

    NameDescription
    categoryReturns items linked to a specified category. Multiple category IDs can be passed as a comma separated list. To exclude series that belong to a specific category, add '-' before the id. E.g. category=1,2,-3,-4 returns series that belong to either category 1 or 2 AND do NOT belong to categories 3 AND 4.
    idReturns items containing the specified ID. Multiple IDs can be passed as a comma separated list. To exclude series by id, add '-' before the id. E.g. id=1,2,-3,-4 returns series that have either id 1 or 2 AND do NOT have id 3 AND 4.
    limitSets limit for the size of the returned collection
    offsetSets offset for the collection. Note that limit + offset must not be greater than 15 000.

    Response

    200 OK on success

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

    400 Bad Request if parameters have illegal values

    cURL example

    Series example

    curl -XGET "https://external.api.yle.fi/v1/series/item.json?category=5-137&limit=1&app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID"
    
    {
        "apiVersion": "1.0.1299",
        "data": [
    	{
    	    "countryOfOrigin": [
    		"Belgia"
    	    ],
    	    "coverImage": {
    		"available": true,
    		"id": "13-1-2309229-cover",
    		"type": "ImageObject"
    	    },
    	    "creator": [
    		{
    		    "name": "BetaFilm GmbH & Co.",
    		    "type": "Organization"
    		}
    	    ],
    	    "description": {
    		"fi": "Brysseliläinen pankki ryöstetään tavallista kohtalokkaammin seurauksin. Belgian kermalle kuuluvat 66 tallelokeroa viedään, ja sisältö on tietenkin tulenarkaa. Ryöstöä tutkiva poliisi Paul Gerardi huomaa, että uhrit kuuluvat kaikki salaperäiseen Salamander-organisaatioon. Belgialainen, suurelle yleisölle tehty rikossarja on ollut ennennäkemätön menestys kotimaassaan."
    	    },
    	    "id": "1-2309229",
    	    "image": {
    		"available": true,
    		"id": "13-1-2309229",
    		"type": "ImageObject"
    	    },
    	    "indexDataModified": "2015-05-09T00:31:14.084+03:00",
    	    "interactions": [
    		{
    		    "title": {
    			"fi": "Yle Areenan perjantaisarjat"
    		    },
    		    "type": "WebPage",
    		    "url": "http://areena.yle.fi/tv/2403342"
    		}
    	    ],
    	    "subject": [
    		{
    		    "broader": {
    			"id": "5-131"
    		    },
    		    "id": "5-134",
    		    "inScheme": "areena-content-classification",
    		    "key": "ulkomaisetsarjat",
    		    "title": {
    			"fi": "Ulkomaiset sarjat",
    			"sv": "Utländska serier"
    		    },
    		    "type": "Concept"
    		},
    		{
    		    "broader": {
    			"id": "5-131"
    		    },
    		    "id": "5-137",
    		    "inScheme": "areena-content-classification",
    		    "key": "jannitys",
    		    "title": {
    			"fi": "Jännitys",
    			"sv": "Spänning"
    		    },
    		    "type": "Concept"
    		},
    		{
    		    "id": "5-262",
    		    "inScheme": "areena-analytics-classification",
    		    "key": "draama",
    		    "title": {
    			"fi": "Draama"
    		    },
    		    "type": "Concept"
    		}
    	    ],
    	    "title": {
    		"fi": "Salamander",
    		"sv": "Salamander"
    	    },
    	    "type": "TVSeries"
    	}
        ],
        "meta": {
    	"category": "5-137",
    	"count": 260,
    	"limit": "1",
    	"offset": "0"
        }
    }
    

    GET /v1/series/items/{id}.json Get a series

    Returns the series with the defined id. E.g. /v1/series/items/1-2.json

    Parameters

    Name Description
    id The ID of the desired series.

    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

    Series example

    curl -XGET "https://external.api.yle.fi/v1/series/items/1-2309229.json?app_key=YOUR_APP_KEY&app_id=YOUR_APP_ID"
    
    {
        "apiVersion": "1.0.1299",
        "data": {
    	"countryOfOrigin": [
    	    "Belgia"
    	],
    	"coverImage": {
    	    "available": true,
    	    "id": "13-1-2309229-cover",
    	    "type": "ImageObject"
    	},
    	"creator": [
    	    {
    		"name": "BetaFilm GmbH & Co.",
    		"type": "Organization"
    	    }
    	],
    	"description": {
    	    "fi": "Brysseliläinen pankki ryöstetään tavallista kohtalokkaammin seurauksin. Belgian kermalle kuuluvat 66 tallelokeroa viedään, ja sisältö on tietenkin tulenarkaa. Ryöstöä tutkiva poliisi Paul Gerardi huomaa, että uhrit kuuluvat kaikki salaperäiseen Salamander-organisaatioon. Belgialainen, suurelle yleisölle tehty rikossarja on ollut ennennäkemätön menestys kotimaassaan."
    	},
    	"id": "1-2309229",
    	"image": {
    	    "available": true,
    	    "id": "13-1-2309229",
    	    "type": "ImageObject"
    	},
    	"indexDataModified": "2015-05-09T00:31:14.084+03:00",
    	"interactions": [
    	    {
    		"title": {
    		    "fi": "Yle Areenan perjantaisarjat"
    		},
    		"type": "WebPage",
    		"url": "http://areena.yle.fi/tv/2403342"
    	    }
    	],
    	"subject": [
    	    {
    		"broader": {
    		    "id": "5-131"
    		},
    		"id": "5-134",
    		"inScheme": "areena-content-classification",
    		"key": "ulkomaisetsarjat",
    		"title": {
    		    "fi": "Ulkomaiset sarjat",
    		    "sv": "Utländska serier"
    		},
    		"type": "Concept"
    	    },
    	    {
    		"broader": {
    		    "id": "5-131"
    		},
    		"id": "5-137",
    		"inScheme": "areena-content-classification",
    		"key": "jannitys",
    		"title": {
    		    "fi": "Jännitys",
    		    "sv": "Spänning"
    		},
    		"type": "Concept"
    	    },
    	    {
    		"id": "5-262",
    		"inScheme": "areena-analytics-classification",
    		"key": "draama",
    		"title": {
    		    "fi": "Draama"
    		},
    		"type": "Concept"
    	    }
    	],
    	"title": {
    	    "fi": "Salamander",
    	    "sv": "Salamander"
    	},
    	"type": "TVSeries"
        },
        "meta": {
    	"id": "1-2309229"
        }
    }
    

    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"