Developer's Guide: Data API Protocol

The YouTube Data API allows applications to perform functions normally executed on the YouTube website. The API enables your application to search for YouTube videos and to retrieve standard video feeds, comments and video responses. In addition, the API lets your application upload videos to YouTube or update existing videos. Your can also retrieve playlists, subscriptions, user profiles and more. Finally, your application can submit authenticated requests to enable users to create playlists, subscriptions, contacts and other account-specific entities.

Contents

Audience

This document is intended for programmers who are writing client applications that interact with YouTube. The document provides examples of basic API operations using raw HTTP and XML. Java and PHP developers may prefer to read the language-specific developer guides that explain how to use the Java or PHP client libraries to perform similar functions.

This document assumes that you understand the general principles behind the Google Data APIs protocol. Google Data APIs provide a simple, standard protocol for reading and writing data on the web. Google Data APIs are based on the Atom 1.0 and RSS 2.0 syndication formats as well as the Atom Publishing Protocol.

About this document

This document contains the following sections:

• 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.

• 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 illustrates how the XML elements in a YouTube Data API response correspond to the video information typically displayed on YouTube's website. This section also explains the API request format for updating an individual 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 also explains how also to retrieve a list of videos uploaded by a specific user or a list of related videos, which are videos that YouTube has determined are similar to a particular video. 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 presents process flow diagrams for each upload method and explains how those methods work in conjunction with the authentication scheme that you are using.

  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. However, 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 to an existing video.

• The Updating and deleting videos section explains how to enable a user to update or delete his videos.

• 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.

• 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.

Authentication

Authentication allows a user to access YouTube features that link content or information to a particular YouTube account. These features require the user or your application to provide the YouTube username and password for that account. For example, a user must log in to YouTube to upload a video or to add a comment to an existing video.

This document describes a number of API functions that require user authentication, including all of the API functions for creating, updating or deleting content require user authentication.

Please note that if you implement any functionality that does require authentication, we recommend that you include the proper authentication headers in all of your requests even if those requests do not explicitly require authentication.

To properly authenticate, a request must include the X-GData-Key and Authorization headers. The X-GData-Key header specifies your developer key, a value that uniquely identifies your application(s). The Authorization header specifies a token that you obtain for each user using one of two authentication schemes, AuthSub or ClientLogin, that are available to enable users to access account-specific YouTube features. The following list will help you to select the authentication scheme that is appropriate for your application.

• AuthSub proxy authentication enables web applications to authenticate users to their YouTube accounts without having to access the user's YouTube username and password. You should use AuthSub authentication if you are building a web application that will let users link videos, comments, ratings, contacts or other information to their own YouTube accounts.

• ClientLogin authentication lets you associate all API actions with a single YouTube account. You should use ClientLogin if you are building a standalone, single-user, installed client, such as a desktop application. In this case, your application will ask the user to enter his YouTube username and password and will then use those values to request a ClientLogin authentication token.

  Note: You should never build a web application that implements ClientLogin authentication and requires users to enter their usernames and passwords. If you are building a web application that allows people to associate actions with their YouTube accounts, use AuthSub authentication.

Using a developer key and client ID

A developer key identifies the YouTube developer that is submitting an API request. A client ID identifies your application for logging and debugging purposes. Please visit http://code.google.com/apis/youtube/dashboard/ to obtain a developer key and client ID.

When you make an API request, use the X-GData-Key request header to specify your developer key and the X-GData-Client header to specify your client ID as shown in the following example:

X-GData-Client: <client_id>
X-GData-Key: key=<developer_key>

AuthSub for web applications

The AuthSub process is documented in more detail at http://code.google.com/apis/accounts/AuthForWebApps.html. In addition, please note that the base URL and scope of service for YouTube AuthSub authentication – http://gdata.youtube.com – are different than the URL and scope specified in the AuthSub documentation available online.

To obtain an authentication token, submit an HTTP POST request to the following URL:

https://www.google.com/accounts/AuthSubRequest?
      next=http%3A%2F%2Fwww.example.com%2Fupload.html
      &scope=http%3A%2F%2Fgdata.youtube.com
      &session=0
      &secure=0

The POST request contains the following parameters:

• The next parameter contains the URL to which the user will be redirected after logging in to YouTube.

• The scope parameter identifies the service that the user is enabling your site to access on his behalf. The value of this parameter must be http://gdata.youtube.com.

• The secure parameter contains a boolean value (0 or 1) that indicates whether the authentication service will return a secure or nonsecure token. Secure tokens are issued only to websites that have registered with Google, and Upload API requests that use a secure token must be digitally signed. Please see the Google AuthSub documentation for more details about secure tokens.

• The session parameter contains a boolean value (0 or 1) that indicates whether the single-use authentication token that the authentication service returns can be exchanged for a session token, which can be used multiple times. Set this variable to 1 to indicate that the single-use token can be exchanged for a session token. Please see the Google AuthSub documentation for an explanation of how to request a session token.

After the user logs in via YouTube's authentication service, YouTube will redirect the user back to the URL identified in the next parameter in your AuthSub request. The redirect contains a single-use authentication token, which is identified by the token parameter in the URL as shown in the following example. If the value of the session parameter in your AuthSub request was 1, then you can exchange the single-use token for a session token by submitting an AuthSubSessionToken request.

The following URL shows how the token parameter will appear in the redirect to your site. Note that the URL for the redirect would have been provided as the value of the next parameter in the AuthSub request.

http://www.example.com/upload.html?token=CKF50YzIHxCT85KMAg

When you make an authenticated API request using an AuthSub authentication token, your request needs to specify the Authorization HTTP request header as shown in the example below. Note: In this document, sample requests use AuthSub syntax unless otherwise specified.

Authorization: AuthSub token=<authentication_token>
X-GData-Key: key=<developer_key>

ClientLogin for installed applications

To make an authenticated API request using ClientLogin, you must identify the YouTube user account associated with the request. You must also use YouTube's ClientLogin system for single-user authentication. You will provide the username and password for the user's YouTube user account, verifying that the user is authorized to perform operations associated with that account. The authenticated actions will then be associated with that account. Please note that the following instructions vary slightly from the standard ClientLogin instructions.

To obtain an authentication token, submit an HTTP POST request to the following URL:

https://www.google.com/youtube/accounts/ClientLogin

The following guidelines apply to the request:

• The POST request must specify the value application/x-www-form-urlencoded for the Content-Type header.

• The POST body must include a string in the following format:

  Email=<youtube_username>&Passwd=<youtube_password>
    &service=youtube&source=<source>
  

  You need to make the following changes to this string:

  • Replace the string <youtube_username> with the user's YouTube account username.

  • Replace the string <youtube_password> with the user's YouTube account password.

  • Replace the string <source> with a short string that identifies your application for logging purposes.

• The <youtube_username>, <youtube_password> and <source> values must all be URL-encoded.

Google will return a response that contains the authentication token that you will need to execute API operations associated with the specified user's YouTube account. The authentication token will be the Auth value on that page. In addition, the YouTubeUser value on the page will be the user's YouTube account username. You must extract the authentication token and username from the page and then submit those values in API requests. Please note that authentication tokens expire periodically. As such, your application may need to repeat this authentication process and update the value of the authentication token when the token is rejected as expired.

