Overview: EPG API

This topic provides and overview of the EPG API, which is used with Cloud Playout.

Introduction

There are two APIs related to Cloud Playout:

Authentication

The Cloud Playout APIs use the Brightcove OAuth system to authenticate requests through an access token that is passed in an authorization header with the request:

Authorization: Bearer {access token}

Access tokens are retrieved using the OAuth API - see Getting Access Tokens for details. You will also need client credentials to authenticate the requests for access tokens. These can be created in the Admin section of Studio - see Managing API Credentials. The permissions your credentials will need for the EPG API are:

EPG API Permissions
EPG API Permissions

EPG request parameters

The following optional query parameters can be added to the EPG request:

EPG API Query Params
Parameter Default Value Description
start (14 days prior to now) The date-time from which the EPG responses can be queried and returned in ISO 8601 Date format
end (now - the current date-time) The date-time until which the EPG responses can be queried and returned in ISO 8601 Date format
limit (all programs) An integer value that controls the number of programmes returned in one request. Note that the limit value (default: 100) may prevent all programmes for the specified time period from being returned. See EPG API Best Practices for more information
include_ads false Set this to true to include ads in the response

Notes

  1. The start/end window cannot exceed 14 days. Start can be 14 days behind from current date-time to query historic EPG. You can also future EPG data for up to 14 days from the current date-time.
  2. If the difference between the end time and start time is greater than 14 days, then the API generates only 14 days from the time time requested to end time or 14 days, whichever is earlier.
  3. Both start and end can accept date-time values with and without timezone offsets - if no timezone offset is included, UTC is assumed.
  4. Both start and end must be URI-encoded:
    URI Encoding
    ISO 8601 Sample URI-Encoded
    2020-07-24 15:30:00 2020-07-24%2015%3A30%3A00
    2020-07-24 15:30:00 +0530 2020-07-24%2015%3A30%3A00%20%2B0530

Sample EPG API response

Below is a sample response from the API:

<?xml version="1.0" encoding="utf-8"?>
    <tv source-info-name="Cloudplayout Schedules" source-info-url="https://www.cloudplayout.qa.brightcove.com">
        <channel id="9fb8032ff2fe4f55b388d8969c22ca58">
            <display-name>MyCloudChannel</display-name>
            <icon src="https://bc-cloudplayout-prod.s3.amazonaws.com/default_channel_image.png"/>
        </channel>
        <programme channel="9fb8032ff2fe4f55b388d8969c22ca58" start="20201120132000" stop="20201120132228">
            <title>Frozen</title>
            <desc>FrozenMultiLanguage</desc>
            <length units="seconds">147.605</length>
            <icon src="https://cf-images.us-east-1.qa.boltdns.net/v1/jit/6063799219001/43d57501-b98a-4708-bdd1-a09081f7a585/main/1280x720/1m13s802ms/match/image.jpg" width="1280" height="720"/>
            <category>video</category>
            <keyword>eyJ2aWRlb19pZCI6IjcwNzAwNDQxMDk2MjAyIiwib3JkZXIiOjEsInRhZ3MiOiJjaGlsZHJlbixjb21lZHkiLCJjdXN0b21fbWV0YWRhdGEiOnsicmVnaW9uIjoiYWZyaWNhIiwic29uZ3MiOjV9fQ==</keyword>
        </programme>
        <programme channel="9fb8032ff2fe4f55b388d8969c22ca58" start="20201120132228" stop="20201120133228">
            <title>LiveDemo</title>
            <desc>Live Demo</desc>
            <length units="seconds">600.0</length>
            <icon src="https://img.brightcove.com/cloudplayout/live-icon.jpg" width="1280" height="720"/>
            <category>live</category>
            <keyword>eyJ2aWRlb19pZCI6IjcwNzAxNDg0MjA3MjAyIiwib3JkZXIiOjIsInRhZ3MiOiJjcC1saXZlLXBsYWNlaG9sZGVyLGR1cmF0aW9uLTAwOjEwOjAwIiwiY3VzdG9tX21ldGFkYXRhIjp7InJlZ2lvbiI6Im5vcnRoIGFtZXJpY2EifX0=</keyword>
        </programme>
        <programme channel="9fb8032ff2fe4f55b388d8969c22ca58" start="20201120133228" stop="20201120133327">
            <title>ChildrenComedy</title>
            <desc>ChildrenComedy</desc>
            <length units="seconds">59.164</length>
            <icon src="https://cf-images.us-east-1.qa.boltdns.net/v1/jit/6063799219001/9430773f-76f5-476e-964d-a13b40cab90a/main/1280x720/29s582ms/match/image.jpg" width="1280" height="720"/>
            <category>video</category>
            <keyword>eyJ2aWRlb19pZCI6IjcwNzAxMjE2NDgyMjAyIiwib3JkZXIiOjMsInRhZ3MiOiJyb21hbmNlIiwiY3VzdG9tX21ldGFkYXRhIjp7InJlZ2lvbiI6ImFzaWEiLCJzb25ncyI6NX19</keyword>
        </programme>
        <programme>
            ...
        </programme>
    </tv>

