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.
DRAFT(When channel’s scheduled start time/stop time in the future)
DRAFT(Stopped channels will enter again in to DRAFT state)
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
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
- 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.
Here is how we recommend that your paginate your queries for a large number of records to get the best performance:
Start with a request using no query parameters:
- 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
- For additional pages of data, submit a request with the
startparameter set equal to the
stopattribute value in the
programmetag of last record returned in the previous response - plus 1 second.
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>
stop value in the last record is a timestamp in the form
YYYYMMDDhhmmss, so in ISO 8601 format:
Adding one second to this value, we get
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
RUNNINGstate, 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
INACTIVEstate; 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
limitwill be given preference and that many records will be generated - in this case you might receive records behind the given end time.
endwindow cannot exceed 14 days.
startcan 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.
endcan accept date-time values with or without timezone offsets - if no timezone offset is included, UTC is assumed
endvalues 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)