IceTV API documentation

Started by Daniel Hall at IceTV, March 15, 2016, 05:06:33 PM

Previous topic - Next topic

Daniel Hall at IceTV

Hi Everyone,

We are please to announce that we have just released the documentation for the IceTV EPG and Smart Recording API.

With this documentation it is possible for PVR projects to be able to integrate into IceTV's EPG and Smart Recording service.

To be able to utilize the service an application developer will need to be apply for a developer key, this can be done by emailing developer@icetv.com.au (this is detailed in the documentation).

The documentation can be found at http://developer.icetv.com.au/
Regards,

Daniel.
CTO.

DeltaMikeCharlie

#1
Thanks Daniel.

Would it be possible to have the "regions" entity carry some DST offset data like the DVB TOT currently does?  This would mean adding the current UTC offset, next transition date and next UTC offset.

prl

I've just had a quick look at it, and there were errors in the first two entries in "shows" that I looked at. The documentation says that "category" is an array of entries have only one element, "name", but a category actually looks like:
"category": [{"name": "Documentary","eit":"0x23"},{"name": "Movie","eit":"0x10"}]
I.e. each category entry has two elements, "name" and "eit", not just "name".

I was also hoping that the API might enumerate the legal values for "name" and "eit" in category (since the IceTV values for both "name" and "eit" use a completely different set of names and interpretations from broadcast TV), but even the mere existence of "eit" is missing in the documentation.

Having this enumeration of the "name", "eit" pairs is necessary for the implementation of IceTV Genre/Category labels on the Beyonwiz T series.

Similarly, the documentation for "credits" says that "director" and "actor" are string elements of "credits". That's simply not what the "credits" structure looks like:
"credits": {"director": "Johnnie To","actors": [{"name": "Simon Yam"},{"name": "Kelly Lin"},{"name": "Ka Tung Lam"}]}
There is no "actor" element at all, and "actors" is an array of "name" elements.

It's really a bit disappointing. I hope that protocol descriptions (which I haven't had a proper look at) are better.
Peter
Beyonwiz T4 in-use
Beyonwiz T2, T3, T4, U4 & V2 for testing

Daniel Hall at IceTV

Quote from: DeltaMikeCharlie on March 15, 2016, 06:25:18 PM
Thanks Daniel.

Would it be possible to have the "regions" entity carry some DST offset data like the DVB TOT currently does?  This would mean adding the current UTC offset, next transition date and next UTC offset.

We can also provide these in POSIX timezone string, so for example Sydney would be "EST+10EST+01,M10.1.0/02:00,M4.1.0/03:00". Will add this to the documentation as it requires a change on our end to set an application to use that.
Regards,

Daniel.
CTO.

Daniel Hall at IceTV

Quote from: prl on March 17, 2016, 01:16:04 PM
I've just had a quick look at it, and there were errors in the first two entries in "shows" that I looked at. The documentation says that "category" is an array of entries have only one element, "name", but a category actually looks like:
"category": [{"name": "Documentary","eit":"0x23"},{"name": "Movie","eit":"0x10"}]
I.e. each category entry has two elements, "name" and "eit", not just "name".

I was also hoping that the API might enumerate the legal values for "name" and "eit" in category (since the IceTV values for both "name" and "eit" use a completely different set of names and interpretations from broadcast TV), but even the mere existence of "eit" is missing in the documentation.

Having this enumeration of the "name", "eit" pairs is necessary for the implementation of IceTV Genre/Category labels on the Beyonwiz T series.

Similarly, the documentation for "credits" says that "director" and "actor" are string elements of "credits". That's simply not what the "credits" structure looks like:
"credits": {"director": "Johnnie To","actors": [{"name": "Simon Yam"},{"name": "Kelly Lin"},{"name": "Ka Tung Lam"}]}
There is no "actor" element at all, and "actors" is an array of "name" elements.

It's really a bit disappointing. I hope that protocol descriptions (which I haven't had a proper look at) are better.

These have been updated, looks like it was mostly due to differences in the JSON vs the XML feeds.
Regards,

Daniel.
CTO.

prl

Peter
Beyonwiz T4 in-use
Beyonwiz T2, T3, T4, U4 & V2 for testing

