EPG API: Best Practices

This topic provides best practices for working with the Cloud Playout EPG API.

Introduction

The EPG API returns an XML Electronic Programming Guide for a Cloud Playout channel, useful for displaying program information on your web page or in your app. This topic provides some explanation of the how the API works and recommendations for using it most effectively.

Channel states

Active States

  • DRAFT (When channel’s scheduled start time/stop time in the future)
  • RE-SCHEDULING
  • SCHEDULED
  • STARTING
  • START_ERROR
  • CREATING
  • CREATE_ERROR
  • RUNNING

Inactive states

  • DRAFT (Stopped channels will enter again in to DRAFT state)
  • IDLE
  • STOPPING
  • STOP_ERROR
  • START_ERROR
  • DELETING (there will be no EPG records - this might cause the EPG API to return a 500 response code)
  • DELETE_ERROR (there will be no EPG records - this might cause the EPG API to return a 500 response code)

EPG Query Recommendation

  • The EPG query by default (without any query parameters for start, stop, or limit supplied) will return 100 EPG records (or all records if there are less than 100). The number returned can be changed by setting it in the limit parameter.
  • Records for up to 14 days will still be supplied by providing an explicit start time and end time, and also a higher limit value to the EPG Query.
  • Because processing time increases exponentially with the number of records to process, we recommend using a paginated way of querying EPG records (see Pagination below) for fetching bulk data.

Pagination

Here is how we recommend that your paginate your queries for a large number of records to get the best performance:

  1. Start with a request using no query parameters: 
    https://sm.cloudplayout.brightcove.com/accounts/{account_id}/channels/{channel_id}/epg
    • If the channel is not running, this will return 100 records from the channel start time or the current time, whichever is later.
    • If the channel is running, the 100 records will be a 50/50 mix of historical and future programs
  2. For additional pages of data, submit a request with the start parameter set equal to the stop attribute value in the programme tag of last record returned in the previous response - plus 1 second.

Example

Let's say your first query returns a response like this:

<tv>
	...
	<programme channel="channel_id" start="20210228000457" stop="20210228001457">
		<title>live</title>
		<desc>live</desc>
		<length units="seconds">600.0</length>
		<icon src="https://img.brightcove.com/cloudplayout/live-icon.jpg" width="" height=""/>
		<category>live</category>
		<keyword>eyJ2aWRlb19pZCI6IjcwNzAxMjE2NDgyMjAyIiwib3JkZXIiOjMsInRhZ3MiOiJyb21hbmNlIiwiY3VzdG9tX21ldGFkYXRhIjp7InJlZ2lvbiI6ImFzaWEiLCJzb25ncyI6NX19</keyword>
	</programme>
</tv>

The highlighted stop value in the last record is a timestamp in the form YYYYMMDDhhmmss, so in ISO 8601 format: 2021-02-28 00:14:57.

Adding one second to this value, we get 2021-02-28 00:14:58.

The query parameter for the next request will then be: start=2021-02-28%2000%3A14%3A57 - remember that the start (and end) parameter must be URI-encoded.

To retrieve all records, continue sending requests with increasing start values until you get an HTTP 422 response with the message "Channel won't be in running state in the requested Time window".

Additional notes on EPG response behavior

The following notes on how the EPG API works are intended to help you create requests that will get the desired response.

  • The EPG is dynamically constructed based on current state of the channel so if a channel is in any active states except RUNNING, then the EPG will produce future data from the scheduled channel start time.
  • If a channel is in RUNNING state, the EPG invoked without any query parameters will provide a mix (50% split - with a limit of 100, this would produce at-most 50 past records and 50 future records) of past & future schedules data.
  • When you stop or delete a channel, it will be in an INACTIVE state; the future EPG records will not be available since the channel has finished its run.
    • In such cases the EPG will return either an empty data set or a 422 error code.
    • In case historical data is needed for any of the inactive states, then EPG request must have a past start/end time in query parameters.
  • If EPG request has both an end time and limit, limit will be given preference and that many records will be generated - in this case you might receive records behind the given end time.
  • The start/end window cannot exceed 14 days. start can be 14 days earlier than the current date-time to retrieve an historic EPG. You can also query future EPG data for up to 14 days after the current date-time.
  • If the difference between the provided end time and start time is greater than 14 days, then the API generates schedules data for only 14 days from the time of the request to scheduled channel stop time or 14 days, whichever is earlier.
  • Both start and end can accept date-time values with or without timezone offsets - if no timezone offset is included, UTC is assumed
  • Both start and end values must be URI-encoded.

Reasons why EPG API would return a 422 Error code

  • 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)