Note: The Google ClientLogin documentation explains how to also incorporate a CAPTCHA challenge into an application using ClientLogin authentication.

Authentication Example

For example, suppose you want to authenticate a YouTube account for which the username and password are testuser and testpassword, respectively. You can simulate the HTTP POST request using the Linux 'curl' command, as shown in the following example:

curl \
  --location https://www.google.com/youtube/accounts/ClientLogin \
  --data 'Email=testuser&Passwd=testpw&service=yt&source=Test' \
  --header 'Content-Type:application/x-www-form-urlencoded'

If your authentication request is successful, the response to your request will have the following format. (Please note that the Auth token value has been shortened in the example.)

Auth=AIwbFARksypDdUSGGYRI_5v7Z9TaijoPQqpIfCEjTFPAikn_---OC-I1VJtQ
YouTubeUser=testuser

When you make an authenticated API request using a ClientLogin authentication token, your request needs to specify the Authorization HTTP request header as shown in the example below:

Authorization: GoogleLogin auth=<authentication_token>
X-GData-Key: key=<developer_key>

Understanding video feeds and entries

When you retrieve a video feed or list of search results, YouTube returns an Atom feed that contains one <entry> tag for each video in the result set. The root XML tag in the response will be the <feed> tag. In addition to the information about the individual videos in the result set, the feed will also contain the total number of results in the list, the index of the first item in the list, the number of items in the list and other metadata about the feed.

The following XML shows the format of a YouTube Data API response containing a video feed:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
         xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'
         xmlns:gml='http://www.opengis.net/gml'
         xmlns:georss='http://www.georss.org/georss'
         xmlns:media='http://search.yahoo.com/mrss/'
         xmlns:yt='http://gdata.youtube.com/schemas/2007'
         xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://gdata.youtube.com/feeds/api/standardfeeds/top_rated</id>
  <updated>2008-02-21T18:57:10.801Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#video'/>
  <title type='text'>Top Rated</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='alternate' type='text/html'
    href='http://www.youtube.com/browser?s=tr'/>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?...'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?...'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='beta'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>99</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry>
    <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b</id>
    <published>2007-02-16T20:22:57.000Z</published>
    <updated>2007-02-16T20:22:57.000Z</updated>
    <category scheme="http://schemas.google.com/g/2005#kind"
      term="http://gdata.youtube.com/schemas/2007#video"/>
    <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat"
      term="Steventon"/>
    <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat"
      term="walk"/>
    <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat"
      term="Darcy"/>
    <category scheme="http://gdata.youtube.com/schemas/2007/categories.cat"
      term="Entertainment" label="Entertainment"/>
    <title type="text">My walk with Mr. Darcy</title>
    <content type="html"><div ... html content trimmed ...></content>
    <link rel="self" type="application/atom+xml"
      href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b"/>
    <link rel="alternate" type="text/html"
      href="http://www.youtube.com/watch?v=ZTUVgYoeN_b"/>
    <link rel="http://gdata.youtube.com/schemas/2007#video.responses"
      type="application/atom+xml"
      href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses"/>
    <link rel="http://gdata.youtube.com/schemas/2007#video.ratings"
      type="application/atom+xml"
      href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/ratings"/>
    <link rel="http://gdata.youtube.com/schemas/2007#video.complaints"
      type="application/atom+xml"
      href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/complaints"/>
    <link rel="http://gdata.youtube.com/schemas/2007#video.related"
      type="application/atom+xml"
      href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/>

    <author>
      <name>Andy Samplo</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>

  <media:group>

    <media:title type="plain">Shopping for Coats</media:title>
    <media:description type="plain">
      What could make for more exciting video?
    </media:description>
    <media:keywords>Shopping, parkas</media:keywords>
    <yt:duration seconds="79"/>
    <media:category label="People"
      scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People
    </media:category>
    <media:content
      url='http://www.youtube.com/v/ZTUVgYoeN_b'
      type='application/x-shockwave-flash' medium='video' 
      isDefault='true' expression="full" duration='215' yt:format="5"/>
    <media:content
      url='rtsp://rtsp2.youtube.com/ChoLENy73bIAEQ1k30OPEgGDA==/0/0/0/video.3gp'
      type='video/3gpp' medium='video' 
      expression="full" duration='215' yt:format="1"/>
    <media:content
      url='rtsp://rtsp2.youtube.com/ChoLENy73bIAEQ1k30OPEgGDA==/0/0/0/video.3gp'
      type='video/3gpp' medium='video' 
      expression="full" duration='215' yt:format="6"/>
    <media:player url="http://www.youtube.com/watch?v=ZTUVgYoeN_b"/>
    <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/2.jpg"
      height="97" width="130" time="00:00:03.500"/>
    <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/1.jpg"
      height="97" width="130" time="00:00:01.750"/>
    <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/3.jpg"
      height="97" width="130" time="00:00:05.250"/>
    <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/0.jpg"
      height="240" width="320" time="00:00:03.500"/>
  </media:group>

  <yt:statistics viewCount="93"/>
  <gd:rating min='1' max='5' numRaters='435' average='4.94'/>

  <gd:comments>
    <gd:feedLink
      href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments"
      countHint='2197'/>
  </gd:comments>

</entry>

Displaying a list of videos

The following screenshot demonstrates how YouTube displays information in a video list. The screenshot is annotated, and the list following the screenshot explains how the display elements correspond to the information in an API response.

The screenshot displays the following information:

1. This element displays a title for the result set. In your application, this value could be the value of the <title> tag or you can select other text appropriate to the requested feed or search result set.

2. In the image, the text 1-20 of about 13,800 uses the following elements from the API response:

   • The value "1" equals the value of the <openSearch:startIndex> tag.
   • The value "20" can be calculated by adding the value of the <openSearch:startIndex> tag to the value of the <openSearch:itemsPerPage> tag and then subtracting one. For example, if the <openSearch:startIndex> value is 26 and the <openSearch:itemsPerPage> value is 25, then the result set will display items 26-50 – 50 = (26 + 25) - 1.
   • The value "13,800" equals the value of the <openSearch:totalResults> tag. Please note that the value of this tag is an approximation of the total number of results and not necessarily an exact figure.

3. The pulldown menus allow the user to select values for the orderby and time parameters. The Reference Guide provides a complete list of the query parameters that the YouTube Data API supports and explains the types of queries for which each parameter applies.

4. This element displays a thumbnail image of the video. YouTube API responses may contain multiple thumbnail images for a video, each of which is identified by a <media:thumbnail> tag. On the YouTube website, the thumbnail image links to a page that displays more information about the video, including comments and video responses, and also allows the user to watch the video. In a video entry, the <link> tag that has a rel attribute value of alternate identifies the URL for the YouTube page where the user could watch the video. On YouTube search result pages, thumbnail images link to that URL.

   To obtain information to display the target page in your application, you would submit an HTTP request to the edit URL for the video entry. The following section, Identifying feeds related to a video entry explains how to identify the edit URL in an entry.

5. The title next to the video is the value of the <media:title> tag for that video. The text below the title is the value of the <media:description> tag.

