openapi: 3.0.3
x-bc-implicit-head: true
x-bc-implicit-options: true
x-bc-upstream: 'http://backend_server'
info:
  title: EPG API Reference
  description: |-
    Reference for the Brightcove EPG API, used to create and retrieve an Electronic Programming Guide for a channel created in Studio - see [Using Cloud Playout to Stream VOD Videos](https://studio.support.brightcove.com/cloud-playout/index.html) for details on how to create a channel.

    For additional information on the API, see the **[Overview: EPG API](/epg/getting-started/overview-epg-api.html)**.

    **The EPG API and Cloud Playout are currently in *limited availability*. If you are interested in trying it out, contact your Account Manager.**

     **Base URL**: https://sm.cloudplayout.brightcove.com
  version: 1.0.0
  x-bc-access: public
servers:
  - url: 'https://sm.cloudplayout.brightcove.com'
    variables: {}
tags:
  - name: EPG
    description: Operations for creating/retrieving an Electronic Programming Guide.
paths:
  '/accounts/{account_id}/channels/{channel_id}/epg':
    get:
      tags:
        - EPG
      summary: Get an EPG
      description: |-
        'Retrieve an EPG generated by Video Cloud for a channel'
      operationId: GetEPG
      security:
        - BC_OAuth2:
          - video-cloud/playlist/read
          - video-cloud/video/read
      parameters:
        - name: account_id
          in: path
          description: Video Cloud account ID
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: channel_id
          in: path
          description: >-
            The channel ID. The channel id can be found in the browser URL when you are in the Channel view of the Cloud Playout section of Studio: `https://studio.brightcove.com/products/videocloud/cloudplayout/channel/2c73c2112f794e6eb80be1284a495674`
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: limit
          description: >-
            'Number of items to return - 100 items are returned by default. **Note** that the limit value may prevent all programmes for the specified time period from being returned. See [EPG API Best Practices](/cloud-playout-apis/getting-started/epg-best-practices.html) for more information.'
          explode: true
          in: query
          schema:
            example: 20
            format: int32
            type: integer
          style: form
        - name: start
          description: >-
            'Start date-time for the EPG in URI-encoded ISO 8601 Date format. Note that the span of the `start`/`end` times must not exceed 14 days. Default is 14 day before the current date-time'
          explode: true
          in: query
          schema:
            example: '2020-07-24%2015%3A30%3A00%20%2B0530'
            type: string
          style: form
        - name: end
          description: >-
            'End date-time for the EPG in URI-encoded ISO 8601 Date format. Note that the span of the `start`/`end` times must not exceed 14 days. Default is the current date-time'
          explode: true
          in: query
          schema:
            example: '2020-07-24%2015%3A30%3A00%20%2B0530'
            type: string
          style: form
        - name: include_ads
          description: >-
            'Set this to true to include ads in the response. Default is `false`'
          explode: true
          in: query
          schema:
            example: true
            type: boolean
          style: form
        - name: Content-Type
          in: header
          description: 'Content-Type: application/json'
          required: true
          style: simple
          explode: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: 'Authorization: Bearer access_token (see [Getting Access Tokens](/oauth/guides/getting-access-tokens.html))'
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: '200'
          content:
            text/xml:
              schema:
                $ref: '#/components/schemas/GetEPGResponse'
        '400':
          description: >-
            NOT_AVAILABLE: The resource you are requesting is temporarily unavailable
        '401':
          description: >-
            UNAUTHORIZED: Authentication failed; check to make sure your policy
            key is correct
        '404':
          description: >-
            RESOURCE_NOT_FOUND: The api could not find the resource you requested
        '422':
          description: |-
            The requested records cannot be returned - there are several causes that will be detailed in the message:

            - EPG Start Time cannot be greater 14 days from Channel Start or Current Time, whichever is greater
            - EPG Start Time cannot be older than 14 days before the current time
            - EPG Interval must be less than or equal to 14 days (start time and end time should be within 14 days limit)
            - The Channel will be in running state in the requested Time window (EPG requested with start time beyond scheduled channel stop time) Start Time needs to be provided or should be less than End Time (start time < end time)
        '500':
          description: |-
            UNKNOWN: Issue in Brightcove system; try again later.
            TIMEOUT: Server likely too busy; try again later.
      deprecated: false
      x-operation-settings:
        CollectParameters: false
        AllowDynamicQueryParameters: false
        AllowDynamicFormParameters: false
        IsMultiContentStreaming: false
components:
  schemas:
    GetEPGResponse:
      title: EPG Response
      description: |-
        The EPG XML adhering to the [XML TV standard](https://repository.data2type.de/XMLTV/v_1.47/html/index.html).

        Example:

        ```
        <?xml version="1.0" encoding="utf-8"?>
        <tv source-info-name="Cloudplayout Schedules" source-info-url="http://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>
        ```

        The `keyword` in each program item contains base64-encoded json value containing the following metadata:
        - `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` is a comma-separated list of tags, if any
        - custom metadata is the set on name/value custom fields set for the video

        Example:

        ```
        {
          "video_id":"70701216482202",
          "order":1,
          "tags":"children,comedy",
          "custom_metadata":{
            "region":"africa",
            "songs":5
          }
        }
        ```
      type: string
  securitySchemes:
    BC_OAuth2:
      type: oauth2
      description: >-
        Brightcove OAuth API. See the [support documentation](/oauth/index.html) or [Getting Access Tokens](/oauth/code-samples/oauth-api-sample-get-access-token.html) to learn more
      flows:
        clientCredentials:
          tokenUrl: 'https://oauth.brightcove.com/v4/access_token'
          scopes:
            video-cloud/cloud-playout/read: Read channel data
