Channel API 2.0

From Livestream » User Guide

(Redirected from Channel API)
Jump to: navigation, search

The Channel API allows you to retrieve all channel related information, such as number of viewers, list of clips, playlists and/or thumbnails, in the form of media rss syndication feeds.

Click here to see an example of how you can use the channel API in conjunction with the player API in order to build your own player.

Contents

What has changed in version 2.0?

The version 2.0 of channel API has been developed to provide a highly scalable and real-time API.

The version 2.0 supports json output for responses with callback option.

The following actions are currently not implemented in version 2.0:

(i) searchclips - searching the ondemand clips using keyword.

(ii) channelsinfo - retrieving multiple channels Information.

(iii) channelslivestatus - retrieving multiple channels live status.

(iv) embed - retrieving the channel embed tags.

If you need these features, please see this page.


We strongly recommend our channel API version 1.0 users to upgrade to version 2.0 to get the features described below. We will continue to support version 1.0 of the API until 2010/08.

Recent changes


- 2010/08/13: Support for JSON has been added to all the API methods. You can get the output in the JSON format by appending the method name with ".json", and optionally specifying a "callback=[your-javascript-callback-method]" parameter for JSONP.



Audience


This document is intended for programmers who want to write client applications that can access the Channel API. The document provides examples of the supported operations using raw HTTP and XML, along with explanations.




Prerequisites


In order to query the Livestream API you need to have a livestream channel. To create a channel please refer Account API or visit www.livestream.com [1]

Required knowledge:

1. Basic understanding of REST ([2]).

2. Forming the request URL as described below.

3. Understanding the request throttling limits as described below.

4. Any programming language.



Forming Your Request


The API calls are invoked by using the escaped channel "short name" in the DNS name.

Here are the steps to form your request:

  1. Add the character 'x' at the beginning and at the end of the channel name.
  2. Replace all underscore ("_") characters (if any) in the channel name by a hyphen ("-")
  3. Append .api.channel.livestream.com/2.0 to the above formed string.

Examples:

For the channel "my_channel", The escaped url is http://xmy-channelx.api.channel.livestream.com/2.0

For the channel "proshowcase", The escaped url is http://xproshowcasex.api.channel.livestream.com/2.0

Response Format


All API methods support either XML or JSON as the response format. To choose between them, append the method name with ".xml" or ".json". If no format is speficied, the API defaults to XML output.

If requesting a JSON output, you can optionally specify a "callback=[your-javascript-callback-method]" parameter for JSONP output.



Rate Limiting/Request Throttling


API users are currently rate-limited as follows:

  • 10 requests per second.
  • 100 requests per minute.
  • 1000 requests per hour.
  • 10000 requests per day.

The "X-Ratelimit" headers in the API responses will give you an indication of your current limit.

If you think you need higher limits, please contact us at info@livestream.com.

List Playlists


To obtain the list of playlists belonging to a channel send an HTTP GET request to

[escaped url]/listplaylists.[xml|json] .

Example: To retrieve the list of video-on-demand playlists belonging to the channel proshowcase

GET

    
 http://xproshowcasex.api.channel.livestream.com/2.0/listplaylists.xml

The response returned will be similar to the following RSS xml.

<rss xmlns:media="http://search.yahoo.com/mrss" xmlns:ls="http://api.channel.livestream.com/2.0"
	version="2.0">
	<channel>
		<title>Mogulus Pro Showcase</title>
		<link>http://www.livestream.com/proshowcase</link>
		<description />
		<image>
			<url />
		</image>
		<language>English</language>
		<category>Entertainment</category>
		<pubDate>Fri, 17 Oct 2008 00:59:38 GMT</pubDate>
		<ls:totalClips>1</ls:totalClips>
		<ls:directory id="9205475006471204305" title="_root"
			hasClips="true">
			<ls:directory id="6845317970224595470" hasClips="true"
				title="High - 700 Kbps (Pro) Samples" />
			<ls:directory id="4056950833275962776" hasClips="true"
				title="HD - 1,700 Kbps (Pro) Samples" />
		</ls:directory>
	</channel>

Each directory element in the above xml represents a playlist. The id attributes of these elements represents the unique id of the playlist, which can be used to list the clips within the playlist. The xml is organized in such a way to represent the exact directory structure of the playlists. For e.g., In the above example the root playlist (directory) has two sub playlists within it. The attribute hasClips indicates whether a playlist contains clips within it or not. All the directory elements belongs to livestream namespace having URI http://api.channel.livestream.com/2.0 with the prefix ls.

