Guide API

From Livestream » User Guide

Jump to: navigation, search

The Livestream Guide API allows client applications to retrieve channels related Information in the form of XML. The client application can access the Guide API in a platform-independent, language-independent way. The Guide API is a web application running on Http Server supporting both Get and Post methods.

Contents


Audience


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


Prerequisites


Obtaining Affiliate Id and Key from Livestream

In order to query the Livestream API you need to obtain a Livestream API Affiliate ID and Application Key. Please request a key, visit your Account Center and click the API tab. Affiliate API Keys can configured by Livestream to filter a specific set of channels, or even to provide a private channel group.

Required Knowledge and skills

1. XML

2. Basic understanding of REST

3. Any programming language.

Retrieve Channels


Using the API, the client application can retrieve the list of channels. The list contains the information such as shortname, fullname, numberofviewers etc... The response is returned as an XML. The schema for the response can be obtained from http://channelguide.api.livestream/schema/channels.xsd

Parameter Allowed values Description Mandatory
method getChannels The name of the operation. In this case getChannels
affiliateId Affiliate Id provided by Livestream.
applicationKey Application key provided by Livestream.
channelType
  • LIVE
  • FEATURED
  • ALL

The type LIVE is used to retrieve the list chanels which are currently live.

The type FEATURED is used to retrieve the list of featured channels.

ALL can be used to retrieve the list of channels irrespective of the channel status

filters The API is designed to allow filters in order to filter out the channels based on the criteria specified. However, filter condition can only be specified on the set of allowed attributes.

The allowed attributes are

  • language
  • category
  • shortname
  • fullname
  • affiliate
  • isIphoneReady (true for iphone channels or else false)
  • isMobileReady (true for mobile compatible streaming channels or else false)
  • isFeaturedVOD (true for mobile compatible with on demand content or else false)

The filters expression is a string of attribute-value pair separated by the operators and/or. Parenthesis can be used in filter expression for modifying the normal order of operations.

The values in the expression have to be enclosed within the single quotes. The relational operators allowed in the filters expression are => < >= <= !=

The syntax of the attribute name-value pair is <<attribute-name>><<realtion-operator>><<attribute-value>>

e.g. The expression language=’english’or (category=’sports’ and affiliate=’2’)returns the list of channels as an XML

(i)Having English as the language or (ii) Belonging to the category ‘sports’ and belonging to affiliate 2

In the above expression, the sub expression category=’sports’ and affiliate=’2’ gets the highest precedence.

This parameter can be omitted if filters are not used

pageNumber Any Positive Integer value The API is designed to support paging. This parameter in combination with the parameter resultsPerPage can be used for paging.

The default value is 1

resultsPerPage Any Positive Integer value This parameter in combination with the parameter pageNumber is used for paging.

For example, if the pageNumber specified is 3 and the resultsPerPage is 20, the response XML will contain the channels from index 41 – 60.

The numberOfChannels attribute in the response XML indicates the total number of channels matching the given criteria.

The default value is 20.

orderBy
  • language
  • category
  • shortname
  • fullname
  • affiliate
  • currentviewers
orderBy parameter is used to order the list of channels in the specified order. Only the attributes specified in the allowed values column are valid.

Multiple ordering can be achieved by using multiple orderBy parameters.

If the parameter is not specified, then the default ordering is used.

orderType
  • ASC
  • DESC
orderType parameter is used to specify whether the list of channels should be returned in ascending order or in the descending order.

The default value is ASC

e.g. To retrieve the list of first 10 live channels which belong to the category ‘music ‘ and having ‘english’ as the language, ordered by shortname, one should form the http query expression like

GET

    
  http://channelguide.api.livestream.com/programguide?method=getChannels
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>> 
  &pageNumber=1&resultsPerPage=10&orderType=ASC&channelType=LIVE&orderBy=shortname 
  &filters=category='Music' and language='english'

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Livestream.

