What's different?
Old: One endpoint for everything
The v2 and v3 EPG both return all of the information needed to produce an electronic program guide. This includes information about the Programs and when they are showing. The old endpoint also returned data for multiple channels in a single call, and allowed for fetching data for an arbitrary time range, meaning the amount of data returned can be huge.
New: Scheduling information and metadata are separated
In V4 we are splitting the EPG information up into two entities - one tracks the scheduling of programs (what appears when) and the other tracks the metadata of the program content. We also return schedule data only for one channel, for one day per request. Clients are expected to asynchronously query more data as needed, instead of fetching all data at once. Pagination is also not supported, instead results are limited by allowing only one day of data returned per request.
EPG search is not supported in new EPG APIs.
| Info |
|---|
The metadata service is intended to be shared between all of our services that relate to programs - live channels, recordings, VOD, and recommendations |
Graphically
The sum of the new metadata service and the scheduling service equals the functionality of the v2 EPG.
| Drawio | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Why does BroadcastSlot include information that is duplicated in the Program it contains?
To allow for the television provider to change the title.
Examples could include adding "Elokuva :" to the beginning of the title or translating the movie title to the local language.
Note: This does mean that it's possible for the BroadcastSlot title not to match the contents of the slot.
It also allows displaying content information in an EPG view without requiring a large number of API calls.
Common use cases
Display a programme guide for the next seven days for a specific user
| Service | Method | Endpoint | Purpose | Cacheable |
|---|---|---|---|---|
| Schedule | GET | /broadcast_slots | Contains the titles and thumbnails of the programs being displayed | Public, 900 seconds |
| User preferences | GET | /users/{user_id}/favourite_channel_lists/relationships/channels | Returns a compressed list of the channel ids contained in the users favourite channel lists | Private, 300 seconds, must-revalidate |
| License | GET | /user/{user_id}/channel_licenses | Returns the permissions that a user has for channels | Private, 600 seconds |
Apply the results of the third call to the first call before displaying the information.
Perform the second call if your user interface requires you to mark up favourite channels.
User clicks item in EPG, show Program details screen
| Service | Method | Endpoint | Purpose | Note | Cacheable |
|---|---|---|---|---|---|
| Schedule | GET | /broadcast_slots/{broadcast_slot_id}/programs | Returns the Program entities for that slot (most likely only one) | This will always include all the associated meta-data | Public, 900 seconds |