EPG Workflow
Purpose
The EPG forms the core of the IceTV service, on top of this core we layer interactive services like series and keyword recording, new shows and most popular shows.
The IceTV EPG contains a rich set of meta-data above and beyond that provided by the EIT guides from the broadcaster, in addition to time and title information we also provide actors, directors, year of production, country of origin, series and episode numbers, images, subtitle information, more items are added as need and availability dictate (See Show for details).
Procedure
The “Series” API call (See series for details) provides series recordings, new shows and most popular.
The “Keyword” API call (See keywords for details) provides keywords.
The “Shows” API call (See shows for details) provides the EPG and timer information.
In order to ensure that the information in the EPG cross-references with series recordings and keywords correctly it is vital that you call the Series, Keyword (if required) and Shows API calls in the correct order. You must always call Series and Keyword immediately prior to any calls to Shows as Series and Keywords reference Shows and Timers (which are part of the Shows response) reference Series and Keywords, a partial data model appears below.
In order to support incremental EPG updates an application must nominate whether it wishes to receive the full 7-day EPG or just the updates since the last download.
In order to receive a full 7-day download the application must send last_update_time=0 in the request URL.
The response will include a new value for last_update_time that must be used in the next download in order to receive just the changes to the EPG since that time.
e.g. last_update_time=0, response contains last_update_time=1342159886, next request for EPG last_update_time=1342159886, response is an incremental download containing changes from 1342159886 to the current time. last_update_time is a Unix timestamp.
Series Recordings (and keywords) Handling
We do not support incremental updates for Series Recordings and Keywords, each call will send the current state of all the entries to the calling device so you must delete the currently cached values and replace them with the new data.
It is entirely possible that you will receive no records from your API call which would occur if the user has deleted all their series recordings or keywords, in this case you would delete your cache and put nothing back in its place.
Locally Created Series Recordings
If the PVR supports local creation of series recordings, often initiated by pressing record twice on a programme in the EPG grid view, the TV Recorder will be required to POST a series recording record to the IceTV server /series/recordings (See the Add a series recording API call for details).
The series recording information should be populated using the information from the EPG. The advanced options like start minutes, channel id ,network id, recording quality, recordings per day and airings need to be populated with sensible default values or provided by the user.
Sensible default values are as follows (See Series Recording for details).
|
start_minutes |
-1 |
|
channel_id |
-1 |
|
network_id |
-1 |
|
recording_quality |
Prefer HD |
|
airings |
First runs and re-runs |
|
recordings_per_day |
0 |
EPG Handling
In contrast to Series Recordings and Keywords we do support incremental updates for EPG, this requires a slightly more complex handling procedure.
The shows response (See shows for details) contains all the delete records first so as you process the response you just delete any records that have deleted_record=”1” in them, all the rest of the EPG records will then be either updates to existing records or new records.
Each IceTV show record contains a unique ID, we recommend maintaining an index into your EPG structure based on this ID as it is used in the EPG and for timers.