General Rules

Endpoint: http://api.vodpod.com/api/<subject>/<action>[.xml|.js]?<params...>

Common Parameters

api_key    = Authenticates the caller

auth = Authenticates the caller with write permission 

page = The number of the page of results you want, base 1

per_page = Number of results you want back in each page

pod_id = subdomain or id of the Pod you want to interrogate

sort = Optional when retrieving lists. Defaults to 'recent'. Possible values are:

  recent, popular, weekly (views this week), rating

query = A URL-encoded set of search words

Errors

Error will result in HTTP status codes of 401 (if authentication fails) or 500 (for other errors). An

XML document will be returned with the explanation, like this:

<error code="102">Missing argument "query"</error>

Pod Services

/pod/details

Arguments: *pod_id

 

Returns the details about a pod.

Example: http://api.vodpod.com/api/pod/details.xml?pod_id=persingers&api_key=your_key

<pod pod_id="10">
  <name>
    Persinger Boys
  </name>
  <subdomain>persingers</subdomain>
  <description>
    Videos of my boys
  </description>
  <created_at>Tue, 23 May 2006 12:38:04 -0700</created_at>
  <user user_id="1" username="scottp">scottp</user>

</pod>

/pod/videos

Returns a list of videos from a certain Pod.

Arguments: *pod_id, sort, per_page, page, tag_id, tag_bool

Example: http://api.vodpod.com/api/pod/videos.xml?pod_id=persingers&api_key=your_key&sort=views.desc&page=2&per_page=2

 

<videos total="12">
  <video video_id="271433">
    <title>Drew's First Birthday</title>
    <description>taken on Sep 1, 2007</description>
    <tags>drew</tags>
    <embed_tag><embed ...></embed></embed_tag>
    <pod_id>10</pod_id>
    <created_at>Mon, 03 Sep 2007 23:21:44 -0700</created_at>
    <updated_at>Mon, 03 Sep 2007 23:21:44 -0700</updated_at>
    <user user_id="1" username="scottp">scottp</user>
    <thumbnails fetched="true">
    <small>http://s3.amazonaws.com/vodpod.com.videos.thumbnail/216725.jpg</small>
    <medium>http://s3.amazonaws.com/vodpod.com.videos.thumbnail/216725.medium160.jpg</medium>
    <large>http://s3.amazonaws.com/vodpod.com.videos.thumbnail/216725.large.jpg</large>
    </thumbnails>
    <stats> ... </stats>
  </video>
  <video video_id="271431">
     ...
  </video>
</videos>

 

To limit the videos returned to those with a specific tag, add:

 

&tag_id=<tag name>

Like:

    &tag_id=barack+obama

You may also return videos with multiple tags, comma separated.  By default, it will return the videos using and OR operator.  For example:

    &tag_id=barack+obama,politics

will return videos that are tagged either "barack obama" OR "politics".

You can pull from multiple tags with an AND constraint by setting tag_bool=and.  For example:

    &tag_id=barack+obama,2008&tag_bool=and

will return videos that are tagged with both "barack obama" and "2008".

/pod/tags

Arguments: *pod_id

 

Returns the top tags used on the videos in this collection, in order of frequency of use.

Example: http://api.vodpod.com/api/pod/tags.xml?pod_id=persingers&api_key=your_key

<tags pod_id="1004">
  <t tag_id="10" count="21">politics</t>
  <t tag_id="202" count="12">funny</t>
  <t tag_id="797839" count="11">sarah palin</t>
  <t tag_id="13053" count="7">john mccain</t>
</tags>

/pod/search

Arguments: *pod_id, *query, sort, per_page, page

Returns the videos from the given collection whose title/descriptions match the indicate query terms.

Example: http://api.vodpod.com/api/pod/search.xml?pod_id=persingers&api_key=your_key&query=obama

