Feed Api

Version 1.0, 02/2019

Introduction

The glomex Content API enables the customer to programatically retrieve metadata information of the video content stored in the glomex services. It is intended as a backend service, which can be connected to a customer’s Content Management System (CMS), Media Asset Management System (MAMS) or any other Middleware.

Usage policies

  • The Content API is a backend service, which can be connected to any customer’s middleware or backoffice systems. Direct access by end user’s applications (e.g. Apps, Player, …) is not allowed.
  • Keep the API key secret and well protected. This especially means that you must not ship it to any end user applications (e.g. Apps, Player, Binaries, …)

API description

For being able to access glomex Content API, you need an API key which can be obtained through glomex Support. By supplying this api_key, the system will identify and authorize you as an authorized caller and known which data needs to be returned.

Therefor Content API supports two major use cases:

  • As a MES publisher you want to get a feed of all content which is currently available within the glomex MES.
  • As a MDS customer you want to get a feed of your video content which is stored in the glomex MDS.

Technically the Content API is implemented as a JSON based REST API. For security reasons it is available through HTTPS only.

The Content API base URL is:

https://content-api-prod-eu-west-1.mes.glomex.cloud/feed

In case of success it returns HTTP status 200. The response body is a JSON object containing a list of video objects and some additional control data.

In case of logical errors (e.g. unauthorized calls), the API returns a 4xx HTTP status code with a JSON body containing some error code and description.

Other HTTP status codes (e.g. 5xxx) might be returned in case of server errors or temporary unavailability.

The API provides two routes, which will be described within the subsequent chapters:

  • Get feed by dates
  • Get single video by id

Get feed by dates

As the name indicates, the glomex Content API implements a content feed. The standard use case is to call it periodically and to retrieve all video objects which were recently added or changed. This is implemented by the API route “Get feed by dates” which is described within this chapter.

Request

You’re free to specify the required time interval as you need by adding from and to timestamps to the request.

For proper handling of large result sets, the Content API implements a paging. This means that the number of video objetcs contained in the JSON result will be limited to a reasonable number of objects. As indication that more objects follow on the next page and to enable the page retrieval, the API will return a next_page_token.

Following parameters can be appended as URL GET parameters:

Parameter Type Example Description
api_key string api_key=GHZj9hgs8.... customer specific APIkey (mandatory!)
from unixtime from=1479362157 beginning of the time window the videos were created or modified. Default is to deliver all videos.
to unixtime end=1479375572 end of the time window the videos were created or modified. If no date is given the default is “now”.
q string q=stars Restricts the result set by executing a full text search for the given phrase within video titles and descriptions. Search phrase needs to be URLencoded. e.g. champions%20league
limit number limit=200 Limits the maximum number of results per result page
next_page_token string next_page_token=cGbsj451a... Needs to be taken from the previous result page and tells the API to retrieve the next result page

End point:

https://content-api-qa-eu-west-1.dev.mes.glomex.cloud/feed?api_key=<APIkey>

Example:

Here’s an example of a complete API call, retrieving all video meta data which was added or changed since 06/28/2017 2:53pm (UTC) (equals to 1498661580 unix time stamp) with a page size of 50 videos:

GET https://content-api-prod-eu-west-1.mes.glomex.cloud/feed?api_key=xyz1y73v3g&limit=50&from=1479362157

Response

In case of a success, the API return a HTTTP status code 200 together with a JSON response body.

The reponse consist of some control data, followed by a list of video objects. It is fairly easy understandible by viewing following example:

{
    "generated_at": 1498492487,
    "limit": 50,
    "total": 4,
    "videos": [
        {
            "clip_id": "v-bdpo8embs3uh",
            "tenant_id": "t-ru",
            "start_date": 1498449600,
            "end_date": null,
            "modified_at": 1498046330,
            "created_at": 1498038182,
            "titles": {
                "de": "Zum grünen Wald"
            },
            "descriptions": {
                "de": "Im Restaurant \"Zum grünen Wald\" trifft gehobene französische Küche auf gutbürgerliche Speisen. Früher wurde noch vor Ort ein hauseigener Apfelwein hergestellt, heute wird er aus der Region bezogen. Hier ist für jeden etwas dabei."
            },
            "clip_duration": 151640.0,
            "midroll_offsets": [ ],
            "language": "de",
            "keywords": [
                {
                    "keyword": "Mein Lokal"
                },
                {
                    "keyword": "Bombay Lounge"
                },
                {
                    "keyword": "Frankfurt"
                }
            ],
            "images": [
                {
                    "id": "i-bdqd1veugaw9",
                    "titles": {
                        "de": "Mein Lokal, Dein Lokal"
                    },
                    "url": "https://imageservice.glomex.com/pis/glomex/6d64DVNXwntjQJEqED1IIp3sZ3lTlPudnEo084NJwCinTD2uZlJ70ZZC8fd1C3TpeFkuhW5t8_zwzEuhyVe5N0sFR3Ack3K_MQeAN2tFaGOmxhzqUxqsZD81pCpAZbjlYByqCyK_VGEUVaCs2vLzAKM/profile:original"
                }
            ],
            "taxonomies": { 
                "categories": [
                    {
                        "id": "tx-b5mmqcm19f29",
                        "titles": {
                            "de": "Auto & Motor",
                            "en": "Cars & Motor"
                        },
                       "images": {
                           "category_image": {
                               "id": "i-b6ljwqfbustd",
                               "titles": {
                                   "de": "Cars & Motor",
                                   "en": "Cars & Motor"
                               },
                               "url": "https://i3.glomex.com/pis/glomex/2981DVNXwntjQJE-bbaCWZwbsyE9wqZKNNnvAnGB7lo8ndHRDVVFGqujUdiDng8WIHUPhbP7PwszCD58a-6quq7Cw_ShbxvEdmLYH5N3o1skrajGfVkV_0DkVYTES2i5RRwdAZnY8darYVXZrBZkhaI/profile:original"
                           }
                       }
                    }
                ], 
                "format": [
                    {
                        "id": "tx-b6qhmj5r6osp",
                        "titles": {
                            "de": "Café Puls",
                            "en": "Café Puls"
                        },
                        "images": { }
                    }
		        ],
                "genres": [
                    {
                        "id": "tx-bb4yrrq2lv4x",
                        "titles": {
                            "de": "Show",
                            "en": "Show"
                    },
                        "images": { }
                    }
		        ],
                "video_types": [
                    {
                        "id": "tx-b5mnxofejxyx",
                        "titles": {
                            "de": "Clip",
                            "en": "Clip"
                        }
                    }
                ],
                "channel": [
                    {
                        "id": "tx-b5ncjmdyz5jd",
                        "titles": {
                            "de": "kabel eins",
                            "en": "kabel eins"
                        },
                        "images": {
                            "player_logo": {
                                "id": "i-bc3ntn15sca9",
                                "titles": {
                                    "de": "kabel eins",
                                    "en": "kabel eins"
                                },
                                "url": "https://i2.glomex.com/pis/glomex/608eDVNXwntjQJE-bbaCWZwbsyE9wqZKNNnvAnGB7lo8ndHRDVVFGqujUdiDng8WIHUPhbP7PwszCD58a-6quq7Cw_ShbxvEdmLZ0KBc9jDLsCdK0CckWdljzVwn_vb-8NyVVFxo-SDTogzpACYk_jU/profile:original"
                            },
                            "channel_logo": {
                                "id": "i-b6a9hajc1nx5",
                                "titles": {
                                    "de": "kabel eins",
                                    "en": "kabel eins"
                                },
                                "url": "https://i3.glomex.com/pis/glomex/9c36DVNXwntjQJE-bbaCWZwbsyE9wqZKNNnvAnGB7lo8ndHRDVVFGqujUdiDng8WIHUPhbP7PwszCD58a-6quq7Cw_ShbxvEdmLZ0KBc9jHZHArYJHX8LOoTjzTb1wPkL-ov-mgMrM5mgL0jA0EU_bc/profile:original"
                            }
                        }
                    }
                ]
            }
        },
        {
        // *** NEXT VIDEO OBJECT***
        }
    ]
}

Here’s the description of the individual response fields:

Control data

On top level, you can find some generic control data:

Field Type Example Description
generated_at Unixtime “generated_at” : 1498492487 Timestamp the request was generated
limit number “limit”: 50 requested page limit
total number “total”: 4 total number of video objects contained with the result (can be larger than “limit” due to paging)
next_page_token string “next_page_token” : “cGbsj451a…” Needs to be provided to the subsequent API call to retrieve the next result page

Video objects

The vido objects are contained within an object list:

Field Type Example Description
video list of objects “videos”: [
{ … },
{ … },

]
List of video objects (see below for details)

Each video object consist of:

