TVkaista Client API

The current version is available at http://www.tvkaista.fi/feed/

A beta feed is available at http://www.tvkaista.fi/feedbeta/ with fixes for issue 2, issue 3 and issue 4. NOTE: The beta feed is not stable and may break at any time. Do not use it in production code.

Authorization

All requests require HTTP Basic Access Authentication using TVkaista client credentials.

Pre-Base64 encoding of credentials may be ISO-8859-1 or UTF-8.

General

Returned content types can currently only be requested by appending {feed type}.{content type} to an URI.

Currently supported combinations are:

• [mp4|flv|h264|ts].[rss|itunes]
• [standard|detailed].[mediarss|mrss]

Unsupported combinations may result in a 404 or fall back to basic RSS.

Feed type filters on video format for RSS and iTunes content types. The detailed Media RSS feed adds time stamped thumbnails to the feed. The 'mediarss', as opposed to 'mrss', content type is a legacy format providing backwards-compatible guids.

Collection editing tries to follow The Atom Publishing Protocol specification.

A 500 Internal Server Error status code may be returned for any request.

Item's pubDate and dc:date currently contains the program's air date.

Optional include_future_dates query parameter adds programs with future dates to a program feed.

Example output

flv.rss

<?xml version="1.0" standalone='yes'?> 
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
   <channel>
      <title>TVkaista Playlist</title>
      <link>http://www.tvkaista.fi</link>
      <description>RSS feed for your playlist</description>
      <language>fi-fi</language>
      <pubDate>Fri, 28 Jan 2011 10:55:45 +0000</pubDate>
      <lastBuildDate>Fri, 28 Jan 2011 10:55:45 +0000</lastBuildDate>
      <ttl>15</ttl>
      <atom:link rel="edit" href="http://www.tvkaista.fi/feedbeta/playlist/"/>
      <item>
         <title>Muumilaakson tarinoita</title>
         <description>Osa 87/101: Joulutarina. Jenni-t&#228;ti kutsuu muumiv&#228;en kyl&#228;ilem&#228;&#228;n. Matkaa taitetaan halki nietosten. Mutta ennen kuin Papan johtajajoukko enn&#228;tt&#228;&#228; perille, he saavat tehd&#228; tuttavuutta oudon olennon kanssa.</description>
         <pubDate>Fri, 28 Jan 2011 05:52:26 +0000</pubDate>
         <link>http://www.tvkaista.fi/search/?findid=9405998</link>
         <guid isPermaLink="true">http://www.tvkaista.fi/feedbeta/programs/9405998/</guid>
         <source url="http://www.tvkaista.fi/feedbeta/channels/1008/flv.rss">YLE TV2</source>
         <atom:link rel="edit" href="http://www.tvkaista.fi/feedbeta/playlist/9405998/"/>
         <enclosure url="http://www.tvkaista.fi/recordings/download/9405998.flv" length="187937262" type="video/x-flv"/></item>
   </channel> 
 </rss>

mp4.itunes

