• logo
  • API

Server API for Video Genome

TOC

Overview
Response Formats
Authentication
Friends
Invitation
Channels
Videos
Comments
Video Attributes And Values
Integration Parameters

Overview

Video Genome provides a set of RESTful APIs. Meaning that the API request is a HTTP GET request to the server and the reply is a chunk of XML that is included in the body of HTTP response. There are two uses of the API. One is native using the embeddable player. In that case, VG can track some information in the session. There is also an external integration method.

Session information will not be sufficient for integration implementers. Instead, the APIs support some additional parameters that identify an integration development environment and any hosted user sessions through that environment. All non-native methods of accessing the API must call each of the APIs listed below with an additional set of parameters. For those developers interest in the non-native integration, see Integration Parameters below.

Response Formats

Successful Response

<rsp stat="ok" version="1.0">
	... response body ...
</rsp>

Error

All the APIs use a common error response below. This will not have further examples in the API documentation

<rsp stat="fail" version="1.0">
    <error>

        <code>101</code>
        <message>message</message>
        <data> <!-- optional -->
            <key>value</key> <!-- unknown number of key values pairs -->

        </data>
    </error>
</rsp>

Error Codes

CodeDescriptionExtra Datanotes
-10Saving failedyes
-11Development only APIno
-200User not logged inno
-204Invalid User IDno
-208Invalid User Credentialsno
-300Invalid integration callnoMost likely the call was missing either the dev ID or signature parameters
-304Invalid signatureyes
-305Invalid User Session Keyno
-704Invalid video IDno
-800Facebook Erroryes: http://wiki.developers.facebook.com/index.php/Feed.publishUserAction#Error_Codes
-904Invalid Channelno

Authentication

/api/login

development only - not in production



Friends

Friend Object

<friend>
  <id>18eye-zpSX_</id>

  <username>username</username>
  <email>some@yahoo.com</email>
  <picurl>http://www.videogenome.com/avatar/2.png</picurl>
</friend>

/api/getFriends

Valid User Session Required




Returns a list of friends that are associated with the current user id.

Example

http://www.videogenome.net/api/getFriends
<rsp stat="ok" version="1.0"> 
	<friends>
		<friend>
			<id>18eye-zpSX_</id>

			<username>username</username>
			<email>some@yahoo.com</email>
			<picurl>http://www.videogenome.com/avatar/2.png</picurl>
		</friend>

	</friends>
</rsp>

Invitation

/api/sendInvite

Valid User Session Required




Generates and sends an invitation email to the email address provided.


Example

http://www.videogenome.net/api/sendInvite?vid=56&email=email%40yahoo.com,&extents=0%2C261000

<rsp stat="ok" version="1.0"> 
</rsp>

Channels

Predefined Channel Ids

channel object

<channel title="Onion News" id='87568'> 
	<thumbnail>URL</thumbnail>
        <attributes> 
		<attributtype id='8' name='Emotion'> 
			<attribute id='8736' name='Happy' weight='7863'/> 
		</attributtype> 
		<attributtype id='6' name='Genre'> 
			<attribute id='567' name='SciFi??' weight='82735'/> 
			<attribute id='19867' name='Horror' weight='87625'/> 
		</attributtype> 
	</attributes> 

</channel>

/api/getChannels

Returns a paginated list of channels that match the given criteria.
NOTE: If a user is authenticated, the resulting list will include items that a non-authenticated user will not get which is the following: private channels that the authenticated user is the owner of


NOTE: channelIDlist and categoryKey parameters are mutually exclusive. If neither categoryKey nor channelIDlist criteria is provided then this call returns ALL of the channels (private channels are returned based on whether the user is authenticate. See a note above on making this call while authenticated)

Example

http://www.videogenome.net/api/getChannels?channelIDlist= 87568, 76452, 87568, 76452&page=1&pagesize=4

<rsp stat="ok" version="1.0"> 
	<channels page='1' pagesize="4" total='4' > 
		<channel title="Onion News" id='87568'> 
			<thumbnail>URL</thumbnail> 
		</channel> 
		<channel title="NASCAR Crashes" id='76452'> 
			<thumbnail>URL</thumbnail> 
		</channel> 
		<channel title="Onion News" id='87568'> 
			<thumbnail>URL</thumbnail> 
		</channel> 
		<channel title="NASCAR Crashes" id='76452'> 
			<thumbnail>URL</thumbnail> 
		</channel>

	</channels>
</rsp> 

/api/saveChannel