The above response can also be retrieved as json output

GET

    
 http://xproshowcasex.api.channel.livestream.com/2.0/listplaylists.json

By passing the callback request parameter, the json response can be wrapped in parentheses and a function name of your choosing

For eg:

GET

    
 http://xproshowcasex.api.channel.livestream.com/2.0/listplaylists.json?callback=listplaylists

List Clips


To obtain the list of clips belonging to a playlist of a channel send an HTTP GET request to

[escaped url]/listclips.[xml|json] with the following HTTP parameter(s).

HTTP parameters

1. id - the playlist id. The playlist id can be obtained from List Playlists. (The value of the element guid in the List Playlist response).

2. page - (optional) used with maxresults to obtain the required results. The default value is 1.

3. maxresults - (optional) the maximum number of results to be in one page. The default value is 10.

e.g. To retrieve the list of clips belonging to channel proshowcase in the playlist with id 6845317970224595470

GET

    
 http://xproshowcasex.api.channel.livestream.com/2.0/listclips.xml?id=6845317970224595470

The response returned will be similar to the following media RSS xml.

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:media="http://search.yahoo.com/mrss" xmlns:ls="http://api.channel.livestream.com/2.0"
	version="2.0">
	<channel>
		<title>Mogulus Pro Showcase</title>
		<link>http://www.livestream.com/proshowcase</link>
		<description />
		<image>
			<url />
		</image>
		<language>English</language>
		<category>Entertainment</category>
		<pubDate>Fri, 17 Oct 2008 00:59:38 GMT</pubDate>
		<ls:totalClips>3</ls:totalClips>
		<item>
			<title>Quantum of Solace Trailer (700Kbps)</title>
			<description />
			<link>http://www.livestream.com/proshowcase/ondemand/flv_7e12afb2-fae2-49e7-
                              aef2-269febafbf10</link>
			<guid>flv_7e12afb2-fae2-49e7-aef2-269febafbf10</guid>
			<ls:workflowStatus>Complete</ls:workflowStatus>
			<ls:isRecorded>false</ls:isRecorded>
			<media:thumbnail
				url="http://thumbnail.api.livestream.com/clipthumbnail/chproshowcase
                                     /2008/11/26/7e12afb2-fae2-49e7-aef2-269febafbf10_10.jpg" />
			<media:content duration="147.4" type="video/x-flv"
				url="http://www.livestream.com/proshowcase/ondemand/flv_7e12afb2-
                                     fae2-49e7-aef2-269febafbf10" />
			<pubDate>Wed, 26 Nov 2008 16:53:43 GMT</pubDate>
		</item>
		<item>
			<title>Iron Man Trailer (700Kbps)</title>
			<description />
			<link>http://www.livestream.com/proshowcase/ondemand/flv_4ed433b2-0689-460e-
                              9726-027c6a8b6f31</link>
			<guid>flv_4ed433b2-0689-460e-9726-027c6a8b6f31</guid>
			<ls:workflowStatus>Complete</ls:workflowStatus>
			<ls:isRecorded>false</ls:isRecorded>
			<media:thumbnail
				url="http://thumbnail.api.livestream.com/clipthumbnail/chproshowcase
                                     /2008/10/16/4ed433b2-0689-460e-9726-027c6a8b6f31_10.jpg" />
			<media:content duration="149.5" type="video/x-flv"
				url="http://www.livestream.com/proshowcase/ondemand
                                     /flv_4ed433b2-0689-460e-9726-027c6a8b6f31" />
			<pubDate>Fri, 17 Oct 2008 01:05:09 GMT</pubDate>
		</item>
		<item>
			<title>The Kite Runner Trailer (700Kbps)</title>
			<description />
			<link>http://www.livestream.com/proshowcase/ondemand/flv_fee7795c-362b-434c-
                              87b8-fd68a32a1ddd</link>
			<guid>flv_fee7795c-362b-434c-87b8-fd68a32a1ddd</guid>
			<ls:workflowStatus>Complete</ls:workflowStatus>
			<ls:isRecorded>false</ls:isRecorded>
			<media:thumbnail
				url="http://thumbnail.api.livestream.com/clipthumbnail/chproshowcase
                                     /2008/11/19/fee7795c-362b-434c-87b8-fd68a32a1ddd_10.jpg" />
			<media:content duration="114.4" type="video/x-flv"
				url="http://www.livestream.com/proshowcase/ondemand/flv_fee7795c-
                                     362b-434c-87b8-fd68a32a1ddd" />
			<pubDate>Wed, 19 Nov 2008 23:00:27 GMT</pubDate>
		</item>
	</channel>
