Retrieving events for an EPG window – pre-defined queries

Using pre-defined queries

To retrieve events for an EPG window, use the pre-defined query API, which both abstracts away the complexity of the underlying data model and provides for the most performant query.

This API allows the user/client to:

Get a slice of EPG across all channels using a default time period
Get a slice of EPG across all channels using time period
Get a slice of EPG across all channels using time offset
Get a slice of EPG for a specific channel (bbc_one)
Limit the EPG details returned to only those events that are playable on a specific device type (rather than filtering on the client side)

Request

To retrieve events for an EPG window, either for a default time period, or by using other parameters, send a GET request to:

https://<host>:<port>/<endpoint>/metadata/epg

Headers

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

Mandatory arguments

None

Other arguments

All these arguments are query parameters:

from – the lower bound (time) from which we want programmes either specified in ISO8601 format, or as a time offset (e.g. +08:00 or -08:00)
to – the upper bound (time) to which we want programmes either specified in ISO8601 format, or as a time offset (e.g. +08:00 or -08:00)
channel – a specific channel ID
fields – a list of fields names to return in the response
deviceType – the device type (e.g., Android)
page – the page of results to retrieve
limit – the page size
Accept-Language – the language (locale) of the response data

Response

A successful request returns an HTTP 200 status.

A bad request returns an HTTP 404 status.

Example

Retrieving events for a defined EPG window, for a specific channel, returning a specified field:

XML

https://<host>:<port>/metadata/v1/epg?from=1643389200&to=1643389200&channel=GLOBAL_bbc_one&fields=id&fields=Title