6. The right column displays the following values:

   • The first line displays text corresponding to the value of the <published> tag for the video. Note that the <published> tag contains a timestamp that could be converted into text to approximate the age of the video as shown in the screenshot -- e.g. added 5 months ago. However, you could also display a date -- e.g. 10/22/07 or Oct. 22 2007.

   • The second line identifies the YouTube username for the video's owner. This value is specified by the <name> tag encapsulated within the <author> tag for the video entry. On YouTube's website, this link directs the user to a page that displays the video owner's profile information. To retrieve this information on your site, you would submit a subsequent request to the value of the <uri> tag encapsulated within the <author> tag for the video entry.

   • The third line specifies the number of times the video has been viewed. The <yt:statistics> tag's viewCount attribute specifies this value.

   • The fourth line provides the average user rating for the video. The <gd:rating> tag's average attribute provides this rating. Note that on YouTube, the rating is adjusted to determine the proper star image to display. For example, ratings between 2.75 and 3.2499 display a three-star rating, while ratings between 3.25 and 3.7499 display a 3.5 rating.

   • The fifth line displays the length of the video. The <yt:duration> tag provides the length of the video in seconds. In the screenshot, the value has been adjusted to display in minutes and seconds (292 seconds = 04:52).

   • The sixth line displays the name of the category that describes the video. This value is contained in the <media:category> tag's label attribute. On YouTube's website, the category name also links to a page that displays more videos in that category. The Browsing with Categories and Keywords section explains how to request videos that are in a particular category.

To retrieve a feed about a single video in the result set, you would submit an HTTP GET request to the edit URL for that entry, as explained in the following section. For example, you might issue this request when a user linked from a set of search results to watch a particular video in the search result set.

Identifying feeds related to a feed entry

Each entry in a YouTube Data API response identifies several API URLs related to the video. For example, the entry identifies URLs that let you request comments for the video, video responses for the video or the video owner's YouTube public user profile. Some URLs may be used not only for retrieving information but also for creating, updating or deleting information. For example, you send an HTTP GET request to a URL to retrieve comments for that video and an HTTP POST request to the same URL to add a comment to that video.

Several API functions in this document refer to the edit URL for a video or other type of entry. (In a playlists feed, for example, an entry corresponds to a playlist rather than to a video.) Within a feed <entry>, the edit URL is the value of the href attribute in the <link> tag that has a rel attribute value of edit.

The following XML sample demonstrates how <link> tags appear in a YouTube Data API response. The edit URL in the example is shown in bold text.

<entry>
  <id>http://gdata.youtube.com/feeds/api/videos/dMH0bHeiRN</id>
  <link rel='http://gdata.youtube.com/schemas/2007#video.responses'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/responses'/>
  <link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/ratings'/>
  <link rel='http://gdata.youtube.com/schemas/2007#video.complaints'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/complaints'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/dmH0bHeiRN/uploads'/>
  <link rel='edit' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/dmH0bHeiRN/uploads'/> 
  ...
</entry>

The Using community features, Saving and collecting videos and Enabling user interaction sections of this document all present use cases describing situations when you might use a particular function to request, create, update or delete resources using the YouTube API. Each use case explains the API requests that you would send as well as the values that you would need to parse from the API responses to allow a user to progress through the use case. Frequently, these steps require you to send an API request to a URL identified within a <link> tag in an API response. The use cases identify the URLs for API requests using the value of the <link> tag's rel attribute.

For example, to retrieve a list of video responses for a video, you would send an HTTP GET request to the URL associated with the <link> tag with the rel attribute value http://gdata.youtube.com/schemas/2007#video.responses. To add a rating to a video, you would send an HTTP POST request to the URL associated with the <link> tag with the rel attribute value http://gdata.youtube.com/schemas/2007#video.ratings.

Displaying information about a video

The following screenshot demonstrates how YouTube displays information about a single video. Whereas the screenshot that displays the list of videos only displays information from a single API request, this page synthesizes several API responses into a single page.

The screenshot is annotated, and the list following the screenshot explains how the display elements correspond to the API responses that contain the content.

Note that to display this page, you would first retrieve the feed for the video entry. The XML in a video entry feed is identical to the content that appears for that video in a feed or search result set.

The screenshot displays the following information:

1. Section 1 displays the title of the video. In an API response, the <media:title> tag contains the video's title.

2. Section 2 displays the video itself. You can use the following code snippet to display a YouTube video on your own page. Please note that you must replace the MEDIA_CONTENT_URL and MEDIA_CONTENT_TYPE variables with the appropriate values from the XML feed:

   • To play a video on a web page, replace the MEDIA_CONTENT_URL variable with the url attribute value of the <media:content> tag for which the yt:format attribute value is 5. Also, replace the MEDIA_CONTENT_TYPE variable with the type attribute value from the same <media:content> tag.

   • To play a video on a mobile device, select the appropriate <media:content> tag values based on the value of the yt:format attribute. Replace the MEDIA_CONTENT_URL variable with the url attribute value from that tag. Also, replace the the MEDIA_CONTENT_URL variable with the url attribute value from the tag.

   <object width="425" height="350">
     <param name="movie" value="MEDIA_CONTENT_URL"></param>
     <embed src="MEDIA_CONTENT_URL" 
       type="MEDIA_CONTENT_TYPE" width="425" height="350">
     </embed>
   </object>
   

3. Section 3 displays a variety of action buttons as well as statistics about the video:

   • Action buttons

     • The Share button on YouTube's website displays an inline form that allows a user to send a message to a contact or any other email address. To duplicate this implementation of the Share button, you would need to provide a form that retrieves and displays the contacts for the logged-in user and then allows the user to select contacts to whom to send a message. When the user submits the message, your application would need to submit one API request for each message recipient.

       

     • The Favorite button adds the video to the logged-in user's list of favorite videos. Learn more about adding a favorite video.

     • The Add to Playlists button toggles an inline form that displays a pulldown menu listing the logged-in user's playlists as well as an option to create a new playlist. If the user selects an existing playlist, the video is added to that playlist. If the user chooses to add a new playlist, the form directs the user to another form for adding a playlist. After submitting information about the new playlist, YouTube also adds the video to the playlist.

       To duplicate this functionality, your application would need to send an additional API request to retrieve a list of the user's playlists. If the user selected an existing playlist, your application would add the video to that playlist. If the user elected to create a new playlist, your application would collect the new playlist information, add the playlist and then add the video to the playlist.

     • The Flag button displays an inline form that allows a user to add a complaint about a video. On YouTube's site, the form displays select menus that are used to generate the value of the <yt:description> tag in the API request for adding the complaint. Your application could display similar pulldown menus or could display a text box allowing the user to enter a complaint.

   • Statistics

     • The star rating is a rounded figure that is based on the <gd:rating> tag's average attribute while the number of ratings is specified by the numRaters attribute on the same tag.
     • The number of views is provided in the <yt:statistics> tag's viewCount attribute.
     • The number of comments is specified in the <gd:feedLink> tag's countHint attribute.
     • The remaining statistics in this section are not provided in API responses.

