Viddler API via Perl

| 0 Comments | 0 TrackBacks
| | | |

Recently, while doing some consulting work, I started working with an new online video platform called Viddler. Much like YouTube, Viddler is a web application, built around videos, that allows one to upload and share on the web.

However, unlike YouTube, Viddler also provides a great deal of features for customization, from the skinning of the video player to the integration of the Viddler platform into customized web applications. The obvious advantage here for a business or organization is the ability to provide video content wrapped within their own branding or application without the expense of building and managing the huge computing infrastructure required for bandwidth and data storage.

For example, checkout the MIT Tech TV, a video-sharing site for the MIT community built using Viddler.

Alas, while there is plenty of support for the Viddler Application Programming Interface via PHP, which is what my consulting work is based in, the support for Perl is quite anemic.

To help rectify this dire situation, in my free time over the last week or so, I've been working on an Perl module that wraps around Viddler's API. The goal here is not only to provide a basic how-to, but a quick method for integrating Perl-based applications with Viddler. As such, I plan on having something more formal to submit, not only to Viddler's Project Directory, but to CPAN as well, in the near future.

With that in mind, here's the basic layout with a few implemented methods for guidance and testing:

package Viddler;

use strict;
use warnings;

use LWP::Simple;
use XML::Simple;

our $VERSION = "0.01";

### To Do
#
# Complete support of all API methods
# Add SSL option for methods such as users_auth
# Validation/Error Handling of parameters/results 
#
#### 

=head1 NAME

Viddler - An encapsulation of the Viddler video platform in Perl

=head1 SYNOPSIS

use Viddler;
my $videos = new Viddler( apiKey => $apiKey, 
			  username => $username,
			  password => $passwd,
			);

print "API Version: " .$videos->api_getInfo(). "\n";

=head1 DESCRIPTION

This is an object-oriented library which focuses on pro diving Perl 
specific methods for accessing the Viddler video service via their 
API, as documented at: 
http://developers.viddler.com/documentation/api/

=head2 Methods

=head3 new

my $video = Viddler->new( apikey => $key, 
			  username => $username, 
			  password => $passwd );

Instantiates an object which established the basic connection to 
the API, including requesting and setting session id.

=cut

# The constructor of an object is called new() by convention.  
   
sub new {

	my ( $class, %args ) = @_;
	my $new = bless {
		_apiURL => 'http://api.viddler.com/rest/v1/',
		_sessionID => undef,
		_record_token => undef,
		%args
	}, $class;

	# Get a sessionid
	$new->users_auth;

	return $new;

}

=head3 users_auth

Gets and sets a sessionid for an authenticated Viddler account.
Returned sessionid is valid for 5 minutes (may change in the
future). Every method request which contains valid sessionid,
renews its validity time.

$video->users_auth;

No required parameters. Will use username and password defined
at object's creation

Additional options parameters include: 

* get_record_token: If set to response will also include
recordToken

Returns 0 ( false ) if unsucessful and 1 ( true ) if sucessful

=cut

sub users_auth {

	my ( $self, $get_record_token ) = @_;

	my $xml = new XML::Simple;
	my $content = get $self->{_apiURL}. 
		"?method=viddler.users.auth&api_key="
		.$self->{apiKey}. "&user=" .$self->{username}. 
		"&password=" .$self->{password}. 
		"get_record_token=" .$get_record_token;
	my $results = $xml->XMLin( $content );
	$self->{_sessionID} = $results->{'sessionid'};
	
	if ( defined $results->{'get_record_token'} ) {

		$self->{_recordToken} = $results->{'record_toaken'};

	}

	if ( defined ( $self->{_sessionID} )) {

		return 1;

	} else {

		return 0;

	}

}

=head3 api_getInfo

Gets and returns the current version of the Viddler API.

$video->api_getInfo;

Returns current API version as a string

=cut

sub api_getInfo {

	my ( $self ) = @_;

	my $xml = new XML::Simple;
	my $content = get $self->{_apiURL}. 
		"?method=viddler.api.getInfo&api_key=" 
		.$self->{apiKey};
	my $results = $xml->XMLin( $content );
	return $results->{'version'};

}

=head3 videos_search

Gets and returns results of a search of Viddler videos and people.

$video->videos_search( $type, $query, $page, $per_page );

Requires the following parameters:

* type: The type of search (e.g. "myvideos", 
"friendsvideos", "allvideos", "relevant", "recent", "popular",
 "timedtags", "globaltags". (The "timedtags" and "globetags"
sorting argument should be used in conjunction with an actual 
tag being given for the query argument.))

* query: What to search for (e.g. "iPhone", "Pennsylvania", or 
"Windows XP")

Additional options parameters include: 

* page: The "page number" of results to retrieve (e.g. 1, 2, 3).

* per_page: The number of results to retrieve per page (maximum 
100). If not specified, the default value equals 20.

Returns a hash of an array of search results

=cut

sub videos_search( $$ ) {

	my ( $self, $type, $query, $page, $per_page ) = @_;

	my $xml = new XML::Simple;
	my $content = get $self->{_apiURL}. 
		"?method=viddler.videos.search&api_key=" 
		.$self->{apiKey}. "&type=" .$type. 
		"&query=" .$query. "&page=" .$page. 
		"&per_age=" .$per_page. "&sessionid=" 
		.$self->{_sessionID};
	my $results = $xml->XMLin( $content );
	return $results;

}

=head3 videos_getByUser

Gets and returns a lists of all videos that were uploaded by the 
specified user.

$video->videos_getByUser( $user, page, $per_page, $tags, $sort );

Requires the following parameters:

* user: The chosen Viddler user name. You can provide multiple 
coma separated viddler usernames

Additional options parameters include: 

* page: The of results to retrieve (e.g. 1, 2, 3).

* per_page: The number of results to retrieve per page (maximum 
100). If not specified, the default value equals 20.

* tags: The tags you would like to filter your query by.

* sort: How you would like to sort your query (views-asc, 
views-desc, uploaded-asc, uploaded-desc)

Returns a hash of an array of search results

=cut

sub videos_getByUser( $ ) {

	my ( $self, $user, $per_page, $page, $tags, $sort ) = @_;

	my $xml = new XML::Simple;
	my $content = get $self->{_apiURL}. 
		"?method=viddler.videos.getByUser&api_key=" 
		.$self->{apiKey}. "&sessionid=" 
		.$self->{_sessionID}. "&user=" .$user. 
		"&page=" .$page. "&per_age=" .$per_page. 
		"&tags=" .$tags. "&sort=" .$sort;
	my $results = $xml->XMLin( $content );
	return $results;

}

=head1 AUTHOR

Paul Weinstein pdw [at] weinstein [dot] org

=cut

1;
__END__

And here's a little code to test the demo package:

#!/usr/bin/perl -T

use strict;
use warnings;

use Data::Dumper;
use Viddler;

my $videos = new Viddler( apiKey => '1234567890abcdefghij', 
			  username => 'username',
			  password => 'password',
			);

print "API Version: " .$videos->api_getInfo(). "\n";

my $searchResults = $videos->videos_getByUser( "username", 
						"", "", 
						"test", "" );
print Dumper( $searchResults );

Comments, suggestions or corrections are quite welcomed.

No TrackBacks

TrackBack URL: http://pdw.weinstein.org/mt/mt-tb.cgi/193

Leave a comment

About the Author

Paul is a technologist and all around nice guy for technology oriented organizations and parties. Besides maintaining this blog and website you can follow Paul's particular pontifications on the Life Universe and Everything on Twitter.

   
   


Subscribe:
Add to Google Reader or Homepage
Add to My AOL

Add to netvibes
Subscribe in Bloglines
Add to Technorati Favorites

Powered
CentOS
Apache
MySQL
Perl
Movable Type Pro