Field Type Example Description
clip_id string “clip_id”: “v-bdpo8embs3uh” Unique ID of this video clip
tenant_id string “tenant_id”: “t-ru” Content Owner ID
start_date Unixtime “start_date”: 1498449600 Beginning of the time window where the clip may be viewed
end_date Unixtime “end_date”: null End of the time window where the clip may be viewed (null means “not limited”
modified_at Unixtime “modified_at”: 1498046330 Last modification timestamp
created_at Unixtime “created_at”: 1498038182 Creation timestamp
titles Object "titles": { <br> "de": "Zum grünen Wald", <br> "en": "Green forest" <br>} Video title(s), might be given in multiple languages
descriptions Object “descriptions”: {
“de”: “Im Restaurant …”,
“en”: “Within the restaurant …”
}
Video description, might be given in multiple languages
clip_duration Number “clip_duration”: 151640.0 Clip duration in ms
midroll_offsets Object “midroll_offsets”: [ ] Midroll offest timestamps
language string “language”: “de” Language of the video audio track
keywords Object “keywords”: [
{“keyword”: “Mein Lokal”},
{“keyword”: “Bombay Lounge”}
]
List of keywords
images Object “images”: [ {
“id”: “i-bdqd1veugaw9”,
“titles”: {“de”: “Mein Lokal, Dein Lokal” },
“url”: “https://imageservice.glomex.com/..."
} ]
List of related images. Each containing a unique id, titles and a url
taxonomies Object “taxonomies”: { … } See below for more details

Taxonomies

Taxonomies are used to classify the video. Depending on the data provided by the Content Owner, taxonomies may contain several objects describing the categorization of the video.

Object name Name in MES Examples
channel Channels AFP, dpa, Copa90, neuwagen.de, Promiflash, ProSieben, Puls4, …
categories Categories Cars & Motor, Celebrities, Cinema & TV, Fashion & Beauty, Food & Drink, Health & Fitness, Lifestyle & Docutainment, News, Social & Fun, Sport, Travel & Adventure
format Shows Abenteuer Leben, AKTE, Galileo, Germany’s next Topmodel, The Voice of Germany, …
genre N/A e.g. Action, Children & Family, Comedy, Documentary, Drama, Fantasy, Food, Infotainment, News, Reality, Science fiction, Series, Show, Sports, Thriller, Weather, …
For a complete list, please refer to MES Onboarding Guide - Apendix
video_types N/A Bonus Material, Clip (default), Deleted Scenes, Full Episode, Main Film, Livestream, Preview, Trailer
For a complete list, please refer to MES Onboarding Guide - Apendix

The values of the taxonomies will change over time, e.g. when we introduce new categories or channels. For the most concurrent values please refer to either:

Each taxonomy is represented as a list ob objects, meaning that a video could be to e.g. two genres. Each of those objects consists of a unique id, titles in different languages and optional images.

Field Type Example Description
video_types Object “video_types”: [{
“id”: “tx-b5mnxofejxyx”,
“titles”: {“de”: “Clip”}
}]
Classification of Video type
channel Object “channel”: [ {
“id”: “tx-b5ncjmdyz5jd”,
“titles”: {“de”: “kabel eins”}
}]
MES channel
categories Object “categories”: [ {
“id”: “tx-b5mmqcp0vy35”,
“titles”: {“de”: “Lifestyle & Dokutainment”}
}]
MES Category
format Object “format”: [ {
“id”: “tx-b6qhmj5r6osp”,
“titles”: {“de”: “Café Puls”}
}]
MES Show
genre Object “genre”: [ {
“id”: “tx-bb4yrrq2lv4x”,
“titles”: {“de”: “Show”}
}]
MES Genre
images Object “images”: {
“player_logo”: {
“id”: “i-bc3ntn15sca9”,
“titles”: {
“de”: “kabel eins”},
“url”: “https:…” } },
“channel_logo”: {
“id”: “i-b6a9hajc1nx5”,
“titles”: {“de”: “kabel eins”},
“url”: “https:…” }
}
}
List of related images, each containing Id, title and URL. player_logo is to be displayed within the player along with the video (Content Owner logo). channel_logo indicates the MES channel

Errors

In case of a logical error, the Content API returns a HTTP 4xx code and an error object with an error code and a human readable description.

In case of an invalid api_key it e.g. returns:

{
    "errors": {
        "api_key": [
            "Invalid API key"
        ]
    }
}

Get single video by id

If you just want to get the meta data of a single video, you can use this route.

Request

Parameter Type Example Description
api_key string api_key=GHZj9hgs8.... customer specific APIkey (mandatory!)
ClipId string v-123456 Id of the Video Clip you want to request

End point:

https://content-api-qa-eu-west-1.dev.mes.glomex.cloud/feed/<ClipId>?api_key=<APIkey>

Example:

GET https://content-api-qa-eu-west-1.dev.mes.glomex.cloud/feed/v-123456?api_key=oC2G5N

Response

As response, the meta data of the requested video clip is returned. The meta data format equals to what was described before in chapter “Get feed by dates”.

Errors

As described before in chapter “Get feed by dates”.

Feed as Media RSS XML

We also support the output as a Media RSS XML. For more information, please contact us via service@glomex.com

Pre-filtered feeds

If you wish, glomex can prefilter your feed. Following filters are supported:

  • Language (e.g. “en”, “de”)
  • Channel (e.g. “ProSieben”)
  • Categories (e.g. “Celebrities”)
  • Show (e.g. “Germanys Next Top Model”):
  • Keywords (e.g. “Meghan”, “Brexit” )

Please contact service@glomex.com or your glomex contact person for more information.