Respond to metadata change notifications | NAGRAVISION Documentation Portal

Overview

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

Depending on how the platform is configured, EPG changes are notified in this format, in the format described in Message format – EPG update, or both. A client should handle both formats.

The notification body has the following format. All values are strings:

JSON

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

where:

id is the ID of the channel that the notification applies to.
start_date_time is the start of the change time window, in Unix time (for example, "1792410300.0").
end_date_time is 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 programme's metadata (for example, title, description, actors, flags, or ratings), not its scheduled time.
- EPG Change – the change is to the scheduled time in the EPG. If a channel has both kinds of change in the same period, the notification says EPG Change.

Changes are grouped by channel: one notification is sent for each channel that has changed, every five minutes by default, covering changes within six hours before or after the current time.

Request

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

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:

{
   "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

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

Get all recorded changes since a certain time

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

Get all changes for programmes since a certain time

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)

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:

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:

{
  "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
}