DeltaMikeCharlie


Daniel Hall at IceTV

Quote from: DeltaMikeCharlie on March 17, 2016, 06:54:13 PM
Quote from: Daniel Hall at IceTV on March 17, 2016, 05:06:56 PMWe can also provide these in POSIX timezone string
Thanks Daniel.

Oh, and this has been updated in the documentation as well.
Regards,

Daniel.
CTO.

DeltaMikeCharlie

Having read the examples more closely, I have noticed that the requests are all https.  Is there an option for using http?

Because of the limited Linux OS provided with the Topfield PVRs, I have to statically link absolutely everything.  This makes the openssl libraries huge and the TAPs even bigger.

prl

Quote from: Daniel Hall at IceTV on March 17, 2016, 05:07:36 PM
Quote from: prl on March 17, 2016, 01:16:04 PM
I've just had a quick look at it, and there were errors in the first two entries in "shows" that I looked at. The documentation says that "category" is an array of entries have only one element, "name", but a category actually looks like:
"category": [{"name": "Documentary","eit":"0x23"},{"name": "Movie","eit":"0x10"}]
I.e. each category entry has two elements, "name" and "eit", not just "name".

I was also hoping that the API might enumerate the legal values for "name" and "eit" in category (since the IceTV values for both "name" and "eit" use a completely different set of names and interpretations from broadcast TV), but even the mere existence of "eit" is missing in the documentation.

Having this enumeration of the "name", "eit" pairs is necessary for the implementation of IceTV Genre/Category labels on the Beyonwiz T series.

Similarly, the documentation for "credits" says that "director" and "actor" are string elements of "credits". That's simply not what the "credits" structure looks like:
"credits": {"director": "Johnnie To","actors": [{"name": "Simon Yam"},{"name": "Kelly Lin"},{"name": "Ka Tung Lam"}]}
There is no "actor" element at all, and "actors" is an array of "name" elements.

It's really a bit disappointing. I hope that protocol descriptions (which I haven't had a proper look at) are better.

These have been updated, looks like it was mostly due to differences in the JSON vs the XML feeds.

The field names for the JSON category entries have been corrected, but there's no proper enumeration of the values used for the two fields. The comment "Value as closest match to Table 28 in ETSI EN 300 468" really is a bit misleading, because IceTV uses multiple genre/category names for single Table 28 numerical values, and assigns names to Table 28 numerical values that the standards (both ETSI EN 300 468 and AS 4599) specify as "undefined content". The EIT content descriptor value 0x00 is both "undefined content" and given multiple text values by IceTV.

IceTV also seems to place "Adventure" with both codes 0x12 and 0x13. In Table 28 of ETSI EN 300 468, 0x12 is "adventure/western/war" and 0x13 is "science fiction/fantasy/horror".

Examples of other codes given multiple text values in the IceTV data are:
Ice  IceTV
EIT  Genre                AS 4599                        ETSI EN 300 468
---- -----                -------
0x10 Drama                Movie/Drama                    movie/drama (general)
0x10 Medical              Movie/Drama                    movie/drama (general)
0x10 Movie                Movie/Drama                    movie/drama (general)
0x11 Crime                Movie/Drama                    detective/thriller
0x11 Murder               Movie/Drama                    detective/thriller
0x11 Mystery              Movie/Drama                    detective/thriller
0x11 Thriller             Movie/Drama                    detective/thriller
0x12 Action               Movie/Drama                    adventure/western/war
0x12 Adventure            Movie/Drama                    adventure/western/war
0x12 Cult                 Movie/Drama                    adventure/western/war
0x12 War                  Movie/Drama                    adventure/western/war
0x12 Western              Movie/Drama                    adventure/western/war
0x13 Adventure            Movie/Drama                    science fiction/fantasy/horror
0x13 Fantasy              Movie/Drama                    science fiction/fantasy/horror
0x13 Horror               Movie/Drama                    science fiction/fantasy/horror
0x13 Sci-Fi               Movie/Drama                    science fiction/fantasy/horror
0x14 Animation            Movie/Drama                    comedy
0x14 Comedy               Movie/Drama                    comedy
0x14 Sitcom               Movie/Drama                    comedy


