This document describes how to access and consume the Media-Press Proxy API. The API exposes RESTful interface allowing to retrieve the latest state of linear tv metadata, non-linear assets and other resources. The API provides secure, robust, and reliable access to the resources. To get access to the API, a contact with Media-Press is required to set up the account.
For each account following parameters are fully configurable and can vary depending on the contract:
To access the API, customer receives a dedicated private API-Key. The key is used for a client authentication and rights management. It must be kept secret.
We encourage you to contact our Sales Department to configure a demo access
This section contains general guidelines that help creating the API client and integrate the API with the customer system. The API comply with the RESTful specification, therefore creating the client in any programming language should be easy. We are working on the Swagger definition of the API, that could be used for auto-generation of client SDK which will make the process even easier.
The API endpoint is available at https://api-proxy.media-press.tv
Each request must contain a private API-Key in the https request-header like in the following example:
x-api-key: ZXDEMOkYuizu67DEMOnGWgY7E8GCDEMOZX
It is worth to note that the 'Accept' request-header is not respected. The content-type is always application/xml or application/json. It is fixed per client to meet the client-software requirements and is consistent through the whole API.
Refresh all data
Process modified channel-day schedules (incremental update)
Processing of the tv-data heavily depends on the ordered format. In most cases, the broadcast ID is available along with activity flag, which allows to perform updates, save or delete operation of the broadcast in the client’s system.
This section lists all API endpoints used for fetching linear tv schedules. Particular endpoints availability depends on the contract.
The endpoint retrieves the list of available channels. Each channel item contains the channel-id and the channel-name.
Input params: None Output: Response body contains a xml or json fixed schema representing a list of channels available for the customer.
Example: GET https://api-proxy.media-press.tv/GetChannels
returns object as xml,
<ArrayOfChannelHeader>
<ChannelHeader>
<ChannelId>3SA</ChannelId>
<Name>3 SAT</Name>
</ChannelHeader>
<ChannelHeader>
<ChannelId>BBC1</ChannelId>
<Name>BBC1 Channel</Name>
</ChannelHeader>
</ArrayOfChannelHeader>
or as json
[
{ "ChannelId": "3SA",
"Name": "3 SAT"
},
{ "ChannelId": "BBC1",
"Name": "BBC1 Channel"
},
]
The endpoint retrieves a list of channel-day schedules that has been modified since the last checking.
Input params:
datetime - timestamp of the last modification checking in the format YYYY-MM-DDTmm:hh:ss.
datetimenow value returned by last execution of the GetModifiedChannelDaysSince endpoint.
Output:
Response body with a document in fixed format containing a list of recently modified channel-day schedules.
Example: GET https://api-proxy.media-press.tv/GetModifiedChannelDaysSince/2017-01-04T10:00:00
returns object as xml,
<modifiedDataResponse>
<datetimenow>2017-01-09T20:42:00</datetimenow>
<modified date="2017-01-05" channelId="3SA">https://api-proxy.media-press.tv/GetEventByAirdate/3SA/2017-01-05</modified>
<modified date="2017-01-02" channelId="PR7">https://api-proxy.media-press.tv/GetEventByAirdate/PR7/2017-01-02</modified>
<modified date="2017-01-03" channelId="PR7">https://api-proxy.media-press.tv/GetEventByAirdate/PR7/2017-01-03</modified>
</modifiedDataResponse>
or as json
{
"datetimenow":"2017-01-09T20:42:00",
"modified":
[
{ "_date":"2017-01-05",
"_channelId":"3SA",
"value":"https://api-proxy.media-press.tv/GetEventByAirdate/3SA/2017-01-05",
},
{
"_date":"2017-01-02",
"_channelId":"PR7",
"value":"https://api-proxy.media-press.tv/GetEventByAirdate/PR7/2017-01-02",
},
{
"_date":"2017-01-03",
"_channelId":"PR7",
"value":"https://api-proxy.media-press.tv/GetEventByAirdate/PR7/2017-01-03",
}
]
}
The endpoint retrieves a complete tv-schedule for given channel-id and broadcasting date.
Input params:
channel - the id of the channel returned by GetChannels endpoint.
airdate - the broadcasting date in the format YYYY-MM-DD. The date cannot exceed the arranged range.
Output:
Response body with a document containing a tv-schedule in ordered format. The specification of the document is arranged with the customer to meet requirements of the client’s system.
Example: GET https://api-proxy.media-press.tv/GetEventByAirdate/311/2017-01-09
can return depending on the arranged format:
<?xml version="1.0" encoding="UTF-8"?>
<tv generator-info-name="media-press">
<channel id="311">
<display-name>MCM TOP</display-name>
</channel>
<programme channel="311" start="20170109210000+0100" stop="20170109223000+0100">
<title>Top Mix</title>
<desc>Des clips, des clips et toujours des clips, de la dernière nouveauté à l'artiste un peu moins connu mais qui mérite d'être découvert.</desc>
<category>Musique</category>
<category>Rock + Pop</category>
<language>FR</language>
<length units="minutes">90</length>
<video>
<aspect>16:9</aspect>
</video>
<audio>
<stereo>stereo</stereo>
</audio>
</programme>
<programme channel="311" start="20170109223000+0100" stop="20170109233000+0100">
<title>Top Star</title>
<sub-title>Magazine</sub-title>
<desc>Une heure en compagnie des meilleurs clips d'un artiste reconnu par la critique et le public.</desc>
<category>Musique</category>
<category>Magazine musical</category>
<language>FR</language>
<length units="minutes">60</length>
</programme>
</tv>
This section lists API endpoints used for downloading files. This generic API allows to list files available in the root folder and to download them. The type of files and content can vary and depends on the agreement.
The endpoint retrieves the list of available files and files meta-data.
Input params: None Output: Response body contains a xml or json fixed schema representing a list of files and meta-data.
Example: GET https://api-proxy.media-press.tv/ListItems
returns object as json
[
{
"FileName": "epg_20170529.zip",
"LastModified": "2017-05-29T10:06:17.000Z",
"Size": 3676160
},
{
"FileName": "epg_20170530.zip",
"LastModified": "2017-05-30T06:11:04.000Z",
"Size": 3676160
},
{
"FileName": "epg_20170531.zip",
"LastModified": "2017-05-31T06:10:20.000Z",
"Size": 3983360
}
]
The endpoint allows to download a file of a known name.
Input params:
filename - the name of the file to be downloaded.
Output
Stream of the file.
Example: GET https://api-proxy.media-press.tv/GetItem/epg_20170531.zip
returns the stream to the epg_20170531.zip file
The Files endpoints can be used to access non-liner assets. The assets are grouped into catalogues (VoD). The standard sequence of requests is as follows:
Retrieve list of catalogs
GET https://api-proxy.media-press.tv/GetItem/channel_details.json
This endpoint returns a list of all available streaming catalogs.
Retrieve Assets in a Catalog
GET https://api-proxy.media-press.tv/GetItem/{channelId}/catalogue.json
The channelId parameter, required for this request, can be found in the response of the previous endpoint.
This endpoint returns a list of all assets within a specific catalog also known as the catalog index.
For each asset, the response contain:
'EventId' : Unique ID of the VoD event
'VodAvailableFrom' & 'VodAvailableUntil' : the availability span
'LastModif' : time of the last modification of the asset
Retrieve a Single Item from the Catalog
GET https://api-proxy.media-press.tv/GetItem/{channelId}/{eventId}.json
This endpoint returns details of a single item from the catalog.
The response object complies with the arranged data model.
The 'eventId' parameter, required for this request, can be found in the response of the previous endpoint.
Identifying and refreshing only newest changes in the catalogue
There is no need to perform a full scan through all assets in the cataloge {eventId}.json to refresh the state or identify new assets.
The catalogue.json response contains the time of the latest update of the index document in the property 'GenerationTime'. This value should be stored.
During subsequest scans of the catalogue.json, only assets with a 'LastModif' higher then the previously stored 'GenerationTime' should be retrieved.
When using the API, errors may occur, resulting in response codes other than 200 OK. The errors generally can be grouped into two categories:
Server-side errors
Server-side errors are caused by malfunction within the API core. These issues are internally monitored and resolved by API team.
Client-side errors
Client-side errors typically result from incorrect usage of the API by the client’s software. Detailed information about a cause of an error can be determined based on the HTTP response code and the response body message.
The following codes and messages can be returned:
Status code:400 Mesage:Wrong format of the date parameter <date>
The airdate parameter is formatted incorrectly.
Status code:400 Mesage:Valid channelId parameter should be provided in the request URL
The channelId parameter is missing or the specified channel is not available for the customer.
Status code:400 Mesage:Valid Api-Key should be provided in the request header
The API-Key is missing. Please check in the request-header for the “x-api-key”.
Status code:401 Mesage:There are no privileges for this api key
The API-Key has not the sufficient permissions to access the resource.
Status code:403 Mesage:There are no privileges for this resource
The requested REST endpoint is not available for the customer.
Status code:403 Mesage:No privileges for query in given datetime range. Request date is smaller than
The airdate parameter is not accurate as it is too far in the past. Please verify in your contract which time range is available for your export or contact us.
Status code:403 Mesage:No privileges for query in given datetime range. Request date is greater than
The airdate parameter is too far ahead. Please verify in your contract which time range is available for your export or contact us.
Status code:403 Mesage:Demo access expired
Your demo access to the API has expired.
Status code:500 Mesage:Failed to process request
The request was not processed due to the unexpected server errors. Please contact Media-press Technical Support.
If you have any questions about the API, do not hesitate to contact our Technical Support