4. Section 4 displays a list of comments and video responses for the video. (In the example, there are no video responses for the video.) This section displays the following elements:

   • Above the list of comments, the link to post a video response directs the user to a form that allows him to select a previously uploaded video or to upload a new video as a video response.

     To allow the user to select a previously uploaded video, the application retrieves a feed of the videos uploaded by that user. Once the user selected a video, your application would add the video as a video response.

     If the user chooses to upload a new video, your application will need to support either the browser-based uploading or direct uploading method for adding new videos to YouTube. After the user uploads the new video using one of those two methods, your application would retrieve the new video's ID and subsequently add the video as a video response.

   • The second link above the list of comments allows the user to post a text comment. The link toggles an inline form where the user can enter the comment. To provide this functionality, your application would need to send an API request to add the comment after the user submitted the form.

   • To display the list of comments, your application would need to send an additional API request to retrieve the comments feed for the video.

5. Section 5 displays additional information about the video and the person who uploaded the video:

   • To retrieve additional information about the video owner, such as the number of videos that person had uploaded, you would need to send an additional API request to retrieve the owner's profile. A profile feed contains a number of <gd:feedLink> tags that correspond to the something about the user, such as the user's favorite videos, subscriptions or uploaded videos. The countHint attribute of the <gd:feedLink> tag indicates how many favorite videos, subscriptions or uploaded videos the user has.

   • The Subscribe button next to the video owner's name allows a user to subscribe to the video owner's channel, which contains all videos uploaded by the video owner. To duplicate the functionality of the Subscribe button in your application, you would need to send an API request to add a subscription when a user clicks the button.

   • The About This Video part of the box contains additional information about the video. You could use the content in the <media:description>, <media:keywords>, <yt:duration> or other tags to provide more information about a video.

6. Section 6 displays more videos uploaded by the video owner. Learn how to retrieve videos uploaded by a specific user.

7. Section 7 displays a list of videos that YouTube considers similar to the video featured on the page. The related videos feed allows you to retrieve this list using the API.

Retrieving and searching for videos

Standard video feeds

This section explains how to retrieve standard YouTube feeds. Standard feeds contain lists of videos that either reflect YouTube user behavior, such as top-rated and most viewed video feeds, or were selected by YouTube staff, such as recently featured and mobile video feeds. Many of these feeds are shown on the Videos tab of the YouTube website. Standard feeds are updated every few minutes.

To retrieve a standard feed, send an HTTP GET request to the URL associated with that feed. The following table identifies the URL associated with each standard feed:

In addition, please note that many of these feeds support the time query parameter, which allows you to restrict the feed to only contain relevant results from the previous day, week or month. For example, to retrieve top-rated videos from the previous day, you would send an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?time=today

Note: The top_rated, top_favorites, most_viewed, most_discussed, most_linked and most_responded standard feeds support the time parameter.

Videos uploaded by a specific user

This section explains how to retrieve a feed containing all of the videos uploaded by a specific user:

• To request a feed of all videos uploaded by the currently logged-in user, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.

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

  Note: In the above URL, the value default in the GET URL signifies that you are requesting videos uploaded by the currently logged-in user. The user is identified by the authentication token that you submit with the request. The default value can be used to identify the currently logged-in user in a number of other API commands. For example, you can send an HTTP GET request to http://gdata.youtube.com/feeds/api/users/default/playlists to retrieve the currently logged-in user's playlists. You can also send an HTTP POST request to the same URL to create a new playlist in the currently logged-in user's account.

• To request a feed of all videos uploaded by another user, send an HTTP GET request to the following URL. Note that this request does not require authentication.

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

  In the URL above, you must replace the text username with the user's YouTube username. You can extract the username from the <name> tag in an API response as shown in the following example.

  <author>
    <name>andyland74</name>
    <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
  </author>
  

The API response for this query has exactly the same format as the sample response in the Understanding video feeds and entries section of this document.

Related videos

This section explains how to retrieve a feed containing a list of videos that are related to another video. YouTube algorithmically selects the set of related videos.

Each video entry in an API response contains a series of <link> tags. The <link> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007/#video.related identifies the URL for retrieving other videos related to that video entry. (The <link> tag's href attribute identifies the URL.)

<link rel="http://gdata.youtube.com/schemas/2007#video.related"
     type="application/atom+xml"
     href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/>

The API response for this query has exactly the same format as the sample response in the Understanding video feeds and entries section of this document.

Browsing with categories and keywords

This section explains how to retrieve a feed of all of the videos that are in a particular category or that are associated with a particular keyword. (YouTube uses the term "tag" to identify a keyword relevant to a video.) The examples also demonstrate how you can retrieve videos that are associated with a categories and one or more keywords as well as videos that are not associated with particular categories or keywords.

Each video entry in an API response contains a series of <category> elements. Each <category> element identifies a category or keyword with which the corresponding video is associated. The element's scheme attribute indicates whether the element identifies a category or a keyword. The element's term attribute specifies the category or keyword term that you would use to locate videos as described in this section.

To request a feed of all videos that are in a particular category or are associated with a particular keyword, send an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/videos/-/categories_or_keywords

In the URL above, you must replace the text categories_or_keywords with the specific categories or keywords for which you want to retrieve videos. The following example shows the URL that you would use to request videos in the "Comedy" category:

http://gdata.youtube.com/feeds/api/videos/-/Comedy

Note that the following conventions apply to the categories and keywords in your request:

• If your request specifies a category and one or more keywords or if your request does not specify a category but does specify multiple keywords, separate each individual category and keyword name with a forward slash. For example, you would use the following URL to request videos related to the keywords "bass" and "fishing":

  http://gdata.youtube.com/feeds/api/videos/-/bass/fishing

• Your request can use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several keywords or categories. For example, if you wanted to display videos related to "bass" and "music", the most effective search might be for videos associated with the keyword "bass" but not associated with the keywords "fish" or "fishing" as shown in the example below. (Searching for videos associated with the "Music" category and the keyword "bass" might exclude instructional videos about how to play bass.)

  http://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing

  The following example shows how to search for baseball videos that are in either the "Sports" or "Howto" categories. The category names are separated by the value "%7C", which represents a URL-encoded pipe (|) character specifying that the video must be associated with one of the two categories:

  http://gdata.youtube.com/feeds/api/videos/-/Sports%7CHowto/baseball

• Capitalize the names of categories and lowercase the names of keywords. For example, the following query identifies videos associated with the keyword "comedy" that are not in the "Comedy" category:

  http://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy

• If you are generating category or keyword searches automatically based on the information in an API response, specify the schema as part of the category name to clearly differentiate YouTube categories from keyword tags or developer tags. The following URLs demonstrate how to specify the schema in the category name. (Note that each URL should actually appear on one line but has been split into multiple lines for printing purposes.)

  Categories:
  http://gdata.youtube.com/feeds/api/videos/-/
    %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
    %2Fcategories.cat%7DNews
  
  Keywords:
  http://gdata.youtube.com/feeds/api/videos/-/
    %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
    %2Fkeywords.cat%7Ddog
  
  Developer tags:
  http://gdata.youtube.com/feeds/api/videos/-/
    %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
    %2Fdevelopertags.cat%7Dexample.com
  