The response returned will be similar to the following XML snippet

       <response status="200">
         <channels totalNumberOfChannels="25">
	     <channel id="18589" shortName="0873tv" fullName="0873-Tv"
		category="Music"
		logoURL="http://mogulus-user-uploads.s3.amazonaws.com/45E56C15-BB53-
		5646-8312-CA1EE15F9D36.png"
		description="Il canale della musica e degli eventi di Vasto0873.Com"
		currentViewers="0" totalVM="275" vmThisMonth="35" vmThisWeek="10"
		vmToday="5" live="false" language="English"
		tags="musica, eventi, vasto, spettacoli" />
	     <channel id="21721" shortName="100pour100_rap" fullName="Soufiane"
		category="Music" logoURL="" description="Rap Marocain"
		currentViewers="0" totalVM="35" vmThisMonth="1" vmThisWeek="1"
		vmToday="0" live="false" language="English" tags="rap marocain tv" />
	     ..........
        </channels>
      </response>


The totalNumberOfChannels attribute in the above XML indicates that there are 25 channels matching the given filter criteria.

totalVM,vmThisMonth,vmThisWeek,vmToday indicates the total number of current viewers, current month’s total viewer minutes, current week’s total viewer minutes and current day’s total viewer minutes respectively .

Search Channels


Using the API, the client application can search channels based on the keyword specified. The keyword specified is matched against the shortname, description and tag attributes of a channel. The list contains the information such as shortname, fullname, numberofviewers etc... The response is returned as an XML. The schema for the response can be obtained from http://channelguide.api.livestream.com/schema/channels.xsd

Parameter Allowed values Description Mandatory
method search The name of the operation. In this case search
affiliateId Affiliate Id provided by Livestream.
applicationKey Application key provided by Livestream.
keywords Keywords to search. The keyword is matched against the shortname, description and tag attributes of a channel.
filters The API is designed to allow filters in order to filter out the channels based on the criteria specified. However, filter condition can only be specified on the set of allowed attributes.

The allowed attributes are

  • language
  • category
  • shortname
  • fullname
  • affiliate
  • islive (true/false)
  • isIphoneReady (true for iphone channels or else false)
  • isMobileReady (true for mobile compatible streaming channels or else false)
  • isFeaturedVOD (true for mobile compatible with on demand content or else false)


The filters expression is a string of attribute-value pair separated by the operators and/or. Parenthesis can be used in filter expression for modifying the normal order of operations.

The values in the expression have to be enclosed within the single quotes. The relational operators allowed in the filters expression are => < >= <= !=

The syntax of the attribute name-value pair is <<attribute-name>><<realtion-operator>><<attribute-value>>

e.g. The expression language=’english’or (category=’sports’ and affiliate=’2’)returns the list of channels as an XML

(i)Having English as the language or (ii) Belonging to the category ‘sports’ and belonging to affiliate 2

In the above expression, the sub expression category=’sports’ and affiliate=’2’ gets the highest precedence.

This parameter can be omitted if filters are not used

pageNumber Any Positive Integer value The API is designed to support paging. This parameter in combination with the parameter resultsPerPage can be used for paging.

The default value is 1

resultsPerPage Any Positive Integer value This parameter in combination with the parameter pageNumber is used for paging.

For example, if the pageNumber specified is 3 and the resultsPerPage is 20, the response XML will contain the channels from index 41 – 60.

The numberOfChannels attribute in the response XML indicates the total number of channels matching the given criteria.

The default value is 20.

orderBy
  • language
  • category
  • shortname
  • fullname
  • affiliate
  • currentviewers
orderBy parameter is used to order the list of channels in the specified order. Only the attributes specified in the allowed values column are valid.

Multiple ordering can be achieved by using multiple orderBy parameters.

If the parameter is not specified, then the default ordering is used.

orderType
  • ASC
  • DESC
orderType parameter is used to specify whether the list of channels should be returned in ascending order or in the descending order.

The default value is ASC

e.g. To retrieve the list of first 30 channels matching the keyword ‘groundreport ‘ordered by shortname, one should form the http query expression like

GET

    
  http://channelguide.api.livestream.com/programguide?method=search
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>    
  &pageNumber=1&resultsPerPage=30&orderType=ASC& orderBy=   
  shortname&keywords=groundreport

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Livestream.