<videos total="8">
  <video video_id="1177032">
    <title>Barack Obama North Carolina Primary Victory Speech</title>
    <description>...</description>
    <tags>obama, campaing08, election08</tags>
    <link>http://vodpod.com/watch/702378-barack-obama-north-carolina-primary-victory-speech</link> 
    <embed_tag>..</embed_tag> 

  </video>

  <video>

    ...

  </video>

...

</videos>

Video Services

/video/details

Arguments: *video_id

 

Returns the details for a given video.

 

Example: http://api.vodpod.com/api/video/details.xml?video_id=614&api_key=your_key

 

<video video_id="614">
  <title>Easter 2006 in Orinda</title>
  <description>Ben and Evan at Easter 2006</description>
  <tags>ben evan</tags>
  <embed_tag><embed ...></embed></embed_tag>
  <pod_id>10</pod_id>
  <created_at>Mon, 03 Sep 2007 23:21:44 -0700</created_at>
  <updated_at>Mon, 03 Sep 2007 23:21:44 -0700</updated_at>
  <user user_id="1" username="scottp">scottp</user>
  <thumbnails fetched="true">
    <small>http://s3.amazonaws.com/vodpod.com.videos.thumbnail/216725.jpg</small>
    <medium>http://s3.amazonaws.com/vodpod.com.videos.thumbnail/216725.medium160.jpg</medium>
    <large>http://s3.amazonaws.com/vodpod.com.videos.thumbnail/216725.large.jpg</large>
  </thumbnails>
  <stats>
    <total_views>10</total_views>
    <total_pod_views>8</total_pod_views>
    <total_widget_views>2</total_widget_views>
    <weekly_views>2</weekly_views>
    <weekly_pod_views>2</weekly_pod_views>
    <weekly_widget_views>0</weekly_widget_views>
  </stats>
</video>

 

/video/search

Returns videos from any Pod matching the given search words.

Arguments: *query, per_page, page

Example: http://api.vodpod.com/api/video/search.xml?query=ben&api_key=bb3dc0d68be28

<videos total="3">
  <video video_id="271433">
    <title>Ben eating some cake</title>
    <pod_id>10</pod_id>

    ...
  </video>
  <video video_id="271431">

    <title>I can't believe he ate that</title>

    <description>My friend ben eats a work</description>

    <pod_id>28383</pod_id>

    ...
  </video>

  <video>

     ...

  </video>
</videos>

/video/post

Add a new video to a Pod.

 

Arguments: *auth, *api_key, *pod_id, *[url,embed], title, description, tags

Returns: a <video> record with details of the new video. 

 

You should indicate the video by passing either the url of the page containing the video, or the <embed> code for the video.

 

Parameters should be passed as typical POST parameters (url encoded var=value&var=value style).

 

Example:  http://api.vodpod.com/api/video/post.xml?api_key=bb3dc0d68be28&auth=XXXX&url=http://youtube.com/watch?v=gXU8kCrRHJY&

                     title=the+police+message+in+a+bottle&description=a+good+music+video&tags=police+music
<video video_id="29282">

  <title>the police message in a bottle</title>

  <description>a good music video</description>

  <tags>police music</tags>

  <embed_tag> .. </embed_tag>

</video>

/video/update

Update the attributes of a video.

 

Arguments: *auth, *api_key, *video_id, title, description, tags

Example: http://api.vodpod.com/api/video/post.xml?api_key=bb3dc0d68be28&auth=XXX,video_id=28272&title=the+new+title

 

Returns the <video> details record with the new attributes. 

User Services

/user/network_activity

Returns the recent activity by those users related to the indicated user.

 

Arguments: user_id

 

 

Related Videos

We also offer an service for fetching related videos based on our user's video collecting habits.  You can see examples of this data on all of our video pages.

Please contact us at (support at vodpod) if you are interested in this.

Notes

Old sorts included:

date-desc, date-asc, views-desc, views-asc, weekly-views-desc, weekly-views-asc, rating-desc, rating-asc