• Always specify the schema, as explained in the previous item, if you are requesting videos associated with a particular developer tag.

Searching for videos

This section explains how to use the API to retrieve a list of videos matching a user-specified search term. To search for videos, submit an HTTP GET request to the following URL, appending the appropriate query parameters to your request:

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

The following example searches for the second set of 10 recently uploaded videos matching the query term "football" but not matching the query term "soccer":

http://gdata.youtube.com/feeds/api/videos?
    vq=football+-soccer
    &orderby=published
    &start-index=11
    &max-results=10

Search requests can include any of the following parameters. Commonly used parameters are listed first.

Name	Definition
vq	The vq parameter specifies a search query term. YouTube will search all video metadata for videos matching the term. Video metadata includes titles, keywords, descriptions, authors' usernames, and categories. Note that any spaces, quotes or other punctuation in the parameter value must be URL-escaped. To search for an exact phrase, enclose the phrase in quotation marks. For example, to search for videos matching the phrase "spy plane", set the vq parameter to %22spy+plane%22. Your request can also use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several search terms. For example, to search for videos matching either "boating" or "sailing", set the vq parameter to boating%7Csailing. (Note that the pipe character must be URL-escaped.) Similarly, to search for videos matching either "boating" or "sailing" but not "fishing", set the vq parameter to "boating&7Csailing+-fishing".
orderby	The orderby parameter specifies the value that will be used to sort videos in the search result set. Valid values for this parameter are relevance, published, viewCount and rating. In addition, you can request results that are most relevant to a specific language by setting the parameter value to relevance_lang_languageCode, where languageCode is an ISO 639-1 two-letter language code. (Use the values zh-Hans for simplified Chinese and zh-Hant for traditional Chinese.) In addition, please note that results in other languages will still be returned if they are highly relevant to the search query term. The default value is relevance.
start-index	The start-index parameter specifies the index of the first matching result that should be included in the result set. This parameter uses a one-based index, meaning the first result is 1, the second result is 2 and so forth. This parameter works in conjunction with the max-results parameter to determine which results to return. For example, to request the second set of 25 results – i.e. results 26-50 – set the start-index parameter to 26 and the max-results parameter to 25.
max-results	The max-results parameter specifies the maximum number of results that should be included in the result set. This parameter works in conjunction with the start-index parameter to determine which results to return. For example, to request the second set of 25 results – i.e. results 26-50 – set the max-results parameter to 25 and the start-index parameter to 26. The default value of this parameter is 25 and the maximum value is 50.
author	The author parameter restricts the search to videos uploaded by a particular YouTube user. The Videos uploaded by a specific user section discusses this parameter in more detail.
alt	The alt parameter specifies the format of the feed to be returned. Valid values for this parameter are atom, rss, json and json-in-script. The default value is atom and this document only explains the format of Atom responses. For more information about using API responses in JavaScript, please see Using JSON with Google Data APIs.
client	The client parameter is an alphanumeric string that identifies your application. The client parameter is an alternate way of specifying your client ID. You can also use the X-GData-Client request header to specify your client ID. Your application does not need to specify your client ID twice by using both the client parameter and the X-GData-Client request header, but it should provide your client ID using at least one of those two methods.
format	The format parameter specifies that videos must be available in a particular video format. Your request can specify any of the following formats: Value Video Format 1 RTSP streaming URL for mobile video playback. H.263 video (up to 176x144) and AMR audio. 5 HTTP URL to the embeddable player (SWF) for this video. This format is not available for a video that is not embeddable. Developers commonly add &format=5 to their queries to restrict results to videos that can be embedded on their sites. 6 RTSP streaming URL for mobile video playback. MPEG-4 SP video (up to 176x144) and AAC audio.
lr	The lr parameter restricts the search to videos that have a title, description or keywords in a specific language. Valid values for the lr parameter are ISO 639-1 two-letter language codes. You can also use the values zh-Hans for simplified Chinese and zh-Hant for traditional Chinese. This parameter can be used when requesting any video feeds other than standard feeds.
racy	The racy parameter allows a search result set to include restricted content as well as standard content. Valid values for this parameter are include and exclude. By default, restricted content is excluded. Feed entries for videos that contain restricted content will contain the <media:rating> element.
restriction	The restriction parameter identifies the IP address that should be used to filter videos that can only be played in specific countries. We recommend that you always use this parameter to specify the end user's IP address. (By default, the API filters out videos that cannot be played in the country from which you send API requests. This restriction is based on your client application's IP address.) To request videos playable from a specific computer, include the restriction parameter in your request and set the parameter value to the IP address of the computer where the videos will be played – e.g. restriction=255.255.255.255. To request videos that are playable in a specific country, include the restriction parameter in your request and set the parameter value to the ISO 3166 two-letter country code of the country where the videos will be played – e.g. restriction=DE.
time	The time parameter, which is only available for the top_rated and most_viewed standard feeds, restricts the search to videos uploaded within the specified time. Valid values for this parameter are today (1 day), this_week (7 days), this_month (1 month) and all_time. The default value for this parameter is all_time.

Note that search query parameters can also be appended to other types of feed requests. For example, you can retrieve videos uploaded by a specific user that also match a particular keyword.

Uploading videos

The YouTube Data API provides two methods for uploading videos to YouTube. A newly uploaded video will be included in a user's uploaded videos feed a few minutes after the upload completes and YouTube finishes processing the video. In addition, a newly uploaded video will typically be included in search results a couple of hours after the upload completes and YouTube finishes processing the video. However, this delay may be longer during periods of heavy API server loads.

• Direct uploading allows you to add videos that are in your video library to YouTube. You should choose a direct-upload implementation if you want to host or store videos uploaded through your site and also add those videos to YouTube. In a direct-uploading scenario, when a user uploads a video through your site, the video will be sent to your servers. Your application will subsequently send an API request to upload the video from your server to YouTube.

• Browser-based uploading allows you to accept video uploads from your users without having to handle, host or proxy the actual video files. You should choose a browser-based uploading process if you do not want to host or store the uploaded video files.

Note: The YouTube Data API will not allow you to upload additional videos to accounts that already contain 1000 or more videos.

In addition to choosing an uploading method, you must also choose the authentication scheme appropriate for your application. The following sections provide additional information about the video uploading process:

Process flow diagrams

This section provides process flow diagrams for the two authentication schemes and for the two upload methods. Depending on your application, you could combine either authentication scheme with either upload method.

AuthSub authentication

The following diagram illustrates the steps involved in authenticating a user using the AuthSub authentication scheme. AuthSub authentication can be used with either direct uploading or browser-based uploading.

The image shows the following steps:

1. The user clicks a link on your site to upload a video.

2. Your site redirects the user to YouTube's Authentication Proxy service.

3. The user's browser sends a request to the authentication service.

4. YouTube displays an Access Consent page, prompting the user to log in to his YouTube account.

5. The user logs in to his account, and YouTube then asks the user to grant or deny the ability for your site to upload the user's video details.

6. If the user grants access, YouTube redirects the user back to your site. The redirect URL contains the authentication token for your Upload API request.