</rss>

Where each item element in the above rss feed represents a clip. The guid element within the item element contains the unique identifier value of the clip. If the thumbnail is not available for the clip then the element media:thumbnail will not be present.

The totalClips element is used to show the total number of clips belonging to the playlist.

The above response can also be retrieved as json output

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/listclips.json?id=6845317970224595470

By passing the callback request parameter, the json response can be wrapped in parentheses and a function name of your choosing

For eg:

GET

    
http://xproshowcasex.api.channel.livestream.com
            /2.0/listclips.json?id=6845317970224595470&callback=listplaylists

Latest Clips


To obtain the list of clips belonging to a playlist of a channel in the descending order of the date created of the clip (latest first), Send an HTTP GET request to [escaped url]/latestclips.[xml|json] with the following HTTP parameter(s).

HTTP parameters

1. page - (optional) used with maxresults to obtain the required results. The default value is 1.

2. maxresults - (optional) then number of results to be in one page. The default value is 10.

For example, If the page is 1 and maxresults in 2, The first 2 latest clips are returned. To get the second set of 2 clips, set page to 2.

e.g. To retrieve the latest clips for channel proshowcase

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/latestclips.xml?page=2&maxresults=2

The response returned will be similar to the following media RSS xml.

<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:media="http://search.yahoo.com/mrss" xmlns:ls="http://api.channel.livestream.com/2.0"
	version="2.0">
	<channel>
		<title>Mogulus Pro Showcase</title>
		<link>http://www.livestream.com/proshowcase</link>
		<description />
		<image>
			<url />
		</image>
		<language>English</language>
		<category>Entertainment</category>
		<pubDate>Fri, 17 Oct 2008 00:59:38 GMT</pubDate>
		<ls:totalClips>6</ls:totalClips>
		<item>
			<title>The Kite Runner Trailer (700Kbps)</title>
			<description />
			<link>http://www.livestream.com/proshowcase/ondemand/flv_fee7795c-362b-434c-
                              87b8-fd68a32a1ddd</link>
			<guid>flv_fee7795c-362b-434c-87b8-fd68a32a1ddd</guid>
			<ls:workflowStatus>Complete</ls:workflowStatus>
			<ls:isRecorded>false</ls:isRecorded>
			<media:thumbnail
				url="http://thumbnail.api.livestream.com/clipthumbnail/chproshowcase
                                     /2008/11/19/fee7795c-362b-434c-87b8-fd68a32a1ddd_10.jpg" />
			<media:content duration="114.4" type="video/x-flv"
				url="http://www.livestream.com/proshowcase/ondemand/flv_fee7795c-
                                     362b-434c-87b8-fd68a32a1ddd" />
			<pubDate>Wed, 19 Nov 2008 23:00:27 GMT</pubDate>
		</item>
		<item>
			<title>Iron Man Trailer (1,700Kbps)</title>
			<description />
			<link>http://www.livestream.com/proshowcase/ondemand
                              /flv_3271446087426817161</link>
			<guid>flv_3271446087426817161</guid>
			<ls:workflowStatus>Complete</ls:workflowStatus>
			<ls:isRecorded>false</ls:isRecorded>
			<media:thumbnail
				url="http://thumbnail.api.livestream.com/clipthumbnail/chproshowcase
                                     /2008/10/17/8591abac-bd89-47fd-bb23-4473816eb0b9_10.jpg" />
			<media:content duration="149.5" type="video/x-flv"
				url="http://www.livestream.com/proshowcase/ondemand
                                     /flv_3271446087426817161" />
			<pubDate>Fri, 17 Oct 2008 16:32:20 GMT</pubDate>
		</item>
	</channel>
</rss>

The above response can also be retrieved as json output

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/latestclips.json?page=2&maxresults=2

By passing the callback request parameter, the json response can be wrapped in parentheses and a function name of your choosing

For eg:

GET

    
http://xproshowcasex.api.channel.livestream.com
               /2.0/latestclips.json?page=2&maxresults=2&callback=latestclips

