Retrieving events for an EPG window – advanced queries

Where possible, you are recommended to use the pre-defined queries that are tuned for performance and abstract away the complexity of the underlying data model.

The query below allows for more targeted content retrieval, but it cannot be guaranteed that the response will be as performant as the predefined alternative.

Request

To retrieve events for an EPG window, send a GET request to:

https://<host>:<port>/metadata/delivery/<provider>/btv/programmes

Headers

Authorization: Bearer – bearer token
Content-Type: application/json

Mandatory arguments

provider - Narrows down queries to a single service provider to allow for API clarity and security.

Other arguments

All these arguments are query parameters:

filter - A list of key/value pairs, where key is the fieldname and value is the value the field should be. For example:
sort - A list of pairs, where a pair is a list containing a field name and a sort order with 1 ascending, and -1 is descending.
fields - A list of fields names to return in the response.
offset - The number of records to skip for pagination.
limit - The number of records to return for pagination.
cache - Sets or unsets HTTP headers; TRUE allows CDN caching, FALSE prevents CDN caching.
pretty - TRUE returns human-readable formatted JSON, FALSE returns compact and efficient JSON.

Response

A successful request returns an HTTP 200 status.

A bad request returns an HTTP 400 status.

An unsuccessful request returns an HTTP 401 status.

Examples

Retrieving events for an EPG window

In this use case, sufficient EPG data to render an EPG screen with eight channels and a three-hour window is required (e.g. the user can see from 10 AM to 2 PM). For optimisation purposes, the events should be retrieved per channel. In the example below, events on BBC1 with a start time before 2 PM, Oct 29th but after 2 PM Oct 28th are requested. This restriction on starting 24 hours earlier reduces the MDS's work when filtering on end-time. Events ending after 10 AM are then specified, with the Title, Description, Duration, Start, End and Rating fields, as these are the only fields used to render the EPG. Paging is not necessary since dates already restrict the returned items.

XML

https://<host>:<port>/metadata/delivery/<provider>/btv/programmes?filter={"locale":"en_GB", "serviceRef":"BBC1","period.start":{"$lte":1414591200,"$gte":1414490400},"period.end":{"$gte":1414576800}}&fields=["id","Title","Description","period.duration","period.end","period.start","Rating"]

If an event airs at a time that is different from its scheduled time (for example, because an earlier football match went to extra time), this is reflected in the airingStartTime and airingEndTime fields.

Retrieving detailed event information

In this use case, a user wants to view additional information about an event, such as show cast, episode data, technical information, etc. Since the event in question is known, its unique id is specified in the request, and no other filter is necessary, further fields are specified to retrieve the additional information needed to render the UI. Only the additional data is required as the information for "id", "Title", "Description" etc is already available.

XML

https://<host>:<port>/metadata/delivery/<provider>/btv/programmes?filter={"id":"ABC123"}&fields=["Audio","Definition","Episode","Language","productRefs"]