Valid User Session Required




Creates new/updates an existing channel. Returns a created/updated channel entry upon successful completion
NOTE: This API call is provided through XML over HTTP POST

* if chanel id is specified then the server performs an update on the existing channel otherwise a new channel is created

Example

POST /api/saveChannel  HTTP/1.0

<channel title="Onion News"> 
	<attributes> 
		<attributtype id='8' name='Emotion'> 
			<attribute id='8736' name='Happy' weight='7863'/> 
		</attributtype> 
		<attributtype id='6' name='Genre'> 
			<attribute id='567' name='SciFi??' weight='82735'/> 
			<attribute id='19867' name='Horror' weight='87625'/> 
		</attributtype> 
	</attributes>

</channel>
<rsp stat="ok" version="1.0">
	<channel title="Onion News" id="1234"> 
		<attributes> 
			<attributtype id='8' name='Emotion'> 
				<attribute id='8736' name='Happy' weight='7863'/> 
			</attributtype> 
			<attributtype id='6' name='Genre'> 
				<attribute id='567' name='SciFi??' weight='82735'/> 
				<attribute id='19867' name='Horror' weight='87625'/> 
			</attributtype> 
		</attributes>

	</channel>
</rsp>

Videos

Video object

<video>
	<id>595</id>

	<title>dream team tay lover and lil bro</title>
	<thumbnail><![CDATA[http://www.videogenome.net/thumbs/595.png]]></thumbnail>
	<vid_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></vid_url>
	<duration>172</duration>

	<page_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></page_url>
	<ownerid>108</ownerid>
	<ownername><![CDATA[JohnDoe]]></ownername>
	<ownerpic><![CDATA[http://10.33.176.90/userphotos/default.jpg]]></ownerpic>

	<type>static</type>
</video>

/api/getVideos

Gets information on a single video id of which is provided

Example

http://www.videogenome.net/api/getVideos?vid=12345
<rsp stat="ok" version="1.0">
  <videos page='1' pagesize="50" total='101' >
    <video>
      <id>595</id>
      <title>dream team tay lover and lil bro</title>

      <thumbnail><![CDATA[http://www.videogenome.net/thumbs/595.png]]></thumbnail>
      <vid_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></vid_url>
      <videoStartTimestamp>0</videoStartTimestamp>
      <duration>172</duration>

      <page_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></page_url>
      <ownerid>18eye-zpSX_</ownerid>
      <ownername><![CDATA[RESERVED]]></ownername>
      <ownerpic><![CDATA[RESERVED]]></ownerpic>

      <requesterid></requesterid>
      <type>1</type>
      <playertype>1</playertype>
      <numcomments>146</numcomments>

    </video>
  </videos
</rsp>

/api/getVideosByChannelID

Returns a paginated list of videos that are related to the channel id of which is provided.
NOTE: please see Predefined Channel Ids

Example

http://www.videogenome.net/api/getVideosByChannelID?cid=1234
<rsp stat="ok" version="1.0">
  <videos page='1' pagesize="50" total='101' >
    <video>

      <id>595</id>
      <title>dream team tay lover and lil bro</title>
      <thumbnail><![CDATA[http://www.videogenome.net/thumbs/595.png]]></thumbnail>
      <vid_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></vid_url>

      <videoStartTimestamp>0</videoStartTimestamp>
      <duration>172</duration>
      <page_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></page_url>
      <ownerid>18eye-zpSX_</ownerid>

      <ownername><![CDATA[RESERVED]]></ownername>
      <ownerpic><![CDATA[RESERVED]]></ownerpic>
      <requesterid></requesterid>
      <type>1</type>

      <playertype>1</playertype>
      <numcomments>146</numcomments>
    </video>
  </videos
</rsp>

/api/getVideosBySearch

Returns a paginated list of videos that match the string search criteria given

Example

http://www.videogenome.net/api/getVideosBySearch?search=San%20Francisco&pagesize=100&page=2

<rsp stat="ok" version="1.0">
  <videos page='1' pagesize="50" total='101' >
    <video>
      <id>595</id>
      <title>dream team tay lover and lil bro</title>

      <thumbnail><![CDATA[http://www.videogenome.net/thumbs/595.png]]></thumbnail>
      <vid_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></vid_url>
      <videoStartTimestamp>0</videoStartTimestamp>
      <duration>172</duration>

      <page_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></page_url>
      <ownerid>18eye-zpSX_</ownerid>
      <ownername><![CDATA[RESERVED]]></ownername>
      <ownerpic><![CDATA[RESERVED]]></ownerpic>

      <requesterid></requesterid>
      <type>1</type>
      <playertype>1</playertype>
      <numcomments>146</numcomments>

    </video>
  </videos
</rsp>

/api/getVideosByAttributes

Returns a paginated list of videos that match attributes provided.
Note: this API is invoked via XML over HTTP POST

Example

POST /api/getVideosByAttributes HTTP/1.0

<attributes pagesize="50" page="1"> 
	<attributtype id='8' name='Emotion'> 
		<attribute id='8736' name='Happy' weight='7863'/> 
	</attributtype> 
	<attributtype id='6' name='Genre'> 
		<attribute id='567' name='SciFi' weight='82735'/> 
		<attribute id='19867' name='Horror' weight='87625'/> 
	</attributtype> 

</attributes>
<rsp stat="ok" version="1.0">
  <videos page='1' pagesize="50" total='101' >
    <video>
      <id>595</id>
      <title>dream team tay lover and lil bro</title>

      <thumbnail><![CDATA[http://www.videogenome.net/thumbs/595.png]]></thumbnail>
      <vid_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></vid_url>
      <videoStartTimestamp>0</videoStartTimestamp>
      <duration>172</duration>

      <page_url><![CDATA[http://www.youtube.com/watch?v=tEWYUi8rJx4]]></page_url>
      <ownerid>18eye-zpSX_</ownerid>
      <ownername><![CDATA[RESERVED]]></ownername>
      <ownerpic><![CDATA[RESERVED]]></ownerpic>

      <requesterid></requesterid>
      <type>1</type>
      <playertype>1</playertype>
      <numcomments>146</numcomments>

    </video>
  </videos
</rsp>

Comments

Comment object

<comment>

	<id>400</id>
	<emotion>0</emotion>
	<text><![CDATA[hi]]></text>
	<timestamp>0</timestamp>

	<userid>18eye-zpSX_</userid>
	<username><![CDATA[Wencheng]]></username>
	<picurl><![CDATA[http://10.33.176.90/userphotos/26.JPG]]></picurl>
	<created_at>2009-06-16 09:18:49</created_at>

	<ispublic>1</ispublic>
</comment>

/api/getComments

Retrieves a list of comments for the video given.
NOTE: If a user is authenticated, the resulting list will include items that a non-authenticated user will not get which is the following: private comments that were made by that user and private comments that were made by on of the friends of this user

Example

http://www.videogenome.net/api/getComments?vid=595
<rsp stat="ok" version="1.0">
  <comments>
	<comment>
		<id>400</id>
		<emotion>0</emotion>

		<text><![CDATA[hi]]></text>
		<timestamp>0</timestamp>
		<userid>18eye-zpSX_</userid>
		<username><![CDATA[Wencheng]]></username>

		<picurl><![CDATA[http://10.33.176.90/userphotos/26.JPG]]></picurl>
		<created_at>2009-06-16 09:18:49</created_at>
		<ispublic>1</ispublic>
	</comment>

	<comment>
		<id>402</id>
		<emotion>0</emotion>
		<text><![CDATA[tu]]></text>

		<timestamp>0</timestamp>
		<userid>18eye-zpSX_</userid>
		<username><![CDATA[Wencheng]]></username>
		<picurl><![CDATA[http://10.33.176.90/userphotos/26.JPG]]></picurl>

		<created_at>2009-06-16 09:27:06</created_at>
		<ispublic>1</ispublic>
	</comment>
    </comments>
</rsp>

/api/storeComment

Valid User Session Required




Creates a new comment for the video id of which is provided. Upon successful execution a full comment entry is returned
NOTE: this call requires authentication

Example

http://www.videogenome.net/api/storeComment?vid=595&time=1000&data=Comment%20Text&emotion=1&ispublic=1
<rsp stat="ok" version="1.0">	
      <comment>

		<id>403</id>
		<emotion>1</emotion>
		<text><![CDATA[Comment Text]]></text>
		<timestamp>1000</timestamp>

		<userid>18eye-zpSX_</userid>
		<username><![CDATA[Wencheng]]></username>
		<picurl><![CDATA[http://10.33.176.90/userphotos/26.JPG]]></picurl>
		<created_at>2009-06-16 09:27:06</created_at>

		<ispublic>1</ispublic>
	</comment>
</rsp>

Video Attributes and Values

Video genes are called AttributeType?. For a single attribute type there could be multiple Attributes per single video

Attribute type and Attribute objects

<attributtype id='8' name='Emotion'> 
    <attribute id='8736' name='Happy' weight='7863'/> 
    <attribute id='8737' name='Sad' weight='7000'/> 
</attributtype> 

/api/getVideoAttributes

Get all the attributes for the video list ids of which are specified

Example

http://www.videogenome.net/api/getVideoAttrs?vid=1,2,3

<rsp stat="ok" version="1.0">
	<attributes> 
		<attributtype id='8' name='Emotion'> 
			<attribute id='8736' name='Happy' weight='7863'/> 
		</attributtype> 
		<attributtype id='6' name='Genre'> 
			<attribute id='567' name='SciFi??' weight='82735'/> 
			<attribute id='19867' name='Horror' weight='87625'/> 
		</attributtype> 
	</attributes>

</rsp>

/api/getAttributesBySearch

Returns the attribute values that match the search criteria and attribute type provided

Example

http://www.videogenome.net/api/getAttributesBySearch?tid=8&search=Happy

<rsp stat="ok" version="1.0">
	<attributes> 
		<attributtype id='8' name='Emotion'> 
			<attribute id='8736' name='Happy' weight='0'/> 
		</attributtype> 
	</attributes>
</rsp>

Integration Parameters

Overview

For those that do not want to use our Embeddable Player, we also provide the ability to integrate with the same API above with some additional require parameters and a few more APIs. First you must have a user account and that user account needs to be registered as an Integration User. With the registration as an Integration user you will get two pieces of information: devID and devSeceret. These will be used to call our APIs and enable you to integrate your site with our APIs. Here are the additional parameters require to use all of the above APIs:

nameValueNotes
devIDYour dev IDPlease remember to register to get this and the devSeceret
sigMD5 hash of the request, the devSeceret, and API paramsSee documentation below for full document on how to generate this signature
userSessionUser Session KeyRequired only by the APIs that require a valid user session (See API below)

The devID is provided as you have received it. You will use it with all API calls. In order to validate that an API request with your devID is valid, you need to also provide the calculated signature for the API call.

To generate the signature parameter, you must build the following string and collect its md5 hash: requestURI|devSeceret|sortedAPIParams where requestURI looks like: /api//api/storeComment and sortedAPIParams follow this pattern in alphabetical order by key: key=value|key2=value As a complete example of a string used to create the verifying md5 hash(not URL encoded): /api/storecomment|4acbb8ca8af1e|data=Comment Text|ispublic=1|rid=1|time=1000|userSession=4acbbb6e20f65|vid=595 resulting in this MD5 hash: c78785182f6c06ec14d50d5be325aa91

In the case the signature is invalid, we do issue an Invalid signature error message. This includes data that should help you resolve the problem. It includes the following information:

namevalueAdditional Notes
requestURIthe incoming requestURIThis is the request URI from our perspective
recv_devIDreceived devIDThis is the devID we received
recv_sigreceived signatureThis is the signature exactly as we received it
sigParam_*Sorted list of signature parametersThis is the alphabetical list of parameters we used to verify your signature

Finally, many of the APIs require a valid user session. This is maintain automatically by VideoGenome? during native calls to the API. In order to aquire a user session via the non-native integration you need to use the following API calls:

/api/getAuthorizationKey

Returns the authentication key and userID needed to acquire a user session. This authentication key will be valid only for a short time (no more than 30s). You must call getUserSession with the authentication key before then.

Example

http://www.videogenome.net/api/getAuthorizationKey?userEmail=myEmail@nowhere.com&pwd=c78785182f6c06ec14d50d5be325aa91&devID=18eye-zpSX_4acbbeac2ea14&sig=c6ffa835b0b1d4b95332c5a44d241ee6
<rsp stat="ok" version="1.0">
  <user id="18eye-zpSX_">4acbc22eb9994</user>
</rsp>

/api/getUserSession

Returns the UserSession? id required by many of the API calls. Most API calls will refresh the session. However, certain call like /api/getComments does not refresh the session. If a session expires, you are required to re-authenticate them. See Common Error format for the error response and the invalid session code.

Example

http://www.videogenome.net/api/getUserSession?userID=18eye-zpSX_&authKey=4acbc22eb9994&devID=18eye-zpSX_4acbbeac2ea14&sig=c0acfda91e1d9c998518ec6e106e7d38
<rsp stat="ok" version="1.0">
  <user id="18eye-zpSX_">cde7a262ccca4</user>
</rsp>