Where each item element in the above rss feed represents a clip. The guid element within the item element contains the unique identifier value of the clip. If the thumbnail is not available for the clip then the element media:thumbnail will not be present.

Clip Details


To obtain the details of a clip, Send an HTTP GET request to [escaped url]/clipdetails.[xml|json]

HTTP parameters

1. id - the clip id. This can be obtained from any of List Clips, Latest Clips(The value of the element guid in the response).

e.g. To retrieve the details of the clip with id pla_1145907244544877845 belonging to the channel proshowcase

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/clipdetails.xml?id=pla_1145907244544877845

The response returned will be similar to the following media RSS feed

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:media="http://search.yahoo.com/mrss" xmlns:ls="http://api.channel.livestream.com/2.0"
	version="2.0">
	<channel>
		<title>Mogulus Pro Showcase</title>
		<link>http://www.livestream.com/proshowcase</link>
		<description />
		<image>
			<url />
		</image>
		<language>English</language>
		<category>Entertainment</category>
		<pubDate>Fri, 17 Oct 2008 00:59:38 GMT</pubDate>
		<item>
			<title>Live Show [mogulus] Mon Nov 24 2008 04:09:48 PM</title>
			<description />
			<link>http://www.livestream.com/proshowcase/ondemand
                              /pla_1145907244544877845</link>
			<guid>pla_1145907244544877845</guid>
			<ls:workflowStatus>Complete</ls:workflowStatus>
			<ls:isRecorded>true</ls:isRecorded>
			<media:thumbnail
				url="http://thumbnail.api.livestream.com/clipthumbnail/chproshowcase
                                     /2008/11/24/4bbf53dc-9aec-4ebe-ab41-1da397363e34_10.jpg" />
			<media:content duration="1987.279" type="video/x-flv"
				url="http://www.livestream.com/proshowcase/ondemand
                                     /pla_1145907244544877845" />
			<pubDate>Fri, 17 Oct 2008 00:59:38 GMT</pubDate>
		</item>
		<ls:totalClips>1</ls:totalClips>
	</channel>
</rss>

The above response can also be retrieved as json output

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/clipdetails.json?id=pla_1145907244544877845

By passing the callback request parameter, the json response can be wrapped in parentheses and a function name of your choosing

For eg: GET

    
http://xproshowcasex.api.channel.livestream.com
        /2.0/clipdetails.json?id=pla_1145907244544877845&callback=clipdetails

Channel Information


To obtain the meta data of a channel, Send an HTTP GET request to [escaped url]/info.[xml|json]

e.g. To retrieve the meta data of the channel proshowcase

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/info.xml

The response returned will be similar to the following xml

<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:ls="http://api.channel.livestream.com/2.0" version="2.0">
	<channel>
		<title>Mogulus Pro Showcase</title>
		<link>http://www.livestream.com/proshowcase</link>
		<description />
		<image>
			<url />
		</image>
		<language>English</language>
		<category>Entertainment</category>
		<pubDate>Fri, 17 Oct 2008 00:59:38 GMT</pubDate>
		<ls:isPremium>true</ls:isPremium>
		<ls:isLive>false</ls:isLive>
		<ls:shortName>proshowcase</ls:shortName>
		<ls:currentViewerCount>0</ls:currentViewerCount>
		<ls:viewerMinutesToday>64</ls:viewerMinutesToday>
		<ls:viewerMinutesThisWeek>84</ls:viewerMinutesThisWeek>
		<ls:viewerMinutesThisMonth>1533</ls:viewerMinutesThisMonth>
		<ls:totalViewerMinutes>330445</ls:totalViewerMinutes>
		<ls:totalLibraryClips>6</ls:totalLibraryClips>
		<ls:totalLibraryRecordings>0</ls:totalLibraryRecordings>
		<ls:tags />
		<ls:profile></ls:profile>
		<ls:links />
		<ls:bannerUrl>http://www.livestream.com/filestore/user-uploads/823F848F-76A3-B2AC-
                              1D21-5F0503F3EC3A.png</ls:bannerUrl>
	</channel>
</rss>


The above response can also be retrieved as json output

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/info.json

By passing the callback request parameter, the json response can be wrapped in parentheses and a function name of your choosing

For eg: GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/info.json?callback=info

shortName specifies the channel name.

title specifies the channel full name.

description specifies the channel description.