7. The user's browser sends a request, including the authentication token, to your site. The Google AuthSub documentation explains the optional step of exchanging the single-use authentication token for a session token that does not expire.

ClientLogin authentication

The following diagram illustrates the steps involved in authenticating a user using the ClientLogin authentication scheme. Like AuthSub authentication, ClientLogin authentication can be used with either direct uploading or browser-based uploading.

The image shows the following steps:

1. The user clicks a link on your site to upload a video.

2. Your application presents a form for the user to enter a YouTube username and password.

3. The user submits his YouTube username and password to your installed application.

4. Your application sends a ClientLogin authentication request to YouTube to obtain an authentication token for uploading the video. The request specifies the username and password for the user's YouTube user account, which will be the account associated with the video.

5. YouTube verifies the user's username and password and returns the authentication token to your application. If you are using browser-based uploading, the token will allow you to upload the video metadata. If you are using direct uploading, the token will allow you to upload the metadata and the actual video file.

Browser-based upload

The following diagram illustrates the browser-based uploading process. Your application might have already completed the authentication process before these steps occur. However, you could also choose to have the user provide the video metadata before completing the authentication process.

The image shows the following steps:

1. Your site displays a form in which the user will enter details about the video being uploaded.

2. The user enters the video details, such as the title, description and category for the video.

3. Your site sends an HTTP POST request to YouTube that contains the authentication token and the video details that the user submitted in the previous step. The Uploading video metadata section explains how to submit video details to YouTube.

4. YouTube returns a one-time upload token, an encrypted value containing authentication information and video details for the video being uploaded. The Extracting values from the API response section identifies the upload token and URL in the API response.

5. Your site displays a form where the user can select his video file and upload it to YouTube. The form will submit directly to YouTube and must contain a hidden input field that specifies the upload token obtained in the previous step. The Uploading the video file section defines the guidelines for this form.

6. The user selects his video and submits the form, sending his video and the upload token directly to YouTube. YouTube verifies the token is valid and adds the video to the user's YouTube channel. During this process, YouTube assigns the video a unique ID, which will be used to identify the video on YouTube.

7. YouTube redirects the user back to your site.

Direct upload

The following diagram illustrates the direct uploading process. Your application might have already completed the authentication process before these steps occur. However, you could also choose to have the user provide the video metadata before completing the authentication process.

The image shows the following steps:

1. Your site displays a form in which the user will enter details about the video being uploaded and select the actual video file to upload.

2. The user selects the video file and enters the video details, such as the title, description and category for the video.

3. Your site sends an HTTP POST request to YouTube that contains the authentication token as well as the video file and the video details that the user submitted in the previous step. The Uploading video metadata section explains how to submit video files and video details to YouTube.

4. YouTube returns an API response describing the new video.

5. You display a confirmation to the user that the video was uploaded successfully.

Technical requirements for uploaded videos

You must be either the copyright holder or the authorized representative of the copyright owner for all video files that you deliver to YouTube. Similarly, users who upload videos to YouTube from your site must be either the copyright holder or the authorized representative of the copyright owner for all videos that they upload. We encourage you and your users to provide the highest quality video possible. YouTube's recommended video specifications can be found online in YouTube's Help Center and we recommend that you convey these guidelines to your users.

In addition to these guidelines, please note that video files must be 100 MB or smaller and that YouTube does not limit the duration of uploaded videos. You may compress video files using the .zip format. However, please note that the 100 MB size restriction applies to the uncompressed video file.

Assigning developer tags

When you upload a video, you can associate that video with one of YouTube's video categories. You can also associate the video with additional keywords, or developer tags, that you use to identify the video. By using developer tags, you can identify all of the videos uploaded through your website or even through specific areas of your website. YouTube will not display developer tags to YouTube users; however, you can retrieve or update videos that match a specific developer tag.

To associate developer tags with a video, include one <media:category> tag in your Upload API request for each developer tag. Set the value of the scheme attribute to http://gdata.youtube.com/schemas/2007/developertags.cat and the tag value to the keyword you want to associate with the video. The following XML shows a sample developer tag as it would appear in an Upload API request. (You would need to replace the string TagName with the actual keyword or label you wanted to associate with the video.)

<media:category
  scheme="http://gdata.youtube.com/schemas/2007/developertags.cat">TagName
</media:category>

In an API response, developer tags are specified in both <category> and <media:category> tags.

Note: Each developer tag that you assign will be associated with the developer key in your request. To search for videos matching that developer tag, your application would need to specify the same developer key in the search request.

Searching for videos that match a developer tag

To search for videos associated with a specific developer tag, send an API search request that specifies the developertags.cat category scheme and the developer tag that videos must match. The URLs below demonstrate how you would modify the standard API URL to match a developer tag. (You would need to replace the string TagName at the end of the URL with the name of your developer tag.)

Standard URL:
http://gdata.youtube.com/feeds/api/videos/

Retrieving videos associated with a developer tag:
http://gdata.youtube.com/feeds/api/videos/-/
  %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
    %2Fdevelopertags.cat%7DTagName

Note: When you search for videos that match a developer tag, your request must specify the same developer key that you used to assign that developer tag.

Browser-based uploading

Step 1 - Uploading video metadata

The example below shows the format of an API request that uses the AuthSub authentication scheme for browser-based uploading:

POST /action/GetUploadToken HTTP/1.1
Host: gdata.youtube.com
Authorization: AuthSub token=<authentication_token>
X-GData-Client: <client_id>
X-GData-Key: key=<developer_key>
Content-Length: <content_length>
Content-Type: application/atom+xml; charset=UTF-8

API_XML_request

Variables in the upload request

You must provide several values in the HTTP POST request. Those values are highlighted in bold text in the example above. The following list explains how to populate each of these values:

• authentication_token - This value contains the authentication token for your request. The token will either be a ClientLogin token, a single-use AuthSub token or a session AuthSub token.

• client_id - (optional) This value identifies the application making the API request. This value is used for logging and debugging. Please visit http://code.google.com/apis/youtube/dashboard/ to get a client ID.

• developer_key - This value identifies the YouTube developer that is submitting the request to upload the video. Please visit http://code.google.com/apis/youtube/dashboard/ to get a developer key.

• content_length - This value contains the length, in bytes, of the entire body of the HTTP POST request.

• API_XML_Request - This value contains information about the uploaded video file in the form of an Atom XML entry. The example below shows a sample XML request. The XML tags used in the entry are defined in the Reference Guide.

The following example shows an HTTP POST request that has all of these values populated with the exception of the binary file data.

POST /action/GetUploadToken HTTP/1.1
Host: gdata.youtube.com
Authorization: AuthSub token=DXAA...sdb8
X-GData-Client: b1c4t9sl2159
X-GData-Key: key=adf15ee97731bca89da876c...a8dc
Content-Length: 1941255
Content-Type: application/atom+xml; charset=UTF-8

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:media="http://search.yahoo.com/mrss/"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
  <media:group>
    <media:title type="plain">Bad Wedding Toast</media:title>
    <media:description type="plain">
      I gave a bad toast at my friend's wedding.
    </media:description>
    <media:category
      scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People
    </media:category>
    <media:keywords>toast, wedding</media:keywords>
  </media:group>
