Respond to metadata change notifications

Overview

When the client application receives a metadata change notification, it should take the appropriate action(s) depending on the contents of the notification.

The notification body has the following format:

CODE

{
   "data": {
      "Reference": "<id>",
      "Start": "<start_date_time>",
      "End": "<end_date_time>",
      "Status": "Update",
      "Details": "<type>"
   }
}

where:

id is the ID of the channel/programme/content that the notification applies to.
start_date_time is the date/time of the start of the change time window (in Unix time).
end_date_time is the date/time of the end of the change time window (in Unix time).
type is the notification type. It is one of:
- Content Change – the change is to the content (for example, title, description, actors, and so on).
- EPG Change – the change is to the scheduled time in the EPG.

Request

To request updated metadata for programmes, VOD content, or channels in response to a metadata change notification, send a GET request to:

CODE

https://<host>:<port>/metadata/delivery/changes

You will typically request the changes since a particular time.

Changes are returned in chronological order, and can be paginated.

Headers

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

Mandatory arguments

None

Other arguments

All these arguments are query parameters:

since – the timestamp from which to get changes (in Unix time)
type – the type of entity for which to get changes. One of: programme, vod, or channel. If not specified, all changes are returned.
fields – a list of fields names to return in the response. (By default, all fields are returned.) See the examples below and the MDS API documentation for a list of available fields:
page – if using pagination, which page of results to retrieve. (The first page is number 1, not 0.)
limit – the number of results to return per page
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
locale – the locale in which to retrieve the metadata

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.

Example

A basic response would look like this, where change is a copy of the record that has been updated:

CODE

{
   "changes": [{
      "id": "GLOBAL_p1",
      "action": "reschedule",
      "type": "programme",
      "change": {
         "id": "GLOBAL_p1",
         "serviceRef": "GLOBAL_sky_one",
         "period": {
            "start": 1454284800.0,
            "end": 2147483707.0,
            "duration": 693198907
         },
         "Title": "Game of Thrones"
      }
   }],
   "total_records": 1
}

Examples

Get all recorded changes for all available records

CODE

https://<host>:<port>/metadata/delivery/changes?locale=en_GB

Get all recorded changes since a certain time

CODE

https://<host>:<port>/metadata/delivery/changes?locale=en_GB&since=1643912152

Get all changes for programmes since a certain time

CODE

https://<host>:<port>/metadata/delivery/changes?locale=en_GB&since=1643912152&type=programme

Get page 3 of changes since a certain time with page size 100 (records 201–300)

CODE

https://<host>:<port>/metadata/delivery/changes?locale=en_GB&since=1643912152&page=3&limit=100

Get EPG changes for a specific channel since a certain time

Groups programme changes into a single channel change for each affected channel, and provides the time period for the EPG that changed:

CODE

https://<host>:<port>/metadata/delivery/changes?locale=en_GB&since=1643912152&type=channel

In this case, the response body does not contain the programme information, but instead the channel reference and the start/end time period. You can use this information to retrieve an EPG update using the /epg or /btv/programmes APIs.

For example:

CODE

{
  "changes": [{
      "id": "Sky One",
      "action": "reschedule",
      "type": "channel",
      "start": 1675209600,
      "end": 1675216800
  }, {
      "id": "Sky Two",
      "action": "reschedule",
      "type": "channel",
      "start": 1675213200,
      "end": 1675216800
  }],
  "total_records": 2
}

Request

Headers

Mandatory arguments

Other arguments

Response

Example

Examples

Get all recorded changes for all available records

Get all recorded changes since a certain time

Get all changes for programmes since a certain time

Get page 3 of changes since a certain time with page size 100 (records 201–300)

Get EPG changes for a specific channel since a certain time

See also