Notes

  1. The start and end timestamps are in UTC time.
  2. The category and keyword entries are for internal purposes.

The EPG data contains multiple programme data where each programme represents details about the video or live asset:

<programme channel="27963aa756294a7c98ca1c2c459d4ba2" start="20201118232206" stop="20201118232305">
	<title>ChildrenComedy</title>
	<desc>ChildrenComedy</desc>
	<length> units="seconds">59.164</length>
	<icon> src="https://cf-images.us-east-1.qa.boltdns.net/v1/jit/6063799219001/9430773f-76f5-476e-964d-a13b40cab90a/main/1280x720/29s582ms/match/image.jpg" width="1280" height="720" ></icon>
	<category>video</category>
	<keyword>eyJ2aWRlb19pZCI6IjcwNzAxMjE2NDgyMjAyIiwib3JkZXIiOjEsInRhZ3MiOiJjaGlsZHJlbixjb21lZHkiLCJjdXN0b21fbWV0YWRhdGEiOnsicmVnaW9uIjoiYWZyaWNhIiwic29uZ3MiOjV9fQ==</keyword>
</programme>

Here, the keyword contains base64 encoded json value. The decoded value of the keyword is shown below.

  • video_id: is the identifier for the video as in Video Cloud.
  • order: is the order of the asset in the Cloud Playout program list.
  • tags: comma separated (if any) - associated with the corresponding video in video cloud.
  • custom metadata: (if any, represented as name/value pairs) associated with the corresponding video in video cloud.
{
  "video_id":"70701216482202",
  "order":1,
  "tags":"children,comedy",
  "custom_metadata":{
    "region":"africa",
    "songs":5
  }
}

The EPG and Bumpers

How the EPG handles bumpers

The EPG will not include the bumpers themselves. The durations of the bumpers will be reflected in the following way:

  • Pre-roll bumper durations are added the following video duration
  • Post-roll bumper durations are added to the previous video duration

Potential problems

There are two things you can do that will cause the EPG to be inaccurate:

  • Tagging videos to be both pre-roll (cp-preroll-bumper) AND post-roll (cp-postroll-bumper) will cause the EPG to be inaccurate because it depends on the tag to decide where to add the duration. If the video has both tags, the bumper duration will be added to both the previous and next video.
  • You can move bumpers in the Cloud Playout program list, but if you arrange them such that a pre-roll bumper is immediately followed by a post-roll bumper, both bumpers will play, but the EPG API will ignore them and the schedule for that time period will be empty.

limitations

  1. The EPG is generated on best effort / close to accurate.
  2. When the EPG is initially constructed from the playlist, there may be a start time error as the Cloud Playout takes some time to initiate the switching.
  3. EPG may not be consistent for every retrieval when the playlist is modified, because it is constructed dynamically based on the current information it holds. Some actions that will alter the EPG include reordering the playlist or adding/deleting assets in the playlist.
  4. If any malfunction happens in the switching and the switch time is not accurate,there could be transit inaccuracy for the future EPG. Some examples of actions that could cause this would be a playlist switch or deleting the current active asset in playlist.
  5. Consumers of the EPG should be requesting it as close to realtime as possible to get the most accurate version.