API

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 a couple of examples of successful and failed API requests. You can find the common error messages from the "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 requests

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"
}