The response returned will be similar to the following XML snippet

       <response status="200">
          <channels totalNumberOfChannels="25">
	     <channel id="157" shortName="groundreport"
		fullName="GroundReport TV" category="News and Politics"
		logoURL="http://mogulus-user-uploads.s3.amazonaws.com/5026E5B4-85F7-
                BCD1-EE26-26B34D628D11"
		description="GroundReport.com is a citizen journalism portal that helps 
		people tell their stories--and gives them a cut of website revenues."
		currentViewers="0" totalVM="312536" vmThisMonth="17395"
		vmThisWeek="997" vmToday="321" live="false" language="English"
		tags="citizen, journalism, media, sterne, rachel, lofgren, jordan,
	 	news, ny, participatory, grassroots" />
	     <channel id="6751" shortName="dancinggirlstv"
		fullName="Dancing Girls tv" category="Film and Animation" logoURL=""
		description="dancing girls tv" currentViewers="0" totalVM="7358"
		vmThisMonth="3953" vmThisWeek="1876" vmToday="449" live="false"
		language="English"
		tags="tv groundreport backstage bill cunt robingoodtv gomedia 
                frankhouse" />
	     ..........
          </channels>
      </response>


The totalNumberOfChannels attribute in the above XML indicates that there are 2 channels matching the given criteria.

totalVM,vmThisMonth,vmThisWeek,vmToday indicates the total number of current viewers, current month’s total viewer minutes, current week’s total viewer minutes and current day’s total viewer minutes respectively .

Retrieve Most Viewed Channels


Using the API, the client application can retrieve the most popular channels. The list contains the information such as shortname, fullname, numberofviewers etc... The response is returned as an XML. The schema for the response can be obtained from http://channelguide.api.livestream.com/schema/channels.xsd


Parameter Allowed values Description Mandatory
method getMostViewedChannels The name of the operation. In this case getMostViewedChannels
affiliateId Affiliate Id provided by Livestream.
applicationKey Application key provided by Livestream.
mostViewedChannelType
  • NOW
  • TODAY
  • CURRENT_WEEK
  • CURRENT_MONTH
  • ALL_TIME

If the mostViewedChannelType is NOW, then the channels currently viewed by more viewers are returned. Likewise the most viewed channels for the current day, current week , current month and all time can be retrieved by using the mostViewedChannelType TODAY, CURRENT_WEEK, CURRENT_MONTH and ALL_TIME respectively

filters The API is designed to allow filters in order to filter out the channels based on the criteria specified. However, filter condition can only be specified on the set of allowed attributes.

The allowed attributes are

  • language
  • category
  • shortname
  • fullname
  • affiliate
  • islive (true/false)
  • isIphoneReady (true for iphone channels or else false)
  • isMobileReady (true for mobile compatible streaming channels or else false)
  • isFeaturedVOD (true for mobile compatible with on demand content or else false)


The filters expression is a string of attribute-value pair separated by the operators and/or. Parenthesis can be used in filter expression for modifying the normal order of operations.

The values in the expression have to be enclosed within the single quotes. The relational operators allowed in the filters expression are => < >= <= !=

The syntax of the attribute name-value pair is <<attribute-name>><<realtion-operator>><<attribute-value>>

e.g The expression language=’english’or (category=’sports’ and affiliate=’2’)returns the list of channels as an XML

(i)Having English as the language or (ii) Belonging to the category ‘sports’ and belonging to affiliate 2

In the above expression, the sub expression category=’sports’ and affiliate=’2’ gets the highest precedence.

This parameter can be omitted if filters are not used

pageNumber Any Positive Integer value The API is designed to support paging. This parameter in combination with the parameter resultsPerPage can be used for paging.

The default value is 1

resultsPerPage Any Positive Integer value This parameter in combination with the parameter pageNumber is used for paging.

For example, if the pageNumber specified is 3 and the resultsPerPage is 20, the response XML will contain the channels from index 41 – 60.

The numberOfChannels attribute in the response XML indicates the total number of channels matching the given criteria.

The default value is 20.

e.g To retrieve the list of first 30 currently most viewed channels, one should form the Http Query expression like

GET

    
  http://channelguide.api.livestream.com/programguide?method=getMostViewedChannels
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>  
  &pageNumber=1&resultsPerPage=30&mostViewedChannelType=NOW 


Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Livestream.