</entry>

Step 2 - Extracting values from the API response

When you submit an Upload API request, the API returns an XML response that contains an upload URL and upload token that enable the user to upload the actual video file. You will need to extract the URL and token from the response and include these values in the form on your web page where the user submits the video file.

The example below shows a sample API response to a request for browser-based uploading:

The following XML shows a sample Upload API response.

<?xml version='1.0' encoding='UTF-8'?>
<response>
  <url>http://uploads.gdata.youtube.com/action/FormUpload/AEF3087AUD<url>
  <token>AEwbFAQEvf3xox...</token>
</response>

Step 3 - Uploading the video file

After extracting the upload URL and upload token from the API response, you need to display a form so that the user can upload the actual video file. The form must use the upload URL as the value of the <form> tag's action attribute and contains a hidden input field containing the upload token.

The following HTML shows a sample form as it would appear on your site:

<form action="URL?nexturl=http%3A%2F%2Fwww.example.com method="post"
  enctype="multipart/form-data">
  <input type="file" name="file"/>
  <input type="hidden" name="token" value="TOKEN"/>
  <input type="submit" value="go" />
</form>

Please note that the form must follow these guidelines:

• You need to add the nexturl parameter to the form's target URL. This parameter specifies the URL to which YouTube will redirect the user's browser when the user uploads his video file. After the video is uploaded in the browser, the user will be redirected to the nexturl URL. See the reference guide for more information about additional parameters that will be appeneded to the URL.

• You must set the value of the <form> tag's enctype attribute to multipart/form-data.

• The <input> tag that identifies the file must be named file.

• The <input> tag that contains the token must be named token.

Direct uploading

Sending an Upload API Request

To upload a video, send an HTTP POST request containing the video and associated metadata to http://uploads.gdata.youtube.com/feeds/api/users/<youtube_username>/uploads. You need to replace the string <youtube_username> with the username for the content creator's YouTube account. You can replace the <youtube_username> string with the term default to upload a video to the currently logged-in user's account. The authentication token that you upload with the request identifies that user.

The Upload API request must have the following format:

POST /feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: AuthSub token=<authentication_token>
X-GData-Client: <client_id>
X-GData-Key: key=<developer_key>
Slug: <video_filename>
Content-Type: multipart/related; boundary="<boundary_string>"
Content-Length: <content_length>
Connection: close

--<boundary_string>
Content-Type: application/atom+xml; charset=UTF-8

API_XML_request
--<boundary_string>
Content-Type: <video_content_type>
Content-Transfer-Encoding: binary

<Binary File Data>
--<boundary_string>--

A request to upload a video using the ClientLogin authentication scheme has one syntactic difference from the example above. The Authorization header is formatted differently for a ClientLogin authentication token. The following example demonstrates how to properly format the Authorization request header for a ClientLogin authentication token:

Authorization: GoogleLogin auth=<authentication_token>

Note: The hostname for uploading a video via the API, uploads.gdata.youtube.com, is different than the hostname used for all other API functions. However, you can use the same authentication token for uploading as for other API functions.

Variables in the upload request

You must provide several values in the HTTP POST request. Those values are highlighted in bold text in the example above. The following list explains how to populate each of these values:

• youtube_username - Note that this variable is only relevant for requests that use ClientLogin authentication. This value contains the username for the user's YouTube account. The uploaded video will be associated with this account.

• authentication_token - This value contains the authentication token for your request. The token will either be a ClientLogin token, a single-use AuthSub token or a session AuthSub token.

• client_id - (optional) This value identifies the application making the API request. This value is used for logging and debugging. Please visit http://code.google.com/apis/youtube/dashboard/ to get a client ID.

• developer_key - This value identifies the YouTube developer that is submitting the request to upload the video. Please visit http://code.google.com/apis/youtube/dashboard/ to get a developer key.

• video_filename - This value contains the name of the video file that the content creator is uploading.

• boundary_string - This value contains a string of non-space characters. Typically, the string is a series of hyphens followed by a random set of alphanumeric characters. Note: This value appears multiple times in the HTTP POST request.

• content_length - This value contains the length, in bytes, of the entire body of the HTTP POST request.

• API_XML_Request - This value contains information about the uploaded video file in the form of an Atom XML entry. The example below shows a sample XML request. The XML tags used in the entry are defined in the Reference Guide.