dateCreated specifies the channel creation date.

language the channel language.

category the channel category.

isPremium specifies whether the channel is premium or not.

isLive specifies whether the channel is live or not.

currentViewerCount specifies the current viewers for the channel.

viewerMinutesToday specifies the viewer minutes in last 24 hours.

viewerMinutesThisWeek specifies the viewer minutes in last 7 days.

viewerMinutesThisMonth specifies the viewer minutes in last 30 days.

totalViewerMinutes specifies the all time viewer minutes.

totalLibraryClips specifies the number of ondemand clips.

totalLibraryRecordings specifies the number of recorded ondemand clips.

Channel Live Status


To know whether a channel is live or not, Send an HTTP GET request to [escaped url]/livestatus.[xml|json]


e.g. To retrieve the live status for channel proshowcase

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/livestatus.xml

The response returned will be similar to the following xml

<?xml version="1.0" encoding="UTF-8"?>
<channel xmlns:ls="http://api.channel.livestream.com/2.0">
	<ls:isLive>false</ls:isLive>
	<ls:currentViewerCount>10</ls:currentViewerCount>
</channel>

The above response can also be retrieved as json output

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/livestatus.json

By passing the callback request parameter, the json response can be wrapped in parentheses and a function name of your choosing

For eg: GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/livestatus.json?callback=livestatus

isLive specifies whether a channel is live or not.

currentViewerCount specifies the current viewers for the channel

Thumbnail


To obtain the thumbnail uri of a clip, Send an HTTP GET request to [escaped url]/thumbnail.[xml|json]

HTTP parameters

1. id - the clip id. This can be obtained from any of List Clips, Latest Clips, Search Clips(The value of the element guid in the response).

3. time - the optional parameter specifying the duration of the video in seconds for which the thumbnail uri is requested. Default value is 10.

e.g. To retrieve the thumbnail uri of clip with id pla_1145907244544877845 belonging to the channel proshowcase for the 20th second

GET

    
http://xproshowcasex.api.channel.livestream.com
                        /2.0/thumbnail.xml?id=pla_1145907244544877845&time=20

The response returned will be similar to the following simple xml

<?xml version="1.0" encoding="UTF-8"?>
<media:thumbnail xmlns:media="http://search.yahoo.com/mrss"
	url="http://thumbnail.api.livestream.com/clipthumbnail/chproshowcase/2008/11/24/4bbf53dc-
             9aec-4ebe-ab41-1da397363e34_20.jpg" />

The above response can also be retrieved as json output

GET

    
http://xproshowcasex.api.channel.livestream.com
                       /2.0/thumbnail.json?id=pla_1145907244544877845&time=20

By passing the callback request parameter, the json response can be wrapped in parentheses and a function name of your choosing

For eg: GET

    
http://xproshowcasex.api.channel.livestream.com
    /2.0/thumbnail.json?id=pla_1145907244544877845&time=20&callback=thumbnail

where text value of the url element is the url location of the thumbnail.

Upcoming Events


To obtain the upcoming events for a channel, Send an HTTP GET request to [escaped url]/events.[xml|json]

e.g. To retrieve the upcoming events for the channel proshowcase

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/events.xml

The response returned will be similar to the following simple xml

<?xml version="1.0" encoding="UTF-8"?>
<ls:events xmlns:ls="http://api.channel.livestream.com/2.0">
	<ls:event title="showcase" startDate="2009-10-27 11:25:00.0"
		endDate="2009-10-27 11:43:00.0" />
	<ls:event title="organize" startDate="2009-10-28 11:20:00.0"
		endDate="2009-10-28 11:53:00.0" />
</ls:events>

The above response can also be retrieved as json output

GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/events.json

By passing the callback request parameter, the json response can be wrapped in parentheses and a function name of your choosing

For eg: GET

    
http://xproshowcasex.api.channel.livestream.com/2.0/events.json?callback=events

The events are ordered by their start dates.

Response Codes


The above services in case of invalid requests/ server error will return the appropriate http response codes.

The possible error codes are

400

     Bad Request. The request is not understood by the server due to invalid  
     action or invalid parameters.

404

     Not Found. The requested resource (clip, channel, playlist, thumbnail) is not found.

500

     Internal Server Error. The server encountered an unexpected condition which
     prevented it from fulfilling the request.

Using the Player API


You can find an example of how to use the channel API with the player API here.