The response returned will be similar to the following XML snippet

       <response status="200">
         <channels totalNumberOfChannels="25">
	      <channel id="16822" shortName="channelpartner_tv24"
		fullName="CP tv24 by ChannelPartner" category="Science and Tech"
		logoURL="http://mogulus-user-uploads.s3.amazonaws.com/B6988A7A-94A0-
		5FC1-1D7A-90D1715A773E.jpg"
		description="" currentViewers="164" totalVM="3239059" vmThisMonth="0"
		vmThisWeek="0" vmToday="0" live="false" language="German"
		tags="reseller händler it distribution deutsch german" />
	      <channel id="23059" shortName="cuoreintertv"
		fullName="Cuore Inter Tv" category="Sports and Hobbies"
		logoURL="http://mogulus-user-uploads.s3.amazonaws.com/C95DA6CD-5C54-
		F376-9797-69896C0F0653.jpg"
		description="Cuore Inter Tv, la prima net-tv che parla di F.C.Inter! in 
		collaborazione tra LuCalcio.com e CuoreInter.com"
		currentViewers="32" totalVM="37942" vmThisMonth="0" vmThisWeek="0"
		vmToday="0" live="false" language="Italian"
		tags=" " />
	      ..........              
        </channels>
      </response>


The totalNumberOfChannels attribute in the above XML indicates that there are currently 296 most viewed channels This value can be used in paging

totalVM,vmThisMonth,vmThisWeek,vmToday indicates the total number of current viewers, current month’s total viewer minutes, current week’s total viewer minutes and current day’s total viewer minutes respectively .

Retrieve Categories


Using the API, the client application can retrieve the categories. All the channels belong to one or other category. The list contains the information such name, description and total number of channels belonging to that category which meets the filter criteria. The response is returned as an XML. The schema for the response can be obtained from http://channelguide.api.livestream.com/schema/categories.xsd

Parameter Allowed values Description Mandatory
method getCategories The name of the operation. In this case getCategories
affiliateId Affiliate Id provided by Livestream.
applicationKey Application key provided by Livestream.
filters The API is designed to allow filters in order to filter out the channels based on the criteria specified. However, filter condition can only be specified on the set of allowed attributes.

The allowed attributes are

  • language
  • category
  • shortname
  • fullname
  • affiliate
  • isIphoneReady (true for iphone channels or else false)
  • isMobileReady (true for mobile compatible streaming channels or else false)
  • isFeaturedVOD (true for mobile compatible with on demand content or else false)


The filters expression is a string of attribute-value pair separated by the operators and/or. Parenthesis can be used in filter expression for modifying the normal order of operations.

The values in the expression have to be enclosed within the single quotes. The relational operators allowed in the filters expression are => < >= <= !=

The syntax of the attribute name-value pair is <<attribute-name>><<realtion-operator>><<attribute-value>>

e.g The expression language=’english’ Returns the list of categories along with the total number of channels belonging to each category.

This parameter can be omitted if filters are not used

e.g To retrieve the categories along with the total number of ‘english’ channels belonging to each category, one should form the Http Query expression like

GET

    
  http://channelguide.api.livestream.com/programguide?method=getCategories
  &affiliateId= <<your affiliate ID>>&applicationKey=<<Your application key>>
  &filters=language='english'

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Livestream.

The response returned will be similar to the following XML snippet

       <response status="200">
          <categories totalNumberOfCategories="24">
	     <category id="18" name="Art and Creativity"
		description="Art and creativity" totalNumberOfChannels="2352" />
	     <category id="1" name="Auto and Vehicles"
		description="Auto and Vehicles" totalNumberOfChannels="782" />
             ......
         </categories>
       </response>


The above response xml indicates that there are totally 24 categories. And the totalNumberOfChannels attribute in each category element indicates the number of english belonging to that category

Retrieve Languages


Using the API, the client application can retrieve the languages. All channels are associated with any one language. The response is returned as an XML. The schema for the response can be obtained from http://channelguide.api.livestream.com/schema/languages.xsd

Parameter Allowed values Description Mandatory
method getChannels The name of the operation. In this case getChannels
affiliateId Affiliate Id provided by Livestream.
applicationKey Application key provided by Livestream.

e.g To retrieve the list of languages, one should form the Http Query expression like

GET

    
  http://channelguide.api.livestream.com/programguide?method=getLanguages
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>> 

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Livestream.

The response returned will be similar to the following XML snippet

        <response status="200">
              <languages totalNumberOfLanguages="36">
	         <language id="2" iso="" name="Bengali" />
	         <language id="3" iso="" name="Burmese" />
	         <language id="4" iso="" name="Cantonese" /> 
                 ......
               </languages>
        </response>


