NAME

WebService::GData::YouTube - Access YouTube contents(read/write) with API v2.

SYNOPSIS

    use WebService::GData::YouTube;

    #create an object that only has read access
    my $yt = new WebService::GData::YouTube();

    #get a feed response from YouTube;
    my $videos  = $yt->get_top_rated_videos;
    #more specific:
    my $videos  = $yt->get_top_rated_videos('JP','Comedy');

    foreach my $video (@$videos) {
        say $video->video_id;
        say $video->title;
        say $video->content;
    }

    #connect to a YouTube account
    my $auth = new WebService::GData::ClientLogin(
        email   =>'...'
        password=>'...',
        key     =>'...'
    );

    #give write access
    my $yt = new WebService::GData::YouTube($auth);

    #returns all the videos from the logged in user 
    #including private ones.
    my $videos  = $yt->get_user_videos();

    #update the videos by adding the common keywords if they are public
    #delete a certain video by checking its id.
    foreach my $video (@$videos) {

        if($video->video_id eq $myid) {

            $video->delete();

        } else {

            if($video->is_listing_allowed){

                $video->keywords('music,live,guitar,'.$video->keywords);
                $video->save();
            }
        }
    }

DESCRIPTION

!DEVELOPER RELEASE! API may change, program may break or be under optimized.

!WARNING! Documentation in progress.

inherits from WebService::GData

This package is a point of entry giving access to general YouTube feeds. Passing an optional authorization object (WebService::GData::ClientLogin) will allow you to access private contents. It also offers some helper methods to shorten up the code. Most of the methods will return one of the following object:

WebService::GData::YouTube::Feed::Video

This object handles the manipulation of the video data such as inserting/editing the metadata, uploading a video,etc.

WebService::GData::YouTube::Feed::Comment

This object handles the insertion of comments on a video or in reply to an other comment.

WebService::GData::YouTube::Feed::Playlist

This object inherits from WebService::GData::YouTube::Feed::Video. It contains a list of all the videos within this particular playlist. The only difference with WebService::GData::YouTube::Feed::Video is that it offers the position tag that specifies the position of the video within the playlist.

WebService::GData::YouTube::Feed::PlaylistLink

This object represents all the playlists metadata of a user. It is not possible to get the metadata of one playlist. You need to query them all and search for the one you're interested in.

WebService::GData::YouTube::StagingServer

use this package at the very top of your program to switch all the read/writes urls to the staging server

CONSTRUCTOR

new

Create a WebService::GData::YouTube instance.

Parameters

auth:Object (optional) - Accept an optional authorization object.: Only WebService::GData::ClientLogin is available for now but OAuth should come anytime soon. Passing an auth object allows you to access private contents and insert/edit/delete data.

Returns

WebService::GData::YouTube instance

Example:

use WebService::GData::ClientLogin;
use WebService::GData::YouTube;

#create an object that only has read access
my $yt = new WebService::GData::YouTube();

#connect to a YouTube account
my $auth = new WebService::GData::ClientLogin(
    email=>'...'
    password=>'...',
    key        =>'...'
);

#give write access with a $auth object that you created
my $yt = new WebService::GData::YouTube($auth);

GENERAL METHODS

query

Set/get a query object that handles the creation of the query string sent to the service. The query object will build the query string required to access the data. All queries contain some default parameters like the alt,v,strict parameters. You can add other parameters in order to do a search.

Parameters

none - getter context
query:Object - setter context accept a query string builder instance. Default to WebService::GData::YouTube::Query

Returns

query:Object in both setter/getter context the query object. Default to WebService::GData::YouTube::Query

Example:

	use WebService::GData::YouTube;

   	my $yt = new WebService::GData::YouTube();

	$yt->query()->q("ski")->limit(10,0);

	#or set your own query object
	$yt->query($myquery);

	my $videos = $yt->search_video();

base_uri

Get the base uri used to query the data.

Parameters

none

Returns

url:Scalar the root uri

base_query

Get the base query string used to get the data.

Parameters

none

Returns

url:Scalar - default to ?alt=json&prettyprint=false&strict=true

connection

Get the connection handler (WebService::GData::Base by default). Mostly usefull to set connector settings.

Parameters

none

Returns

object:Object the connector instance,by default WebService::GData::Base.

Example:

use WebService::GData::YouTube;

my $yt   = new WebService::GData::YouTube();
   $yt->connection->timeout(100)->env_proxy;

STANDARD FEED METHODS

YouTube offers some feeds regarding videos like the most discussed videos or the most viewed videos. All the standard feed methods are implemented:

methods

get_top_rated_videos

get_top_favorites_videos

get_most_viewed_videos

get_most_shared_videos

get_most_popular_videos

get_most_recent_videos

get_most_discussed_videos

get_most_responded_videos

get_recently_featured_videos

get_on_the_web_videos

See http://code.google.com/intl/en/apis/youtube/2.0/developers_guide_protocol_video_feeds.html#Standard_feeds

All the above standard feed methods accept the following optional parameters:

Parameters

region_zone:Scalar - a country code - ie:JP,US.
category:Scalar - a video category - ie:Comedy,Sports.
time:Scalar - a time - ie:today,this_week,this_month,all_time

Returns

WebService::GData::Youtube::Feed::Video objects

Throws

WebService::GData::Error

Example:

    use WebService::GData::YouTube;
	
    my $yt   = new WebService::GData::YouTube();
    my $videos = $yt->get_top_rated_videos();
    my $videos = $yt->get_top_rated_videos('JP');#top rated videos in Japan
    my $videos = $yt->get_top_rated_videos('JP','Comedy');#top rated videos in Japanese Comedy 
    my $videos = $yt->get_top_rated_videos('JP','Comedy','today');#top rated videos of the day in Japanese Comedy

See also:

Explanation of the different standard feeds:

http://code.google.com/intl/en/apis/youtube/2.0/reference.html#Standard_feeds

VIDEO FEED METHODS

These methods allow you to access videos. You do not need to be logged in to use these methods.

get_video_by_id

Get a video by its id.

Parameters

video_id:Scalar - the unique id of the video- ie:Displayed in the url when watching a video. Looks like:Xzek3skD

Returns

WebService::GData::YouTube::Feed::Video

Throws

WebService::GData::Error

Example:

    use WebService::GData::YouTube;
	
    my $yt   = new WebService::GData::YouTube();

    my $video = $yt->get_video_by_id('Xzek3skD');

search_video

Send a request to search for videos. You create the query by calling $yt->query and by setting the available parameters.

Parameters

query:Object (optional) - a query builder instance

Returns

WebService::GData::YouTube::Feed::Video

Throws

WebService::GData::Error

Example:

use WebService::GData::YouTube;

my $yt   = new WebService::GData::YouTube();

   $yt->query->q("ski")->limit(10,0);

my $videos = $yt->search_video();

#or

my $yt     = new WebService::GData::YouTube();
my $query  = $yt->query;
   $query -> q("ski")->limit(10,0);
my $videos = $yt->search_video();

#or set a new query object
#it could be a sub class that has predefined value

my $query  = new WebService::GData::YouTube::Query();

   $query -> q("ski")->limit(10,0);

my $videos = $yt->search_video($query);#this is a helper the same as doing: $yt->query($query); $yt->search_video();

See also:

A list of all the query parameters and related methods you can use with the default query object:

WebService::GData::YouTube::Query

get_related_for_video_id

Get the related videos for a video. These videos are returned by following YouTube's own algorithm.

Parameters

video_id:Scalar - the unique identifier of the video.

Returns

WebService::GData::YouTube::Feed::Video objects

Throws

WebService::GData::Error

Example:

my $yt   = new WebService::GData::YouTube();

my $videos = $yt->get_related_for_video_id('Xz2eFFexA');

get_comments_for_video_id

Get the comments of a video.

Parameters

video_id:Scalar - the unique identifier of the video.

Returns

WebService::GData::Collection instances of WebService::GData::YouTube::Feed::Comment

Throws

WebService::GData::Error

Example:

use WebService::GData::YouTube; 
my $yt   = new WebService::GData::YouTube();

my $comments = $yt->get_comments_for_video_id('Xz2eFFexA');

foreach my $comment (@$comments){
	say $comment->content;
}

USER VIDEO FEED METHODS

All these methods allow you to access the videos of the programmaticly logged in user. Being logged in allow you to access private contents or contents that have been uploaded but is not public yet. The responses will also have a read/write access so you will be able to edit the videos.

It does not mean that you need to be logged in to use these methods. By setting the name of the user (channel name),you will only get a read access to the public data.

get_user_video_by_id

Get a video for the logged in user or for the user name you specified. It queries the uploads feed which can be more up to date than the feed used with get_video_by_id().

Parameters

video_id:Scalar - the id of the video
user_name:Scalar (optional) - the name of the user (channel name)

Returns

WebService::GData::YouTube::Feed::Video objects

Throws

WebService::GData::Error

Example:

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

my $videos = $yt->get_user_video_by_id('Xz2eFFexA');

#if not logged in.
my $videos = $yt->get_user_video_by_id('Xz2eFFexA','live');#you must specify the user if not logged in!

get_user_videos

Get the videos for the logged in user or for the user name you specified.

Parameters

user_name:Scalar (optional) - the user name/channel name

Returns

WebService::GData::YouTube::Feed::Video objects

Throws

WebService::GData::Error

Example:

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

my $videos = $yt->get_user_videos();

#if not logged in, pass the user name as the first parameter
my $videos = $yt->get_user_videos('live');

get_user_favorite_videos

Get the videos that user specificly set a favorites (meaning that you may not have write access to the content even if you are logged in!).

Parameters

user_name:Scalar (optional) - the user name/channel name

Returns

WebService::GData::YouTube::Feed::Video objects

Throws

WebService::GData::Error

Example:

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

my $videos = $yt->get_user_favorite_videos();

#if not logged in, pass the user name as the first parameter
my $videos = $yt->get_user_favorite_videos('live');

add_favorite_video

Parameters

video_id:Scalar the video id you want to add as a favorite

Returns

void

Throws

WebService::GData::Error

Example:

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

   $yt->add_favorite_video('video_id');

get_recommended_videos

Get the videos that a user may be interested in (defined by the YouTube algorithm).

You must be logged in to use this feature.

Parameters

none

Returns

WebService::GData::YouTube::Feed::Video objects

Throws

WebService::GData::Error

Example:

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

my $videos = $yt->get_recommended_videos();

RATING METHODS

These methods allows you to rate,like or dislike, a video. They are helper methods that instantiate a video instance for you.

You must be logged in to use these methods.

like_video

dislike_video

Parameters

video_id:Scalar the video id to rate

Returns

void

Throws

WebService::GData::Error

Example:

 my $auth = new WebService::GData::ClientLogin(email=>...);
 
 my $yt   = new WebService::GData::YouTube($auth);
 
    $yt->like_video('video_id');
    $yt->dislike_video('video_id');
    
#in the background it simply does:

my $vid = $yt->video;
   $vid->video_id('video_id');
   $vid->rate('like');

VIDEO RESPONSE METHODS

These methods allow you to add a video as a response to an other video. You can also erase a video response.

They are helper methods that instantiate a video instance for you. You must be logged in to use these methods.

add_video_response

Parameters

video_id:Scalar the video id you want to response to
video_response_id:Scalar the video id of the response

Returns

void

Throws

WebService::GData::Error

Example:

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

   $yt->add_video_response('video_id','video_response_id');

delete_video_response

Parameters

video_id:Scalar the video id that was responsed to
video_response_id:Scalar the video id of the response

Returns

void

Throws

WebService::GData::Error

Example:

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

   $yt->delete_video_response('video_id','video_response_id');

FACTORY METHODS

These methods instantiate YouTube::Feed::* packages. It just saves some typing.

Example:

use constant KEY=>'...';
    
my $auth; 
eval {
    $auth = new WebService::GData::ClientLogin(
       email=>'...@gmail.com',
       password=>'...',
       key=>KEY
   );
};     

my $yt = new WebService::GData::YouTube($auth);

#instantiate a comment
my $comment = $yt->comment;

   $comment->content('thank you all for watching!');
   $comment->video_id('2lDekeCDD-J1');#attach the comment to a video
   $comment->save;
   
#instantiate a video
my $video = $yt->video;  
 
   $video->title('Live at Shibuya tonight');
   $video->description('Live performance by 6 local bands.');
   $video->keywords('music','live','shibuya','tokyo');
   $video->category('Music');
#etc

get_user_profile

Get the user profile info for the logged in user or the user set as a parameter.

Parameters

user_name:Scalar (optional) - the user name/channel name

Returns

WebService::GData::YouTube::Feed::UserProfile instance

Throws

WebService::GData::Error

Example:

use WebService::GData::ClientLogin;
use WebService::GData::YouTube;

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

my $profile = $yt->get_user_profile;

#or if you did not pass a $auth object:
my $profile = $yt->get_user_profile('profile_name_here');

get_user_contacts

Get the user contact info for the logged in user or the user set as a parameter. A maximum of 100 contacts can be retrieved.

Parameters

user_name:Scalar (optional) - the user name/channel name

Returns

WebService::GData::Collection instance containing WebService::GData::YouTube::Feed::Friend instances

Throws

WebService::GData::Error

Example:

use WebService::GData::ClientLogin;
use WebService::GData::YouTube;

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

my $contacts = $yt->get_user_contacts;

#or if you did not pass a $auth object:
my $contacts = $yt->get_user_contacts('profile_name_here');

get_user_inbox

Get the user inbox for the logged in user.

Parameters

none

Returns

WebService::GData::Collection instance containing WebService::GData::YouTube::Feed::VideoMessage instances

Throws

WebService::GData::Error

Example:

use WebService::GData::ClientLogin;
use WebService::GData::YouTube;

my $auth = new WebService::GData::ClientLogin(email=>...);

my $yt   = new WebService::GData::YouTube($auth);

my $messages = $yt->get_user_inbox;

foreach my $message (@$messages){
	say $message->subject;
	say $message->content;
	say $message->from->name;
	say $message->sent;
}

USER PLAYLIST METHODS

!WARNING! Playlits related methods does not work perfectly yet!!

These methods allow you to access the videos in a playlist or a list of playlists created by a user. If you are logged in, you will be able to modify the data. If you are not logged in,you will only have a read access and you must set the user name.

get_user_playlist_by_id

Retrieve the videos in a playlist by passing the playlist id.

Parameters

playlist_id:Scalar - the id of the playlist, looks like 'CFESE01KESEQE'

Returns

WebService::GData::YouTube::Feed::Playlist

A WebService::GData::YouTube::Feed::Playlist contains the same information as a WebService::GData::YouTube::Feed::Video instance

but adds the position information of the video within the playlist.

Throws

WebService::GData::Error

Example:

    my $auth = new WebService::GData::ClientLogin(email=>...);#not compulsory
    
    my $yt   = new WebService::GData::YouTube($auth);
    
    my $videos_in_playlist = $yt->get_user_playlist_by_id('CFESE01KESEQE');
    
    #a feed returns by default up to 25 videos. 
    #you can loop over the entire playlist (if you have more than 25 videos)
    #if your playlist contains more than 50 videos, you can set the query limit to be 50
    #it will result in less calls to the server.
    
    while(my $videos = $yt->get_user_playlist_by_id('CFESE01KESEQE')){
    	
    	foreach my $video (@$videos) {
    		say $video->title;
    	}
    }

get_user_playlists

Get the playlists metadata for the logged in user or the user set as a parameter.

Parameters

user_name:Scalar (optional) - the user name/channel name

Returns

WebService::GData::YouTube::Feed::PlaylistLink objects

If you are logged in, you can access private playlists.

WebService::GData::YouTube::Feed::PlaylistLink is a list of playlists. If you want to modify one playlist metadata, you must get them all, loop until you find the one you want and then edit.

Throws

WebService::GData::Error

Example:

    use WebService::GData::Base;

    my $auth = new WebService::GData::ClientLogin(email=>...);
    
    my $yt   = new WebService::GData::YouTube($auth);
    
    my $playlists = $yt->get_user_playlists;
	
    #or if you did not pass a $auth object:
    my $playlists = $yt->get_user_playlists('live');	
    
    #a feed returns by default up to 25 entries/playlists. 
    #you can loop over the channel playlists (if you have more than 25 playlists)
    #if your channels contains more than 50 playlists, you can set the query limit to be 50
    #it will result in less calls to the server.    
    
    #this is a working example 
    #list all the programming related tutorials from thenewboston channel:
    my $yt = new WebService::GData::YouTube(); 
       $yt->query->max_results(50);
       
    my $playlist_counter=1;
    while(my $playlists = $yt->get_user_playlists("thenewboston")) {

        foreach my $playlist (@$playlists) {
            say($playlist_counter.':'.$playlist->title);
            
            my $video_counter=1;
            while(my $videos = $yt->get_user_playlist_by_id($playlist->playlist_id)) {
            	foreach my $vid (@$videos){
                say(" ".$video_counter.':'.$vid->title);
                $video_counter++;
            	}
            }
        }
        $playlist_counter++;
    }

HANDLING ERRORS

Google data APIs relies on querying remote urls on particular services. Some of these services limits the number of request with quotas and may return an error code in such a case. All queries that fail will throw (die) a WebService::GData::Error object. You should enclose all code that requires connecting to a service within eval blocks in order to handle it.

Example:

use WebService::GData::Base;

my ($auth,$videos);

eval {
    $auth = new WebService::GData::ClientLogin(email=>...);
};

my $yt   = new WebService::GData::YouTube($auth);

#the server is dead or the url is not available anymore or you've reach your quota of the day.
#boom the application dies and your program fails...

my $videos = $yt->get_user_videos;

#with error handling...

#enclose your code in a eval block...
eval {
    $videos = $yt->get_user_videos;
}; 

#if something went wrong, you will get a WebService::GData::Error object back:

if(my $error = $@){

    #do whatever you think is necessary to recover (or not)
    #print/log: $error->content,$error->code
}

TODO

Many things are left to be implemented!

The YouTube API is very thorough and it will take some time but by priority:

OAuth authorization system
Channel search
Playlist search
know the status of a video
Partial Upload
Partial feed read/write

Certainly missing many other stuffs...

DEPENDENCIES

JSON
LWP

BUGS AND LIMITATIONS

If you do me the favor to _use_ this module and find a bug, please email me i will try to do my best to fix it (patches welcome)!

AUTHOR

shiriru <shirirulestheworld[arobas]gmail.com>

LICENSE AND COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

7 POD Errors

The following errors were encountered while parsing the POD:

Around line 598:

You forgot a '=back' before '=head3'

Around line 1190:

You forgot a '=back' before '=head3'

Around line 1234:

=back without =over

Around line 1246:

You forgot a '=back' before '=head3'

Around line 1322:

=back without =over

Around line 1331:

You forgot a '=back' before '=head3'

Around line 1386:

=back without =over

To install WebService::GData, copy and paste the appropriate command in to your terminal.

cpanm

cpanm WebService::GData

CPAN shell

perl -MCPAN -e shell
install WebService::GData

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

CONSTRUCTOR

new

GENERAL METHODS

query

base_uri

base_query

connection

STANDARD FEED METHODS

get_top_rated_videos

get_top_favorites_videos

get_most_viewed_videos

get_most_shared_videos

get_most_popular_videos

get_most_recent_videos

get_most_discussed_videos

get_most_responded_videos

get_recently_featured_videos

get_on_the_web_videos

VIDEO FEED METHODS

get_video_by_id

search_video

get_related_for_video_id

get_comments_for_video_id

USER VIDEO FEED METHODS

get_user_video_by_id

get_user_videos

get_user_favorite_videos

add_favorite_video

get_recommended_videos

RATING METHODS

like_video

dislike_video

VIDEO RESPONSE METHODS

add_video_response

delete_video_response

FACTORY METHODS

video

comment

playlists

complaint

contact

message

USER PROFILE RELATED METHODS

get_user_profile

get_user_contacts

get_user_inbox

USER PLAYLIST METHODS

get_user_playlist_by_id

get_user_playlists

HANDLING ERRORS

TODO

DEPENDENCIES

BUGS AND LIMITATIONS

AUTHOR

LICENSE AND COPYRIGHT

Module Install Instructions