Resources / API: GET

API requests must include the required parameters to ensure proper processing and accurate responses. From the table below you can find the parameter names, description for the parameter, data validations and is it a mandatory parameter (mandatory if required = TRUE). 

URL: https://guide-api.mediaportal.fi/api

Param name	Description	Validations	Required
apiKey	API key	Must be a String	TRUE
service	The service (chosen channel) for which the guide is required.   Available services: nel, her, nep, liv	Must be a String	TRUE
publication_valid_between	The time period for which the guide is valid. This can be in following formats:  YYYY-MM-DD,YYYY-MM-DD YYYY-MM-DDTHH:MM:SS,YYYY-MM-DDTHH:MM:SS YYYY-MM-DD, (everything after YYYY-MM-DD) ,YYYY-MM-DD (everything before YYYY-MM-DD) YYYY-MM-DD Dates without time will get specific times added: T06:00:00 for start time T05:59:59 for end time Time period with single date without colon (YYYY-MM-DD) or time period with same date as start and end date (YYYY-MM-DD,YYYY-MM-DD) will get +1 day added to end date:  2024-06-16,2024-06-16  -> 2024-06-16,2024-06-17 -> 2024-06-16T06:00:00,2024-06-17T05:59:59 2024-07-14  -> 2024-07-14,2024-07-15 -> 2024-06-14T06:00:00,2024-07-15T05:59:59	Must be a String	TRUE
offset	Optional. Default value: 0. The offset is used to view the next set of results if the search returns more than 500 results. For example, if the totalCount is 800, set the offset to 501 to view results 501-800.	Must be Integer	FALSE
size	Optional. Specifies the page size of the query. Default value: 500.	Must be Integer	FALSE

Examples

Here are couple examples of successful and failed API requests. You can find the common error messages from Error codes article. 

Successful request 

(only the first program is shown in this example)

GET api?apiKey=APIKEY&service=nel&publication_valid_between=2024-08-31

Results

{
"meta": {
"totalCount": 29,
"offset": 0,
"pageSize": 29
},
"service": {
"id": "nel",
"name": "Nelonen",
"startDate": "2024-08-31T06:00:00+03:00",
"endDate": "2024-09-01T05:59:59+03:00"
},
"programs": [
{
"id": xxxxx,
"mpid": "xxxxx",
"year": "",
"country": "",
"premiere": false,
"title": {
"fi": "Bing",
"sv": "",
"en": ""
},
"synopsis": {
"fi": "Bing on kolmevuotias pikkuinen pupu, joka ystäviensä avustamana oppii joka päivä jotain uutta ja selviytyy taaperoille tutuista elämän haasteista. Lastenohjelma.",
"sv": "",
"en": ""
},
"broadcast": {
"planned": {
"start": "2024-08-31T06:00:00+03:00",
"end": "2024-08-31T06:05:00+03:00",
"duration": "PT0H5M0S"
}
},
"captionTracks": [
{
"language": "fin",
"kind": "hardOfHearing"
},
{
"language": "",
"kind": ""
}
],
"classifications": [
{
"notations": [
{
"value": "8",
"name": "Lastenohjelmat",
"type": "Notation",
"kind": "Finnpanel"
}
],
"parentalGuidance": {
"minimumAge": "",
"parentalRating": "[]"
},
"copyright": {
"copyrightHolder": "Nelonen",
"copyrightDate": "2024-08-31"
}
}
],
"category": [
{
"category": "Lastenohjelma",
"subcategory": "Muu, luokiteltava"
}
],
"episodeNumber": 13,
"seasonNumber": 1,
"images": []
},
{
"id": xxxxx,
"mpid": "xxxxx",
"year": "",
"country": "",
"premiere": false,
"title": {
"fi": "Kindi Kids",
"sv": "",
"en": ""
},
"synopsis": {
"fi": "Supersuositun lelusarjan ikioma lastenohjelma koostuu näppäristä viiden minuutin jaksoista, joissa seurataan värikkäiden hahmojen koomisia seikkailuja. Lastenohjelma.",
"sv": "",
"en": ""
},
"broadcast": {
"planned": {
"start": "2024-08-31T06:05:00+03:00",
"end": "2024-08-31T06:10:00+03:00",
"duration": "PT0H5M0S"
}
},
"captionTracks": [
{
"language": "fin",
"kind": "hardOfHearing"
},
{
"language": "",
"kind": ""
}
],
"classifications": [
{
"notations": [
{
"value": "8",
"name": "Lastenohjelmat",
"type": "Notation",
"kind": "Finnpanel"
}
],
"parentalGuidance": {
"minimumAge": "",
"parentalRating": "[]"
},
"copyright": {
"copyrightHolder": "Nelonen",
"copyrightDate": "2024-08-31"
}
}
],
"category": [
{
"category": "Lastenohjelma",
"subcategory": "Muu, luokiteltava"
}
],
"episodeNumber": 5,
"seasonNumber": 1,
"images": []
}

etc...

Failed request

Request example 1

GET /api?service=liv&apiKey=xxxxx

Results example 1

400 Bad Request

{
"message": "Bad request: publication_valid_between must be set"
}

Request example 2

GET /api?service=liv&publication_valid_between=2024-07-08,2024-07-9

Results example 2

401 Unauthorized

{
"message": "Unauthorized"
}