• video_content_type - This value contains the MIME type of the uploaded video file. The MIME type needs to be either video/* (video/mpeg, video/mp4, etc.) or application/octet-stream.

• Binary File Data - This value contains the binary code for the video file that is being uploaded.

The following example shows an HTTP POST request that has all of these values populated with the exception of the binary file data.

POST /feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: AuthSub token=DXAA...sdb8
X-GData-Client: b1c4t9sl2159
X-GData-Key: key=adf15ee97731bca89da876c...a8dc
Slug: video-test.mp4
Content-Type: multipart/related; boundary="f93dcbA3"
Content-Length: 1941255
Connection: close

--f93dcbA3
Content-Type: application/atom+xml; charset=UTF-8

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:media="http://search.yahoo.com/mrss/"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
  <media:group>
    <media:title type="plain">Bad Wedding Toast</media:title>
    <media:description type="plain">
      I gave a bad toast at my friend's wedding.
    </media:description>
    <media:category
      scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People
    </media:category>
    <media:keywords>toast, wedding</media:keywords>
  </media:group>
</entry>
--f93dcbA3
Content-Type: video/mp4
Content-Transfer-Encoding: binary

<Binary File Data>
--f93dcbA3--

Handling the Upload API Response

When you submit an Upload API request, the API returns an Atom entry that contains information about the uploaded video. The entry has the same format as an entry that would appear in a user's uploaded videos feed. The response may contain properly escaped HTML tags.

The entry will contain one <link> tag for which the value of the rel attribute is self. To check the status of the uploaded video, submit an HTTP GET request to the URL identified in this <link> tag. See the following section, Checking the status of an uploaded video, for more information.

Checking the status of an uploaded video

An uploaded video will immediately be visible in an authenticated user's uploaded videos feed. However, the video will not be visible on YouTube until it has been processed and indexed. The length of time between when the video is uploaded and when the video is publicly visible on YouTube varies. However, videos are usually indexed within one day and may be indexed in several hours or even less than an hour.

The following list explains two ways to check the status of an uploaded video:

• You can check the status of a user's unpublished videos by retrieving the user's uploaded videos feed. Entries in that feed that have not been published will contain the <app:control> tag. Please note that unpublished videos include videos that are still being processed, that failed to upload or that were rejected after being uploaded.

• If you upload a video using the direct upload method, then the Upload API response will contain a <link> tag for which the value of the rel attribute is self. To check the status of the uploaded video, submit an HTTP GET request to the URL identified in this <link> tag.

  <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/username/uploads/Video_ID'/>

When you check the status of an uploaded video, the status information will be contained in the <app:control> tag and its subtags, <app:draft> and <yt:state>. The following XML excerpt shows how these tags appear in an entry in an API response:

<entry>
  <id>http://gdata.youtube.com/feeds/user/username/b5bbb2beb5a7d9ca</id>
  <app:control>
    <app:draft>yes</app:draft>
    <yt:state name='rejected' 
        reasonCode='tooLong'
        helpUrl='http://www.youtube.com/t/community_guidelines'>
        Video is too long.
    </yt:state>
  </app:control>
  <yt:private/>
</entry>

Note: We recommend that you check the value of the <yt:state> tag and communicate to video owners whether an unpublished video is still being processed or if an error caused the upload to fail or be rejected. The Java and PHP developer's guides both provide some sample code for checking the values of these tags.

Updating and deleting videos

Updating a video entry

To update a video, send an HTTP PUT request to the URL identified in the video entry's <link> tag where the rel attribute value is edit:

<link rel='edit' type='application/atom+xml'
   href='http://gdata.youtube.com/feeds/apis/users/andyland74/uploads/914IMX9RSTE'>

The body of the PUT request is an Atom XML entry that contains information about the video. You can include any of the following elements and their subtags in your request. Required elements are marked with an asterisk (*).

• media:title*
• media:description*
• media:category*
• media:keywords*
• yt:location
• yt:private
• yt:noembed
• georss:where

Note that excluding an element will delete the information that already exists for that video. For example, if a video is marked as private and your request does not include the <yt:private> tag, the video will become public.

The following XML shows a sample request to update a video:

PUT /feeds/api/users/USER_ID/uploads/VIDEO_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token=AUTHORIZATION_TOKEN
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:media="http://search.yahoo.com/mrss/"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
  <media:group>
    <media:title type="plain">Yippee Skippy</media:title>
    <media:description type="plain">I am updating this video.</media:description>
    <media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">People</media:category>
    <media:keywords>blastoff,rodeo,whiteboards</media:keywords>
  </media:group>
</entry>

Deleting a video

To delete a video, send an HTTP DELETE request to the edit URL for that video as shown in the following example:

DELETE /feeds/api/users/USER_ID/uploads/VIDEO_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token=AUTHORIZATION_TOKEN
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

Deleted videos are typically removed from a user's public uploaded videos feed within a couple of hours.

Using community features

Adding a rating

A user can add a rating to a video. YouTube uses a 1-5 rating system in which 1 is the lowest rating that can be given. Users cannot update or delete ratings. Typically, a user would rate a video after watching that video.

In an API response, each entry includes two tags that contain information relevant to user ratings:

• The <gd:rating> tag identifies the rating scale, the number of ratings of the video and the average rating for the video. This tag is only returned if the video has been rated. The XML excerpt below shows how this URL appears in an API response:

  <feed>
    <entry>
      ...
      <gd:rating min='1' max='5' numRaters='1914' average='4.24'/>
    </entry>
  </feed>
  

• A <link> tag identifies the URL to which you would post an API request to add a rating to a video. Since each entry includes several link tags, you must use the URL for the tag for which the rel attribute value is http://gdata.youtube.com/schemas/2007#video.ratings. The XML excerpt below shows how this URL appears in an API response:

  <feed>
    <entry>
      <link rel='http://gdata.youtube.com/schemas/2007#video.responses'
        type='application/atom+xml'
        href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/responses'/>
      <link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
        type='application/atom+xml'
        href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/ratings'/>
      ...
      <media:group>
    </entry>
  </feed>
  

To add a rating, send an HTTP POST request that identifies the video being rated and the rating itself. (The user who is rating the video is identified by the authentication token.)

The following XML demonstrates how to add a rating to a video. Please note that the value attribute of the <gd:rating> tag must be an integer between 1 and 5 that identifies the rating being given.

POST /feeds/api/videos/VIDEO_ID/ratings
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token=AUTHORIZATION_TOKEN
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
       xmlns:gd="http://schemas.google.com/g/2005">
  <gd:rating value="4" min="1" max="5"/>
</entry>

If YouTube successfully handles your request, the API will return a 201 HTTP response code.

YouTube will return an error if your HTTP request specifies an invalid value for the <gd:rating> tag's value attribute, a value other than 1 for the min attribute or a value other than 5 for the max attribute.

Comments

A comment is a text response to a video. Logged-in users can add comments to a video but cannot modify or delete those comments. In addition, please note that YouTube will convert any HTML markup that appears in a comment into plain text. Typically, a user would add a comment to a video after watching that video.

Retrieving comments for a video

Each video entry contains a <gd:comments> tag, which encapsulates the URL to which you will send API requests to retrieve or append to the list of comments for the video. The sample XML below shows how this URL appears in an API response:

<feed>
  <entry>
    ...
    <media:group>
      ...
    </media:group>
    <gd:comments>
      <gd:feedLink
        href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/comments'/>
    </gd:comments>
  </entry>
</feed>

Each comment has an author, a title and content. The following XML shows a sample API response containing a comments feed:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'>
  <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?...</id>
  <updated>2008-02-25T23:14:03.148Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind' 
    term='http://gdata.youtube.com/schemas/2007#comment'/>
  <title type='text'>Comments on 'My walk with Mr. Darcy'</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='related' type='application/atom+xml' 
    href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b'/>
  <link rel='alternate' type='text/html'
    href='http://www.youtube.com/watch?v=ZTUVgYoeN_b'/>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' 
    href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments'/>
  <link rel='self' type='application/atom+xml' 
    href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?...'/>
  <link rel='next' type='application/atom+xml' 
    href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?...'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='beta'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>100</openSearch:totalResults> 
  <openSearch:startIndex>1</openSearch:startIndex> 
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage> 
  <entry>
    <id>
      http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments/7F2...
    </id>
    <published>2007-05-23T00:21:59.000-07:00</published> 
    <updated>2007-05-23T00:21:59.000-07:00</updated> 
    <category scheme='http://schemas.google.com/g/2005#kind' 
      term='http://gdata.youtube.com/schemas/2007#comment'/>
    <title type='text'>Walking is fun.</title>
    <content type='text'>Walking is fun.</content>
    <link rel='related' type='application/atom+xml' 
      href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b'/>
    <link rel='alternate' type='text/html' 
      href='http://www.youtube.com/watch?v=ZTUVgYoeN_b'/>
    <link rel='self' type='application/atom+xml' 
      href='http://gdata.youtube.com/feeds/api/videos/ZTU.../comments/7F2...'/>
    <author>
      <name>andyland744</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland744</uri> 
    </author>
  </entry>
  <entry>
    ...
  </entry>
  ...
</feed>

YouTube users may respond to a comment with another comment. In an XML response, a comment that was posted in response to another comment will contain an in-reply-to link as shown in the following <link> tag:

<link rel="http://gdata.youtube.com/schemas/2007#in-reply-to"
  type="application/atom+xml" 
  href="http://gdata.youtube.com/feeds/api/videos/2cd.../comments/978..."/>

Adding a comment in response to a video

To add a comment to a video, send an HTTP POST request to the URL identified in the <gd:feedLink> tag that appears inside the <gd:comments> tag. The actual comment that you are submitting appears as the value of the <content> tag in the XML that constitutes the body of the POST request.

The sample XML API request below demonstrates how to add a comment to a video.

POST /feeds/api/videos/VIDEO_ID/comments HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token=AUTHORIZATION_TOKEN
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVE