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;
#more specific:
my $videos = $yt->get_top_rated('JP','Comedy');
foreach my $video (@$videos) {
$video->video_id;
$video->title;
$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($myid);
}else {
if($video->is_listed_allowed){
$video->keywords($video->title.','.$video->keywords);
$video->save();
}
}
}
DESCRIPTION
inherits from WebService::GData;
This package is a point of entry giving access to general YouTube feeds you may want to access.
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::Playlist
-
This object inherits from WebService::GData::YouTube::Feed::Video.
The name may let you think that it is a playlist metadata information but it's not.
It contains a list of all the videos within this particular playlist.
The only difference with 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 then get the one you want to edit.
CONSTRUCTOR
new
Create a WebService::GData::YouTube instance.
Parameters:
auth:Scalar(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.
Return:
- 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. The query object will build the query string required to access the data. Most of the time you will not need it unless you want to do a particular query.
Parameters:
query:Object(Default : WebService::GData::YouTube::Query)
Return:
query:Object(Default : WebService::GData::YouTube::Query)-
or
void
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
Return:
base_query
Get the base query string used to query the data.
Parameters:
- none
Return:
STANDARD FEED METHODS
All the standard feed methods are implemented:
methods:
get_top_rated
get_top_favorites
get_most_viewed
get_most_popular
get_most_recent
get_most_discussed
get_most_responded
get_recently_featured
get_watch_on_mobile
This allows you to grab feeds from YouTube main categories (top_rated,most_viewed,...).
All the above standard feed methods accept the following optional parameters:
Parameters:
- <region_zone:Scalar> (ie,JP,US)
- <category:Scalar> (ie,Comedy,Sports...)
- <time:Scalar> (ie,today,this_week,this_month,all_time)
Return:
Throw:
Example:
use WebService::GData::YouTube;
my $yt = new WebService::GData::YouTube();
my $videos = $yt->get_top_rated();
my $videos = $yt->get_top_rated('JP');#top rated videos in Japan
my $videos = $yt->get_top_rated('JP','Comedy');#top rated videos in Japanese Comedy
my $videos = $yt->get_top_rated('JP','Comedy','today');#top rated videos of the day in Japanese Comedy See also:
See 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:
Return:
Throw:
Example:
use WebService::GData::YouTube;
my $yt = new WebService::GData::YouTube();
my $video = $yt->get_video_by_id($myvideoid);search_video
Search for videos responding to a particular query.
Parameters:
- none
Return:
Throw:
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
my $yt = new WebService::GData::YouTube();
#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);See also:
WebService::GData::YouTube::Query
get_related_for_video_id
Get the related videos for a video. These videos are returned by following YouTube own algorithm.
Parameters:
Return:
Throw:
USER VIDEO FEED METHODS
All these methods allow you to access the videos of the logged in user.
If not logged in,you should set the user name you want to access.
get_user_video_by_id
Get a video for the logged in user or for the user name you specified.
Parameters:
Return:
Throw:
get_user_favorite_videos
Parameters:
Return:
Throw:
get_user_videos
Get the videos for the logged in user or for the user name you specified.
Parameters:
Return:
Throw:
get_user_favorite_videos
Parameters:
Return:
Throw:
USER PLAYLIST METHODS
These methods allow you to access the videos in a playlist or a list of the playlists for a certain user.
If you are not logged in,you must set the user name.
get_user_playlist_by_id
Retrieve the videos in a playlist by passing the playlist id.
Parameters:
Return:
- 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.
Throw:
get_user_playlists
Get the playlists metadata for the logged in user or the user set as a parameter.
Parameters:
Return:
- 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.
Throw:
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 = 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 {
my $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:
- Partial Upload
- Channel search
- Playlist search
- Check the query parameters
- Partial feed read/write
- know the status of a video
Certainly missing other stuffs...
CONFIGURATION AND ENVIRONMENT
none
DEPENDENCIES
INCOMPATIBILITIES
none
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.