<?xml version="1.0" standalone='yes'?>
 <rss version="2.0" xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd" xmlns:atom="http://www.w3.org/2005/Atom">
   <channel>
      <itunes:author>TVkaista NetPVR</itunes:author>
      <itunes:owner>TVkaista NetPVR</itunes:owner>
      <itunes:summary>iTunes-compatible RSS feed for your playlist</itunes:summary>
      <itunes:image href="http://www.tvkaista.fi/iTunesLogo.png"/>
      <title>TVkaista Playlist</title>
      <link>http://www.tvkaista.fi</link>
      <description>iTunes-compatible RSS feed for your playlist</description>
      <language>fi-fi</language>
      <pubDate>Fri, 28 Jan 2011 10:56:16 +0000</pubDate>
      <lastBuildDate>Fri, 28 Jan 2011 10:56:16 +0000</lastBuildDate>
      <ttl>15</ttl>
      <atom:link rel="edit" href="http://www.tvkaista.fi/feedbeta/playlist/"/>
      <item>
         <itunes:author>YLE TV2</itunes:author>
         <itunes:duration>1695</itunes:duration>
         <itunes:summary>Osa 87/101: Joulutarina. Jenni-t&#228;ti kutsuu muumiv&#228;en kyl&#228;ilem&#228;&#228;n. Matkaa taitetaan halki nietosten. Mutta ennen kuin Papan johtajajoukko enn&#228;tt&#228;&#228; perille, he saavat tehd&#228; tuttavuutta oudon olennon kanssa.</itunes:summary>
         <title>Muumilaakson tarinoita</title>
         <description>Osa 87/101: Joulutarina. Jenni-t&#228;ti kutsuu muumiv&#228;en kyl&#228;ilem&#228;&#228;n. Matkaa taitetaan halki nietosten. Mutta ennen kuin Papan johtajajoukko enn&#228;tt&#228;&#228; perille, he saavat tehd&#228; tuttavuutta oudon olennon kanssa.</description>
         <pubDate>Fri, 28 Jan 2011 05:52:26 +0000</pubDate>
         <link>http://www.tvkaista.fi/search/?findid=9405998</link>
         <guid isPermaLink="true">http://www.tvkaista.fi/feedbeta/programs/9405998/</guid>
         <source url="http://www.tvkaista.fi/feedbeta/channels/1008/mp4.itunes">YLE TV2</source>
         <atom:link rel="edit" href="http://www.tvkaista.fi/feedbeta/playlist/9405998/"/>
         <enclosure url="http://www.tvkaista.fi/recordings/download/9405998.mp4" length="65850212" type="video/mp4"/></item>
   </channel>
 </rss>

detailed.mediarss

<?xml version="1.0" standalone='yes'?>
 <rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/" xmlns:atom="http://www.w3.org/2005/Atom">
   <channel>
      <title>TVkaista Playlist</title>
      <link>http://www.tvkaista.fi</link>
      <description>Media RSS feed for your playlist</description>
      <language>fi-fi</language>
      <pubDate>Fri, 28 Jan 2011 10:52:30 +0000</pubDate>
      <lastBuildDate>Fri, 28 Jan 2011 10:52:30 +0000</lastBuildDate>
      <ttl>15</ttl>
      <atom:link rel="edit" href="http://www.tvkaista.fi/feedbeta/playlist/"/>
      <item>
         <title>Muumilaakson tarinoita</title>
         <description>Osa 87/101: Joulutarina. Jenni-t&#228;ti kutsuu muumiv&#228;en kyl&#228;ilem&#228;&#228;n. Matkaa taitetaan halki nietosten. Mutta ennen kuin Papan johtajajoukko enn&#228;tt&#228;&#228; perille, he saavat tehd&#228; tuttavuutta oudon olennon kanssa.</description>
         <pubDate>Fri, 28 Jan 2011 05:52:26 +0000</pubDate>
         <link>http://www.tvkaista.fi/search/?findid=9405998</link>
         <guid isPermaLink="true">http://www.tvkaista.fi/feedbeta/programs/9405998/</guid>
         <source url="http://www.tvkaista.fi/feedbeta/channels/1008/detailed.mediarss">YLE TV2</source>
         <atom:link rel="edit" href="http://www.tvkaista.fi/feedbeta/playlist/9405998/"/>
         <media:group>
            <media:title type="plain">Muumilaakson tarinoita</media:title>
            <media:description type="plain">Osa 87/101: Joulutarina. Jenni-t&#228;ti kutsuu muumiv&#228;en kyl&#228;ilem&#228;&#228;n. Matkaa taitetaan halki nietosten. Mutta ennen kuin Papan johtajajoukko enn&#228;tt&#228;&#228; perille, he saavat tehd&#228; tuttavuutta oudon olennon kanssa.</media:description>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/thumbnail.jpg" width="96" height="72"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0002.png" width="160" height="120" time="00:00:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0003.png" width="160" height="120" time="00:01:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0004.png" width="160" height="120" time="00:02:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0005.png" width="160" height="120" time="00:03:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0006.png" width="160" height="120" time="00:04:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0007.png" width="160" height="120" time="00:05:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0008.png" width="160" height="120" time="00:06:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0009.png" width="160" height="120" time="00:07:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0010.png" width="160" height="120" time="00:08:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0011.png" width="160" height="120" time="00:09:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0012.png" width="160" height="120" time="00:10:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0013.png" width="160" height="120" time="00:11:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0014.png" width="160" height="120" time="00:12:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0015.png" width="160" height="120" time="00:13:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0016.png" width="160" height="120" time="00:14:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0017.png" width="160" height="120" time="00:15:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0018.png" width="160" height="120" time="00:16:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0019.png" width="160" height="120" time="00:17:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0020.png" width="160" height="120" time="00:18:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0021.png" width="160" height="120" time="00:19:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0022.png" width="160" height="120" time="00:20:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0023.png" width="160" height="120" time="00:21:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0024.png" width="160" height="120" time="00:22:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0025.png" width="160" height="120" time="00:23:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0026.png" width="160" height="120" time="00:24:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0027.png" width="160" height="120" time="00:25:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0028.png" width="160" height="120" time="00:26:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0029.png" width="160" height="120" time="00:27:00.000"/>
            <media:thumbnail url="http://www.tvkaista.fi/feedbeta/programs/9405998/metadata/thumbs/thumb-0030.png" width="160" height="120" time="00:28:00.000"/>
            <media:player url="http://www.tvkaista.fi/Embed?id=9405998"/>
            <media:content url="http://www.tvkaista.fi/recordings/download/9405998.ts" medium="video" type="video/mp2t" fileSize="956464852" bitrate="8000" duration="1695"/>
            <media:content url="http://www.tvkaista.fi/recordings/download/9405998.mp4" medium="video" type="video/mp4" fileSize="65850212" bitrate="300" duration="1695"/>
            <media:content url="http://www.tvkaista.fi/recordings/download/9405998.flv" medium="video" type="video/x-flv" fileSize="187937262" bitrate="1000" duration="1695"/>
            <media:content url="http://www.tvkaista.fi/recordings/download/9405998.h264" medium="video" type="video/mp4" fileSize="381162519" bitrate="2000" duration="1695"/></media:group>
      </item>
   </channel> 
 </rss>

Resources

/programs/{program}/

• GET(mediarss):
• 200 Specified program
• 404 Unknown program

/programs/{program}/suggestions/

• GET(rss|itunes|mediarss):
• 200 List of programs similar to specified program
• 404 Unknown program

/programs/{program}/thumbnail

• GET(image/*):
• 200 binary image data
• 404 Unknown program

/programs/{program}/metadata/{remainder}

• GET:
• 302 Redirect to a server hosting the metadata ^{Note: 60s load-balance cache}
• 404 Unknown program

/channels/

• GET(rss):
• 200 List of TV channels the authenticated client has subscribed to

/channels/{channel}/

• GET(rss|itunes|mediarss):
• 200 List of programs on specified TV channel ^{Soft contract: List will only include programs dating back to 05:00 yesterday. Note: Archived programs linked through [http://tools.ietf.org/html/rfc5005 Archived Feeds]}
• 404 Unknown channel

/archives/{year}/{month}/{day}/channels/{channel}/

• GET(rss|itunes|mediarss):
• 200 List of programs on the specified TV channel for the specified date ^{Soft contract: List will only include programs dating between 00:00 and 23:59 of the specified date}
• 404 Not archived yet for future and current dates
• 403 Forbidden for dates outside client's program retention period

/seasonpasses/

• GET(rss):
• 200 List of client's season passes
• POST(form), single parameter 'id'
• 201 Season pass created from program matching id ^{Note: Season pass guid URI in Location header}
• 400 id is not a valid program guid URI or integer identifier

/seasonpasses/{seasonpass}/

• GET(rss|itunes|mediarss):
• 200 List of programs in season pass
• 404 No such seasonpass for unknown or unauthorized season passes
• DELETE:
• 200 Season pass removed
• 404 Unknown or unauthorized season pass

/seasonpasses/*/

• GET(rss|itunes|mediarss):
• 200 Aggregated list of programs in client's season passes

/playlist/

• GET(rss):
• 200 List of programs in client's playlist
• POST(form), single parameter 'id'
• 201 Playlist entry created from program matching id ^{Note: Playlist entry guid URI in Location header}
• 400 id is not a valid program guid URI or integer identifier

/playlist/{program}/

• GET:
• 302 Redirect to program's guid URI
• DELETE:
• 200 Entry for program removed from playlist
• 404 Unknown program or no such entry

/search/{field}/{keywords}

• GET(rss|itunes|mediarss):
• 200 List of programs matching keywords search of title or description field ^{Note: Keywords are urldecoded as UTF-8}
• 404 Field is not 'title' or 'description'