Audience

For YouTube Data API reference information, including expected latencies for data updates, please see the reference guide.

<http://code.google.com/intl/ja/apis/youtube/2.0/reference.html>

This document assumes that you understand the general ideas behind the Google Data APIs protocol, and that you know Perl.

For reference information about the Perl classes and methods, see the client library's API guide.

http://search.cpan.org/dist/WebService-GData/lib/WebService/GData/YouTube.pm

Document structure

The Authentication section describes the two different authentication methods available for associating API operations with a specific user account. This section also outlines the differences between authentication for the YouTube Data API and other Google Data APIs. Throughout this document, the explanations of specific API functions will clearly indicate whether the function requires user authentication. In general, all requests that modify video or feed data need to be authenticated. Read-only requests to retrieve public videos do not require authentication.

The "Understanding video feeds and entries" section provides a sample API response and explains how to extract information about a single video from a list of videos or a set of search results. This section also explains how to access metadata about a specific video entry.

The "Retrieving and searching for videos" section explains how to fetch a list of videos. The YouTube Data API defines several types of standard feeds, such as top-rated or most-viewed videos. This section explains how also to retrieve a list of videos uploaded by a specific user or a list of related videos. Finally, this section explains how to use the API to let users search through YouTube's video library for videos matching specific search terms or categories.

The "Uploading videos" section briefly explains two ways that you can allow users to upload videos to YouTube from your application. This section also explains how to let users delete videos from your application. These solutions are explained in more detail in the Protocol Guide. You may need to let users upload videos to use certain other API functions. For example, the API provides a function for adding a video response to a video. If the user is uploading a new video as a video response, then your client will need to follow the video uploading instructions to add the video to YouTube before identifying the new video as a response.

The "Updating and deleting videos" section describes how to use the API to update information about a YouTube video. It also describes how a video can be removed using the API.

The "Using community features" section describes API functions that allow your users to interact with YouTube videos. These functions explain requests for posting a rating, comment, video response or complaint to an existing video. You can also use the API to retrieve lists of video comments or video responses or to delete a video response.

The "Saving and collecting videos" section explains how to use the API to access, create and update favorite videos, video playlists and subscriptions to YouTube channels. It also explains how to modify video playlists and favorites by adding and removing videos.

The "Enabling user interaction" section explains how to use the API to retrieve and update user profiles. This section also explains how to retrieve, add, update and delete user contacts as well as how to retrieve, send and delete messages.

AuthSub for web applications

    NOT IMPLEMENTED AND WILL NOT BE (OAuth being favored).

OAuth for web applications

    NOT IMPLEMENTED YET.

ClientLogin for installed applications

To use ClientLogin authentication, instantiate a WebService::GData::ClientLogin by specifying the email and password of the user associated with the authentication request and then set it to the YouTube instance.

    Note: ClientLogin authentication should not be used in Web applications, which should use AuthSub/OAuth authentication instead.

The following code demonstrates how to use ClientLogin to authenticate a user. Note that your authentication request must specify a developer key to retrieve private feeds, upload videos, or submit API requests for write operations.

Please visit <http://code.google.com/apis/youtube/dashboard> to obtain a developer key.

    use WebService::GData::YouTube;
    use WebService::GData::ClientLogin;
    
    my $auth;

    eval {
        $auth = new WebService::GData::ClientLogin(
            email    => '...',
            password => '...',
            key      => '...'
        );
    };
    if(my $error = $@){
        #$error->code,$error->content...
    }
    
    my $yt = new WebService::GData::YouTube($auth);

Displaying a feed of videos

The following code retrieves a video feed and then prints information about each entry in the feed:

    my $videos = $yt->get_user_videos();#add a channel name if you are not logged in
    display_videos($videos);

    sub display_videos {
        my $videos = shift;
        foreach my $video ( @$videos ) {
            display_video($video);#implemented below in the documentation
        }
    }

The "Retrieving and searching for videos" section describes different types of video feeds and provides the URLs and instructions for retrieving those feeds.

Retrieving a specific video entry

This tag identifies the URL for a feed of information about that particular video. The URL has the following format:

    http://gdata.youtube.com/feeds/api/videos/videoID

The following code retrieves a WebService::GData::YouTube::Feed::Video object, which corresponds to a particular YouTube video, and then prints the metadata for the video:

    my $video = $yt->get_video_by_id('video_id_goes_here');
    display_video($video);#implemented below in the documentation

Video entry contents

The following code demonstrates how to print a variety of details about a video. Many important data fields for a Video object are specified by the children of the <media:group> element. The client library contains many helper methods that facilitate easy access to the child elements of mediaGroup and that can be called directly from the Video object. For a complete list of all of the information that a Video object contains, please refer to the <entry> tag definition in the API Reference Guide. Specifically, refer to the <entry> tag's subtags for retrieving a video entry.

