Viddler API via Perl

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__

#!/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 );