The documentation still doesn't describe the "credits" element correctly. It gives its fields as "director" and "actor", when the second of those fields is "actors", and the documentation simply says that it's an "array", without specifying what it's an array of (and it's not a simple array of strings). There is an example of what the JSON "actors" array actually looks like in the example in the documentation.

Sorry to be going on a bit over the Genre codes, but the numeric codes appear to be the only way to make use of this IceTV data reliably in the T series.
Peter
Beyonwiz T4 in-use
Beyonwiz T2, T3, T4, U4 & V2 for testing

DeltaMikeCharlie

The documentation states that the HTTP "Accept:" header needs to be set to "application/xml", however, I could only retrieve the "regions" entity using "text/xml".

http://developer.icetv.com.au/Home.html#src-917535_Home-HTTPAcceptheader

Here is the syntax that I had to use with wget:

wget.exe -O regions.xml --header="Accept: text/xml" "http://api.icetv.com.au/regions?api_key=[My_KEY]&application_version=1"

If I added an extension to the URI, then I could force XML format:

wget.exe -O regions.xml "http://api.icetv.com.au/regions.xml?api_key=[MY_KEY]&application_version=1"

Using the extension was the only way I could get JSON.  The Accept header seemed to be ignored.

prl

The Beyonwiz IceTV plugin uses JSON with "Accept: application/json", but it also supplies "Content-Type: application/json". It seems that the IceTV server demands the Content-Type even when it's not a POST query. I think that's wrong, but my HTTP is pretty rudimentary.

This works for me:
wget -O - --header="Accept: application/json" --header="Content-Type: application/json" "http://api.icetv.com.au/regions?api_key=[BeyonwizAppKey]&application_version=1"

If I change "json" to "xml" in the headers, I get XML instead of JSON. In fact all 4 possible combinations of "json" and "xml" in the headers work for that query. I assume if it was a POST query, you'd need the POST data to match the "Content-Type".
Peter
Beyonwiz T4 in-use
Beyonwiz T2, T3, T4, U4 & V2 for testing

DeltaMikeCharlie

I have managed to get some EPG data in XML format by using an extension on the URI.

I have noticed that the "id" field is fairly large and all of the samples that I have looked at so far are 32bit integers.

I was hoping to use this field as an equivalent to the DVB EIT event_id field so that when modifications come in, I can easily identify it with the existing Topfield TAP API, however, this is only 16 bits.  The "Event ID" field in the Topfield PIMP feed is also only 16 bits and was perfect for this purpose.

Internally, the Topfield timer records also carry this 16 bit code so that and indication can be shown in the EPG when a show is scheduled to be recorded.

I have experimented with reducing it mathematically but then I either end up with duplicates or having to keep track of the lowest id to subtract from the rest.  The only way I see to reliably reduce this number would be to implement a lookup table with 4,294,967,296 slots and allocating the next available 16 bit integer with a lot of housekeeping.

The DVB specifications state that this number only needs to be unique within a channel, however, this would still just help me by using one lookup table per channel.

Quoteevent_id: This 16-bit field contains the identification number of the described event (uniquely allocated within a service definition).

Is there any way to provide a 16 bit ID for the EPG events?  I also realise that this may need to be carried on to the timers node as well.

DeltaMikeCharlie

I have another query, this time about logging in.

I already have 2 PVRs registered with ICE and I'm trying to login using one of these.  Unfortunately, they don't seem to have a uid, so I can't logon because I get an error:

Quote<error error_code="13" error_msg="Device details are required for recording app" />

Seeing that I have to login to get my list of devices, I basically have to create a new device just to be able to login.

When I was accessing via PIMP, I could get a list of recorders and then use the recorder index/id to access the EPG/Timer data.

Q1. How do I login without specifying a device node so that I can get a list of my devices?
Q2. How do I login as an existing PVR that has not been allocated a uid?  I have tried using the id provided in my devices list (different to my PIMP device id) but I still get the error.

DeltaMikeCharlie

Quote from: DeltaMikeCharlie on March 17, 2016, 07:49:48 PMIs there an option for using http?
This is no longer necessary, I have managed to find a stand-alone cURL binary for the Topfield PVR architecture that supports https.