The totalNumberOfLanguagesattribute in the above XML indicates that there are totally 36 channels

Retrieve Channels Count


Using the API, the client application can retrieve the total number of featured, live and all channels which meets the filter criteria The response is returned as an XML. The schema for the response can be obtained from http://channelguide.api.livestream.com/schema/channels_count.xsd

Parameter Allowed values Description Mandatory
method getChannels The name of the operation. In this case getChannels
affiliateId Affiliate Id provided by Livestream.
applicationKey Application key provided by Livestream.
filters The API is designed to allow filters in order to filter out the channels based on the criteria specified. However, filter condition can only be specified on the set of allowed attributes.

The allowed attributes are

  • language
  • category
  • shortname
  • fullname
  • affiliate
  • isIphoneReady (true for iphone channels or else false)
  • isMobileReady (true for mobile compatible streaming channels or else false)
  • isFeaturedVOD (true for mobile compatible with on demand content or else false)


The filters expression is a string of attribute-value pair separated by the operators and/or. Parenthesis can be used in filter expression for modifying the normal order of operations.

The values in the expression have to be enclosed within the single quotes. The relational operators allowed in the filters expression are => < >= <= !=

The syntax of the attribute name-value pair is <<attribute-name>><<realtion-operator>><<attribute-value>>

e.g The expression language=’english’ Returns the total number of channels having english as the language

This parameter can be omitted if filters are not used

e.g To retrieve the list of first 30 live channels which belong to the category ‘music ‘ and having ‘english’ as the language, ordered by shortname, one should form the http query expression like

GET

    
  http://channelguide.api.livestream.com/programguide?method=getTotalNumberOfChannels
  &affiliateId=<<your affiliate ID>>&applicationKey=<<Your application key>>  
  &filters=language='english'

Note: Replace <<your affiliate ID>> and <<Your application key>> by the affiliate id and application key provided by Livestream.

The response returned will be similar to the following XML snippet

       <response status="200">
	    <count all="27514" live="42" featured="13" />
        </response>
       

The above response XML indicates that there are totally 27514 English channels. Out of them 42 channels are live and 13 channels quoted as featured channels.


Retrieve Channels Using User/Password


Using the API, the client application can retrieve the total number of channels to which user is associated with either role OWNER or MEBBER.The response is returned as an XML.

Parameter Allowed values Description Mandatory
method getChannels The name of the operation. In this case getChannels
user User Name on Livestream.
password Password for the account on Livestream.

GET

    
http://channelguide.api.livestream.com/programguide?method=getChannels
&user=<your-user-name
&password=<your-password>
    

Response will be like following xml snippet.

   
<response status="200">
<channels totalNumberOfChannels="1">
<channel id="3513" shortName="mogulus" fullName="Mogulus" isOwner="true"
role="Owner" isPro="false"/>
</channels>
</response>
    

Update Channel Info


Using the API, the client application can update the information of channels for which user is authenticated and owner.

Parameter Allowed values Description Mandatory
method updateChannelInfo The name of the operation. In this case updateChannelInfo
user User Name on Livestream.
password Password for the account on Livestream.
channel channel name
configXml XML containing the channel data like user shortName,description, fullName etc. The XML format is explained below in example

This method supports both HTTP POST and GET. However it is better to use HTTP POST method for this operation simply because the length of the configXml could be large.

GET

   
http://channelguide.api.livestream.com/programguide?method=updateChannelInfo
&user=<your-user-name>&password=<your-password>&channel=<channel-name>
&configXml=<channel><full_name>changed-full-name</full_name>
<description>changed-description</description></channel>
    

Response will be like following xml snippet.

  
<response status="200"> Channel is successfully updated </response>
   

Response Codes


Code Message Description
200 OK Invoked operation is executed successfully.
400 Client Error Client error occurs when there are any parameters missing which are required for the requested operation.

Client error can also occur when the value specified for a parameter is invalid. It is important to make sure that the values specified for the parameters are valid according to the allowed values.

401 Unauthorized client error Response code 401 is returned when the given affiliateId or the Application key Is invalid.
500 Server Error Server error may occur when the moguls programguide server is temporarily down for maintenance.