<http://code.google.com/intl/ja/apis/youtube/2.0/reference.html#youtube_data_api_tag_entry>

    sub display_video {
        my $video  = shift;
           say 'Video Id:',$video->video_id;
           say 'Title:',$video->title;
           say 'Description:',$video->description;
           say 'Updated:',$video->updated;
           say 'Published:',$video->published;
           say 'Uploaded:',$video->uploaded; 
           say 'Favorite Count:',$video->favorite_count;
           say 'View Count:',$video->view_count;
           say 'Duration:',$video->duration; 
           say 'Keywords:',$video->keywords;
           say 'Author Name:',$video->author->[0]->name;
           say 'Author Uri:',$video->author->[0]->uri;
           say 'Geo Location:',$video->location;
           say 'Denied Countries:',$video->denied_countries;
           say 'Media Player URL:',$video->media_player;
           say 'Is Private:',$video->is_private;
           
           #content
           say $video->content->type('flash')->[0]->url;#retrieve the flash application url
           say $video->content->format(1)->[0]->url;#3gpp rtsp
           #loop over it:
           my $contents = $video->content;
           foreach my $content (@$contents){
                say $content->url;
                say $content->type;
                say $content->duration;
                say $thumb->format;          
           }
           
           say $video->rating->num_dislikes;
           say $video->rating->num_likes;
           my $thumbs =$video->thumbnails;
           foreach my $thumb (@$thumbs) {
                say $thumb->url;
                say $thumb->time;
                say $thumb->width;
                say $thumb->height;
           }
    }
    
    Note: For more information about how to generate the information required to embed a video with a player 
    in your page please refer to the protocol guide.
    http://code.google.com/intl/en/apis/youtube/2.0/developers_guide_protocol_displaying_video_information.html

Determining whether a user can edit a video entry

You can determine whether the currently authenticated user is the owner of a particular video entry by calling the is_read_only method on that entry. The sample code below demonstrates how to determine whether a video entry is editable.

    if(!$video->is_read_only) {
        say 'Video can be edited by current user.';
    }

Retrieving standard feeds

The URLs for all standard feeds have the following format:

http://gdata.youtube.com/feeds/api/standardfeeds/FEED_IDENTIFIER

The following lists the standard feeds available through the YouTube Data API.

     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

You can also retrieve region-specific standard feeds and category-specific standard feeds by specifying either a regionID, a category name, or both in the feed URL. The URL for a region- and category-specific standard feed has the following format:

    http://gdata.youtube.com/feeds/api/standardfeeds/localeID/feedID_CATEGORY_NAME

For example, the following shows the feed URL for a list of the top-rated comedies in Japan:

http://gdata.youtube.com/feeds/api/standardfeeds/JP/top_rated_Comedy

Please refer to the reference guide for more information about standard feeds, region-specific standard feeds and category-specific standard feeds.

The following example demonstrates how to retrieve a standard feed and print information about the videos in that feed.

Note that you do not need to be authenticated to retrieve standard feeds.

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

        my $videos = $yt->get_recently_featured_videos();
  
        foreach my $video (@$videos){
            display_video($video);
        }

        #adding some constraints on the returned data
        $videos = $yt->get_top_rated_videos('JP');#top rated videos in Japan
        $videos = $yt->get_top_rated_videos('JP','Comedy');#top rated videos in Japanese Comedy 
        $videos = $yt->get_top_rated_videos('JP','Comedy','today');#top rated videos of the day in Japanese Comedy 
    }

Videos uploaded by a specific user

The video feed for a user's uploaded videos can be retrieved from the following URL:

http://gdata.youtube.com/feeds/api/users/username/uploads

The following code demonstrates how to retrieve a feed of videos uploaded by a particular user:

    my $videos = get_user_videos('channel_name');
    foreach my $video (@$videos){
        display_video($video);    
    }

    sub get_user_videos {     
        my $channel = shift;
        my $yt = new WebService::GData::YouTube();
        return $yt->get_user_videos($channel);
    }

Note: In the feed URL, you can substitute the string default instead of a username to retrieve the videos uploaded by the currently authenticated user. In this case, you would retrieve the feed located at http://gdata.youtube.com/feeds/api/users/default/uploads. In such a case, you must pass an authentication object to the YouTube constructor and there is no need to set a channel.

Retrieving related videos

The following code shows how to retrieve and print information about the related videos for a particular video.

    my $videos = $yt->get_related_for_video_id($video->video_id);
    foreach my $video (@$videos) {
        display_video($video);
    }

Searching for videos

Searching for videos using developer tags

NOT IMPLEMENTED YET.

Direct upload

Browser-based upload

Resumable uploads

Checking upload status

Updating video information

Deleting a video

Adding a rating

Comments

Adding a comment

Video Responses

Adding a video response

Deleting a video response

Flagging a video

Favorite videos

Adding a favorite video

Deleting a favorite video

Playlists

Retrieving playlist information

The playlist related write methods below are not implemented yet.

Adding a playlist

Updating a playlist

Adding a video to a playlist

Editing information for a playlist video

Removing a video from a playlist

Deleting a playlist

Subscriptions

Retrieving a user's subscriptions

Adding a subscription

Deleting a subscription

Video Recommendations

Profiles

Contacts

Retrieving a user's contacts

Adding a contact

Accepting or rejecting a contact

Deleting a contact

Messages

Retrieving messages

Sending a message

Deleting a message

User activity feeds

Friend activity feeds