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 application 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 documentation is intended for programmers who are writing client applications that interact with YouTube. It provides examples of basic API operations using raw HTTP and XML. Java , .NET, PHP and Python developers may prefer to read the language-specific developer guides that explain how to use the client libraries for those languages to perform similar functions.

This documentation 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 documentation

This documentation 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 documentation, 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.

API versioning

API requests can specify the version of the API that YouTube should use to handle the request. Your request can specify an API version using either the v parameter or the GData-Version HTTP request header. If a request does not specify an API version, then YouTube will use the oldest supported version of the API to handle that request. The oldest supported version is currently 1.

Note: All of the sample requests in this documentation use the GData-Version HTTP request header.

Please note the following characteristics of API version numbers:

• YouTube may release updates to a specific API version for which the release is not assigned a new version number. These backward-compatible updates can include optional API features, bug fixes or both.

• An increment of the API version number identifies a release that contains changes that are incompatible with previous API versions.

For more information, see the Backward Compatibility Guidelines, which identify API behaviors that may change even if you do not modify the API version that should be used to handle your API requests. The guidelines also define API behaviors that YouTube does not intend to change for a particular API version.

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 documentation 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 Authorization header and either the X-GData-Key header or the key parameter. The X-GData-Key header (or the key parameter) 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 three authentication schemes – AuthSub, OAuth 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.

• The OAuth protocol provides a standard way to access protected data on different websites. Whereas the AuthSub and ClientLogin methods are Google-specific, OAuth is an open protocol that may be implemented on other websites. Like AuthSub, OAuth is useful if you are building a web application that will let users link videos, comments, ratings, contacts or other information to their own YouTube accounts. OAuth may be particularly appealing to you if your application also integrates with other APIs besides the YouTube API, and those APIs also support the OAuth protocol. See http://oauth.net to learn more about Oauth.

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

YouTube provides two ways to specify your client ID and developer key in an API request:

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

• Include the client and key query parameters in the request URL.

  http://gdata.youtube.com/feeds/api/videos?q=SEARCH_TERM&client=CLIENT_ID&key=DEVELOPER_KEY
  

Note: Specifying your client ID and developer key is very simple if you are using one of our client libraries. In the client libraries, you provide your client ID and developer key when initializing the YouTube service object, and all subsequent requests sent using that object will contain the client ID and developer key.

AuthSub for web applications

The AuthSub process is documented in more detail at http://code.google.com/apis/accounts/docs/AuthSub.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 that document.

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 video upload 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: Throughout this documentation, sample requests use AuthSub syntax unless otherwise specified.

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

OAuth for web applications

The OAuth protocol provides a standard way to access protected data on different websites. Whereas the AuthSub and ClientLogin methods are Google-specific, OAuth is an open protocol that can be implemented on other websites. Like AuthSub, OAuth is useful if you are building a web application that will let users link videos, comments, ratings, contacts or other information to their own YouTube accounts.

Understanding OAuth Tokens

OAuth authentication uses two types of tokens:

• A request token ensures that an end user authorizes your application to submit API operations on the user's behalf. YouTube also uses the request token to verify that you have registered your application with Google.
• An access token enables your application to execute YouTube Data API operations on a particular user's behalf.

Note: Your application must obtain unique request and access tokens for each user. In addition, your application needs a mechanism to store access tokens for future use.

The authentication process has three stages:

1. Your application retrieves an unauthorized request token. Google verifies that you have registered your application before returning the token. Request tokens are only valid for one hour.

2. Your application redirects the user to a Google login page. The redirect URL specifies the unauthorized request token value retrieved in step 1 as well as a callback URL.

   After the user logs in to her YouTube account, Google displays a page that lets the user choose whether to allow your application to perform YouTube API operations on her behalf. If the user grants your application this access, the unauthorized token will become an authorized token. (The token value does not change.) The user will also be redirected to the callback URL that you specified.

3. Your application exchanges the authorized request token for an access token. Only authorized tokens can be exchanged, and each request token can only be exchanged one time. The access token is associated with a single user account, and your application should use that token to submit authenticated API requests on that user's behalf.

Setting up OAuth authentication

You must complete the following steps to enable your web application to authenticate users with the OAuth protocol:

1. Register your web application with Google.

   Please see the Registration for Web-Based Applications page for an explanation of the registration process and the requirements for registration.

   Note: All requests to obtain or use an OAuth token must be signed. Google supports the RSA-SHA1 and HMAC-SHA1 signature algorithms.

   • If your application uses the RSA-SHA1 signature algorithm, you will need to upload a security certificate to Google during the registration process.
   • If your application uses the HMAC-SHA1 signature algorithm, leave the certificate field blank when completing your registration. Google will generate an OAuth consumer secret value, which will display on your domain's registration page after you have completed the registration process. You will then use this value to sign requests.

2. Set up a mechanism to manage OAuth tokens.

   After your application obtains an OAuth access token from YouTube, your application will use that token for YouTube API requests it makes on behalf of the user associated with that token. As such, your application will need to store tokens and track the user for whom each token is valid. Your application should not try to retrieve a new access token each time the application needs to interact with YouTube on a particular user's behalf. In fact, tokens should be treated as securely as any other sensitive user information that your application stores.

Using OAuth

As described in the Understanding OAuth tokens section, the OAuth authentication process has three steps. These steps are explained in the following sections:

Step 1: Obtaining a request token

To obtain a request token, send a signed request to https://www.google.com/accounts/OAuthGetRequestToken. Include the following parameters in your request. Note that the only optional parameter is oauth_version; all other parameters are required.

There are three ways to specify these parameters:

• Include them in the Authorization header of a GET or POST request. The sample request below demonstrates how to specify these values in the Authorization header. Note that the scope parameter cannot be specified in the header. The scope can be specified as a query parameter in the request URL or in the body of a POST request.

• Specify them in the body of a POST request. If you choose this method, you must set the value of the Content-Type request header to application/x-www-form-urlencoded.

• Include them as query parameters in the request URL of a GET request.

For more details, see the OAuth specification, (section 5.2).

Sample Request

The example asks for a request token to access a user's Calendar and Picasa accounts.

POST /accounts/OAuthGetRequestToken HTTP/1.1
Host: https://www.google.com
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
               oauth_consumer_key="example.com",
               oauth_signature_method="RSA-SHA1",
               oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
               oauth_timestamp="137131200",
               oauth_nonce="4572616e48616d6d65724c61686176",
               oauth_version="1.0"

scope=http://gdata.youtube.com

About the response

If the request is successful, Google responds with an HTTP 200 message containing a request token and a token secret. Your application needs to parse the token from the response.

If the request is unsuccessful, Google responses with an HTTP 400 message (Bad Request). This response may indicate that the request is poorly formed, meaning it may have an unsupported or missing parameter, unsupported signature method or other error in the request format. This response may also indicate that Google has reason to believe the requester is not acting in good faith.

The following example shows a response to a successful request for a request token:

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20

Step 2: Authorizing a request token

After you retrieve a request token, redirect the user to https://www.google.com/accounts/OAuthAuthorizeToken. Add the following query parameters to the URL:

Sample Request

The following example shows a request to authorize an unauthorized token:

https://www.google.com/accounts/OAuthAuthorizeToken?oauth_token=ab3cd9j4ks73hf7g&oauth_callback=http%3A%2F%2Fwww.example.com

About the response

If Google accepts the request, the user will be redirected to a YouTube login page. After the user logs in, the Authentication service displays a page to inform the user that your application wants to access the user's YouTube account. The page prompts the user to confirm that your application can access the user's account.

If the user grants access to your application, she will be redirected to the callback URL specified in your request to authorize the request token. If the user denies access, she will be redirected to a page that displays a link back to your site and a link to YouTube.

The following URL shows the format of a redirect back to the callback URL with an authorized request token. The authorized token has the same value as the unauthorized token sent in the request. The value is a text string, up to 256 bytes.

http://www.example.com/ytapi.html?oauth_token=CKF50YzIHxCT85KMAg

Step 3: Exchanging a request token for an access token

After authorizing the request token for a user, your application can exchange that token for an access token. An access token lets you submit authenticated YouTube API requests on a specific user's behalf. Access tokens do not expire, effectively functioning like AuthSub session tokens.

To exchange an authorized request token for an access token, send a signed HTTP request to https://www.google.com/accounts/OAuthGetAccessToken with the following query parameters. Note that all of these parameters except for the oauth_token parameter are also used (and used in the same context) in the request to obtain a request token. In addition, the only optional parameter is oauth_version; all other parameters are required.

Your application can use the same three mechanisms to specify these parameters as it can use to specify parameters when obtaining a request token.

Sample Request

The following example exchanges a request token for an access token:

POST /accounts/OAuthGetAccessToken HTTP/1.1
Host:  https://www.google.com
Content-Type: application/x-www-form-urlencoded
Authorization: OAuth
               oauth_consumer_key="example.com",
               oauth_token="CKF50YzIHxCT85KMAg",
               oauth_signature_method="RSA-SHA1",
               oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
               oauth_timestamp="137131200",
               oauth_nonce="4572616e48616d6d65724c61686176",
               oauth_version="1.0"

About the response

Google responds to a successful request for an access token with an HTTP 200 message that contains an access token and a token secret. The following example shows a sample response containing an OAuth access token:

oauth_token=ab3cd9j4ks73hf7g&oauth_token_secret=ZXhhbXBsZS5jb20

Google may reject a token request if it is poorly formed or if Google has reason to believe the requester is not acting in good faith. If the request is not successful, Google will return an HTTP 400 (Bad Request) response code.

Signing requests that use OAuth authentication

You must sign all API requests that retrieve or use an OAuth token. This requirement applies to calls to obtain a request token or an access token as well as to any YouTube Data API requests that require authentication, such as uploading a video or adding a rating to a video.

The following steps explain how to generate a signature for requests that use OAuth authentication:

1. Use the oauth_signature_method parameter to specify the signature algorithm that the request uses. Google supports the RSA-SHA1 and HMAC-SHA1 signature algorithms.

2. Construct a signature base string, which consists of three request elements that are concatenated using ampersand (&) characters. Note that all parameter names and values must be encoded as described in the OAuth Specification (section 5.1).

   • The first element specifies the HTTP request method (GET, POST, etc.).

   • The second element specifies the base URL for the request. The URL must not include any query parameters. For example, if the request URL is http://gdata.youtube.com/feeds/api/videos?q=football&orderby=published&v=2, then the base URL is http://gdata.youtube.com/feeds/api/videos.

   • The third element contains a normalized string of the parameter and parameter values in the request. The string should include any query parameters specified in the request URL as well as all of the OAuth parameters except for the oauth_signature parameter. The OAuth Specification (section 9.1.1), explains how to normalize the string.

3. Generate an oauth_signature using the specified oauth_signature_method.

   • If you are using RSA-SHA1, generate the signature using the private key that corresponds to the certificate that you uploaded to Google during the registration process.
   • If you are using HMAC-SHA1, generate the signature using the "consumer secret" value generated during the registration process. (The value is displayed on your domain's registration page.

The OAuth Specification (appendix A.5) provides a sample request that can be used to test HMAC-SHA1 signatures. The example includes a signature base string and HMAC-SHA1 key as well as the generated HMAC-SHA1 digest (signature).

Note: For more detailed information about signing an OAuth request, please see the OAuth Specification (section 9).

ClientLogin for installed applications

To make an authenticated API request using YouTube's ClientLogin system for single-user authentication, you must identify the YouTube user account associated with the request. 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=youtube&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>

Authenticating requests from Flash applications

As shown in the examples throughout this documentation, different API operations are executed using either HTTP GET, POST, PUT or DELETE requests. However, Flash applications must send an HTTP POST request in order to set an Authorization header.

To submit an authenticated HTTP GET, PUT or DELETE request from a Flash application, set the X-HTTP-Method-Override header in the request to either GET, PUT or DELETE. If your application is submitting a GET request, it should set the body of the request to the query parameters associated with that request as shown in the following example:

POST /feeds/api/videos HTTP/1.1
X-HTTP-Method-Override: GET
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="<authentication_token>"
GData-Version: 2
X-GData-Client: <CLIENT_ID>
X-GData-Key: key=<DEVELOPER_KEY>

vq=jesse+ventura&category=News

If your application is submitting a POST or PUT request, it should set the body of the request to an XML document. The XML formats for different types of requests are defined later in this document.

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/opensearch/1.1/'
    xmlns:gml='http://www.opengis.net/gml'
    xmlns:georss='http://www.georss.org/georss'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:batch='http://schemas.google.com/gdata/batch'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/&quot;CE4EQH47eCp7ImA9WxRQGEQ.&quot;'>
  <id>tag:youtube,2008:standardfeed:us:top_rated</id>
  <updated>2008-07-18T05:00:49.000-07:00</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#video'/>
  <title>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/browse?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?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?...'/>
  <link rel='next' 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='2.0'
    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 gd:etag='W/&quot;C0AMRn47eCp7ImA9WxRQGUw.&quot;'>
    <id>tag:youtube,2008:video:ZTUVgYoeN_b</id>
    <published>2008-07-05T19:56:35.000-07:00</published>
    <updated>2008-07-18T07:21:59.000-07:00</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='Shopping'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/keywords.cat'
      term='parkas'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/categories.cat'
      term='People' label='People'/>
    <title>Shopping for Coats</title>
    <content type='application/x-shockwave-flash'
      src='http://www.youtube.com/v/ZTUVgYoeN_b?f=gdata_standard...'/>
    <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?v=2'/>
    <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?v=2'/>
    <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?v=2'/>
    <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?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#mobile'
      type='text/html' href='http://m.youtube.com/details?v=ZTUVgYoeN_b'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated/v/ZTUVgYoeN_b?v=2'/>
    <author>
      <name>andyland74</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'/>
      <yt:videoid>ZTUVgYoeN_b</yt:videoid>
      <media:player url='http://www.youtube.com/watch?v=ZTUVgYoeN_b'/>
      <media:credit role='uploader' scheme='urn:youtube'>andyland74</media:credit>
      <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?f=gdata_standard...'
        type='application/x-shockwave-flash' medium='video'
        isDefault='true' expression='full' duration='215' yt:format='5'/>
      <media:content
        url='rtsp://rtsp2.youtube.com/ChoLENy73bIAEQ1kgGDA==/0/0/0/video.3gp'
        type='video/3gpp' medium='video'
        expression='full' duration='215' yt:format='1'/>
      <media:content
        url='rtsp://rtsp2.youtube.com/ChoLENy73bIDRQ1kgGDA==/0/0/0/video.3gp'
        type='video/3gpp' medium='video'
        expression='full' duration='215' yt:format='6'/>
      <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='383290' favoriteCount='7022'/>
    <gd:rating min='1' max='5' numRaters='14763' average='4.93'/>
    <georss:where>
      <gml:Point>
        <gml:pos>21.37124437061831 -157.87353515625</gml:pos>
      </gml:Point>
    </georss:where>
    <gd:comments>
      <gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments'
        countHint='9416'/>
    </gd:comments>
  </entry>
</feed>

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 gd:etag='W/&quot;C0AMRn47eCp7ImA9WxRQGUw.&quot;'>
  <id>tag:youtube,2008:video: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 <summary> 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 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

  To ensure that the API response contains the most up-to-date information available for the user's videos, do not use any parameters other than start-index and max-results in your request. Requests using other parameters, such as orderby, will return cached results.

  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?v=2"/>

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

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

The YouTube Data API supports two different methods for retrieving videos that are in a particular category or that are labeled with a specific keyword or developer tag.

• Use the following URL to retrieve videos that are in a specific category or that are labeled with a specific keyword or developer tag. The hyphen (-) in the URL is a standard Google Data API notation that indicates that the rest of the URL consists of a series of one or more tags.

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

  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

• Specify the category, keyword or developer tags using the category parameter in the request URL. The following example shows the URL that you would use to request videos in the "Comedy" category:

  http://gdata.youtube.com/feeds/api/videos?category=Comedy

The following guidelines provide more detail about requesting videos associated with particular categories or tags:

• 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. (If you are using the category parameter, separate the different category and tag names with a comma. (The comma must be URL-encoded in your request.) For example, you could use either of the following URLs to request videos related to the keywords "bass" and "fishing":

  URL notation:
  http://gdata.youtube.com/feeds/api/videos/-/bass/fishing?v=2
  
  category parameter:
  http://gdata.youtube.com/feeds/api/videos?category=bass%2Cfishing&v=2
  

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

  URL notation:
  http://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing?v=2
  
  category parameter:
  http://gdata.youtube.com/feeds/api/videos?category=bass%2C%2Dfish%2Dfishing&v=2
  

  The following example shows how to search for videos that are tagged with the keywords "Jesse" and "Ventura" and that are in either the "News" or "Sports" 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:

  URL notation:
  http://gdata.youtube.com/feeds/api/videos/-/jesse/ventura/News%7CSports?v=2
  
  category parameter:
  http://gdata.youtube.com/feeds/api/videos?category=jesse%2Cventura%2CNews%7CSports&v=2
  

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

  URL notation:
  http://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy?v=2
  
  category parameter:
  http://gdata.youtube.com/feeds/api/videos?category=comedy%2C%2DComedy&v=2
  

• 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:
    URL notation:
    http://gdata.youtube.com/feeds/api/videos/-/
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fcategories.cat%7DNews?v=2
  
    category parameter:
    http://gdata.youtube.com/feeds/api/videos?category=
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fcategories.cat%7DNews&v=2
  
  Keywords:
    URL notation:
    http://gdata.youtube.com/feeds/api/videos/-/
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fkeywords.cat%7Ddog?v=2
  
    category parameter:
    http://gdata.youtube.com/feeds/api/videos?category=
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fkeywords.cat%7Ddog&v=2
  
  Developer tags:
    URL notation:
    http://gdata.youtube.com/feeds/api/videos/-/
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fdevelopertags.cat%7Dexample.com?v=2
  
    category parameter:
    http://gdata.youtube.com/feeds/api/videos?category=
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fdevelopertags.cat%7Dexample.com&v=2
  

• 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

For example, a request to the following URL 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?
    q=football+-soccer
    &orderby=published
    &start-index=11
    &max-results=10
    &v=2

Standard Google Data API query parameters

The YouTube Data API supports the following standard Google Data query parameters.

http://gdata.youtube.com/feeds/api/videos?foo=nonono&strict=true

Please see the Google Data APIs Protocol Reference for more information about standard Google Data API functionality or about these specific parameters.

Custom query parameters for the YouTube Data API

In addition to the standard Google Data query parameters, the YouTube Data API defines the following API-specific query parameters:

In general, parameters that are used for filtering and ordering results are only supported for search requests. However, the API also supports the time parameter for many standard feeds, the author parameter for user activity feeds, and the restriction parameter for video feeds. Please see the Testing and troubleshooting section for tips on how to filter API response feeds that do not support these parameters.

The following table defines each of these parameters:

http://gdata.youtube.com/feeds/api/videos?q=surfing&caption&v=2

<media:credit role="uploader" scheme="urn:youtube
  yt:type="partner">partner_name</media:credit>

Retrieving information about a single video

To retrieve information about a single video, you can submit an HTTP GET request to the following URL. (You need to replace the text videoid with the video's actual video ID.)

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

Note: The video ID for a video is identified in feed entries by the <yt:videoid> tag. This tag appears in video feed entries – including standard feeds, search results, user-uploaded video feeds, etc. – as well as in favorite video feed entries, playlist feed entries, inbox feed entries and several types of activity feed entries.

The API response to a request for a single video feed entry is an Atom entry that contains information about the video. The root tag of the response is <entry>. The entry itself contains the same tags as the sample feed entry in the Understanding video feeds and entries section.

Retrieving video information with the private feed URL

To retrieve the most up-to-date information for a video uploaded by the currently logged-in user, you need to submit an authenticated HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/users/USER_ID/uploads/videoid

You can also retrieve the most up-to-date information for the currently logged-in user by requesting the user's uploaded videos feed from the following URL. Note that your request can use the start-index or max-results parameters but cannot use any other request parameters.

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

For more information, please see the Checking the status of an uploaded video section.

Searching for channels

This section explains how to use the API to retrieve a list of channels matching a user-specified search term. YouTube could match the search term to the channel name, description or other channel-related fields. To search for channels, submit an HTTP GET request to the following URL:

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

YouTube supports the following API query parameters for channel search:

• alt
• q
• max-results
• start-index
• strict
• v

Note: Since the query term could be matched against the channel description, the q parameter value could contain multiple words. You can also search for an exact phrase as described in the q parameter definition. However, for channel search requests, the q parameter does not support the Boolean NOT (-) and OR (|) operators.

Sample channel search request

The following API request searches for the second set of 10 channels matching the query term "soccer":

http://gdata.youtube.com/feeds/api/channels?
    q=soccer
    &start-index=11
    &max-results=10
    &v=2

This request yields the following response:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"CEEERnk_fCp7ImA9WxRUEU4."'>
  <id>tag:youtube.com,2008:channels</id>
  <updated>2008-11-19T14:10:07.744-08:00</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#channel'/>
  <title>YouTube Channels matching query: soccer</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/channels?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/channels/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/channels?q=soccer&start-index=11&max-results=10&v=2'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/channels?alt=atom-service&v=2'/>
  <link rel='next' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/channels?q=soccer&start-index=21&max-results=10&v=2'/>   
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>6141</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>    
  <entry gd:etag='W/"CEEERnk_fCp7ImA9WxRUEU4."'>
    <id>tag:youtube.com,2008:channel:dXNzb2NjZXJkb3Rjb20</id>
    <updated>2008-11-19T14:10:07.744-08:00</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#channel'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/channeltypes.cat'
      term='director'/>
    <title>U.S. Soccer</title>
    <summary>
      ussoccer.com's comprehensive coverage of the U.S. National Teams welcomes
      fans to our YouTube channel - including interviews, press conferences...
    </summary>
    <link rel='http://gdata.youtube.com/schemas/2007#featured-video'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/bYKugypF8HA?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/profile?user=ussoccerdotcom'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/channels/dXNzb2NjZXJkb3Rjb20?v=2'/>
    <author>
      <name>ussoccerdotcom</name>
      <uri>http://gdata.youtube.com/feeds/api/users/ussoccerdotcom</uri>
    </author>
    <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#channel.content'
      href='http://gdata.youtube.com/feeds/api/users/ussoccerdotcom/uploads?v=2'
      countHint='513'/>
  </entry>
  <entry>
    ...
  </entry>
  ...
</feed>

Each entry in the response contains information about a YouTube channel that matches the search request. Entries contain the following information:

• The <title> and <summary> tags specify a name and description of the channel, respectively.

• The <author> tag identifies the owner of the channel, and the <uri> tag within the <author> tag specifies the feed URL that you would use to retrieve more information about the channel owner.

• The <gd:feedLink> tag, which has a rel attribute value of http://gdata.youtube.com/schemas/2007#channel.content, identifies the URL that you would use to retrieve a feed of the videos in the channel.

• The <link> tags contain links relevant to the channel, including a link to the channel's featured video and a link to the channel owner's profile page.

• One <category> tag specifies that the entry contains information about a channel. An additional <category> tag may be present indicating that the type of channel that the entry describes. Channel types include director, guru and musician. See http://gdata.youtube.com/schemas/2007/channeltypes.cat for a complete list of channel types.

Searching for playlists

This section explains how to use the API to retrieve a list of playlists matching a user-specified search term. YouTube tries to match the search term to playlist names and descriptions as well as to the metadata fields for videos in each playlist. To search for playlists, submit an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/playlists/snippets

YouTube supports the following API query parameters for playlist search:

• alt
• q
• max-results
• start-index
• strict
• v – this feed is only available in API version 2 (v=2)

Note: The q parameter value can contain multiple words. The q parameter value can also use the Boolean NOT (-) and OR (|) operators. However, playlist search requests do not support searches for an exact phrase, as described in the q parameter definition.

Sample playlist search request

The following API request searches for the second set of 10 playlists matching the query term "soccer":

http://gdata.youtube.com/feeds/api/playlists/snippets?
    q=soccer
    &start-index=11
    &max-results=10
    &v=2

This request yields the following response:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/' xmlns:media='http://search.yahoo.com/mrss/' xmlns:batch='http://schemas.google.com/gdata/batch' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005' gd:etag='W/"DEAAQH44eip7ImA9WxVUGUQ."'>
  <id>tag:youtube.com,2008:playlists:snippets</id>
  <updated>2009-03-25T15:59:01.032Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/>
  <title>YouTube Playlists matching query: soccer</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/snippets?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/snippets?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/snippets/batch?v=2'/>
  <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/snippets?q=soccer&start-index=1&max-results=25&v=2'/>
  <link rel='service' type='application/atomsvc+xml' href='http://gdata.youtube.com/feeds/api/playlists/snippets?alt=atom-service&v=2'/>
  <link rel='next' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/snippets?q=soccer&start-index=26&max-results=25&v=2'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>459746</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/"D0ANRn47eCp7ImA9WxVUF04."'>
    <id>tag:youtube.com,2008:playlist:snippet:E6DE6EC9A373AF57</id>
    <published>2008-05-26T23:39:53.000Z</published>
    <updated>2009-03-21T12:45:57.000Z</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>2009-03-21T12:45:57.000Z</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/>
    <title>Google Data <b>APIs</b></title>
    <summary>
    </summary>
    <content type='application/atom+xml;type=feed' src='http://gdata.youtube.com/feeds/api/playlists/E6DE6EC9A373AF57?v=2'/>
    <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/GoogleDevelopers?v=2'/>
    <link rel='alternate' type='text/html' href='http://www.youtube.com/view_play_list?p=E6DE6EC9A373AF57'/>
    <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/snippets/E6DE6EC9A373AF57?v=2'/>
    <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/snippets/E6DE6EC9A373AF57?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>http://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
    </author>
    <yt:playlistId>E6DE6EC9A373AF57</yt:playlistId>
    <yt:countHint>24</yt:countHint>
  </entry>
  <entry>
    ...
  </entry>
</feed>

Each entry in the response contains information about a YouTube playlist that matches the search request. Entries contain the following information:

• The <title> and <summary> tags specify a name and description of the playlist, respectively. (Note that some playlists may not have a description, in which case the <summary> tag will be empty.)

• The <author> tag identifies the owner of the playlist.

• The <content> tag identifies the URL that you would use to retrieve a feed of the videos in the playlist.

• The <link> tags contain links relevant to the playlist, including a link to retrieve the playlist owner's profile data through the API and a link to view the playlist on the YouTube website.

• The <yt:playlistId> tag contains a value that YouTube uses to uniquely identify a playlist. You could use this value to add a subscription to the playlist.

• The <yt:countHint> tag specifies the number of videos in the playlist.

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.

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

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

Note: The YouTube Data API will not allow you to upload additional videos to accounts that already contain 2000 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.

OAuth authentication

The following diagram illustrates the steps involved in authenticating a user using the OAuth protocol. Like AuthSub and ClientLogin authentication, OAuth 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 perform an API operation that requires authentication.

2. Your application determines whether you have an OAuth access token stored for the user. If you do have an access token, your application would skip ahead to step 14. If you do not have an access token, your application would proceed to step 3.

3. Your application submits a signed request to obtain a request token from Google's OAuth authentication service.

4. Google responds to your request with an unauthorized request token, which you parse from the response.

5. Your application redirects the user to the YouTube account authentication service. The redirect URL identifies the unauthorized request token and a callback URL.

6. The user's browser handles the redirect by sending a request to YouTube's account authentication service.

7. The YouTube account authentication service displays an Access Consent page, prompting the user to log in to a YouTube account and grant or deny the ability for your application to perform API operations for that account.

8. The user logs in and grants account access to your application.

9. If the user grants access, YouTube redirects the user back to the callback URL that you included in the URL in step 6. The user could also deny account access, in which case YouTube would display a page with links back to your application and to the YouTube website.

10. The user's browser handles the redirect and sends a request to your callback URL. The redirect URL contains the authorized request token value. (The authorized request token has the same value as the unauthorized request token.)

11. Your application submits a signed request to YouTube's OAuth authentication service to exchange the request token for an access token.

12. YouTube responds to your request with an access token.

13. Your application parses the access token from the response and stores the token value, which is associated with a particular user. In the future, your application will use that same access token to make authenticated requests for the same user.

14. Your application submits an API request using the access token to authenticate the request.

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.

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 1 GB or smaller and that videos may not be longer than 10 minutes. You may compress API requests using gzip transfer-encoding. However, please note that the 1 GB size restriction still 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.

Note: You can only associate developer tags with a video at the time that the video is uploaded. In addition, developer tags that are assigned when a video is uploaded cannot be altered thereafter.

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>"
GData-Version: 2
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, an AuthSub single-use token, an AuthSub session token or an OAuth access 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"
GData-Version: 2
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:

<?xml version='1.0' encoding='UTF-8'?>
<response>
  <url>http://uploads.gdata.youtube.com/action/FormDataUpload/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 have a hidden input field containing the upload token. In addition, the form should verify that the user has selected a file to upload before allowing the user to actually submit the form.

The following JavaScript and HTML show a sample form as it might appear on your site. The JavaScript function, which executes when the user tries to submit the form, confirms that the user has selected a file to upload. If the user has not selected a file, then the function displays an error message below the file field.

<script type="text/javascript">
  function checkForFile() {
    if (document.getElementById('file').value) {
      return true;
    }
    document.getElementById('errMsg').style.display = '';
    return false;
  }
</script>

<form action="URL?nexturl=http%3A%2F%2Fwww.example.com method="post"
  enctype="multipart/form-data" onsubmit="return checkForFile();">
  <input id="file" type="file" name="file"/>
  <div id="errMsg" style="display:none;color:red">
    You need to specify a file.
  </div>
  <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 appended 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.

• Your application should verify that the user has selected a file to upload before allowing the user to submit the form to upload the file.

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>"
GData-Version: 2
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, an AuthSub single-use token, an AuthSub session token or an OAuth access 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 can be a video media type, such as video/mpeg or video/mp4, or it can be 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"
GData-Version: 2
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 gd:etag='W/"Ak4ER347eCp7ImA9WxRRF0k."'>
  <id>tag:youtube,2008:video: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, .NET, PHP and Python developer's guides all 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/api/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"
GData-Version: 2
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"
GData-Version: 2
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.

Providing captions for a video

Adding captions to your video files can help users to locate and understand your videos. To add captions to a video, you need to create a file containing the captions and then provide that file to YouTube.

This section discusses the caption file formats that YouTube supports. It also explains the API operations that you can use to create, retrieve, update and delete caption files.

Requirements for caption operations

Please note the following requirements for executing caption-related API operations:

• Captions are only available for API version 2.

• Captions for a video can only be created, retrieved, modified and deleted by the owner of that video. To perform these operations for a video, you must submit authenticated API requests for which the video's owner is the logged-in user. Accordingly, API requests for caption operations must contain a properly formatted Authorization header.

• Requests to create (POST), update (PUT) or delete (DELETE) captions must identify your developer key using either the X-GData-Key HTTP header or the key request parameter.

Supported formats for caption files

YouTube supports many different formats for caption files, including RealText (.rt), SAMI (.smi) and Media RSS. If you already have captions available, we recommend that you upload them in their original format, whatever that may be. If you do not have formatted caption data, such as a transcript that does not have timing data, we recommend using SubRip (*.SRT) or SubViewer (*.SUB) for generating formatted captions.

YouTube also supports a simple format that is compatible with both the SubRip and SubViewer formats. In this simple format, each caption is divided into three segments that appear in the following order:

1. Timecodes specify the time and duration that YouTube should display a caption in HH:MM:SS.FS format. Timecodes, which are measured from the beginning of the video, contain the following units

   • HH – Hours (00, 01, etc.)
   • MM – Minutes (00-59)
   • SS – Seconds (00-59)
   • FS – Fractional seconds (.000-.999)

   YouTube supports the following time constructs:

   • HH:MM:SS.FS,HH:MM:SS.FS – A caption appears at the first time offset and stops displaying at the second time offset. This format is compatible with the SubViewer format.
   • HH:MM:SS.FS --> HH:MM:SS.FS – A caption appears at the first time offset and stops displaying at the second time offset. To make this format completely compatible with the SubRip format, you can insert a "subtitle number" before the timecodes.
   • HH:MM:SS.FS – A caption appears at the designated time offset. Since no stop time is specified, YouTube will try to determine an appropriate stop time. For example, the caption might stop displaying just before the next caption is scheduled to appear.

2. The caption text consists of one or more lines of text that will be displayed on the screen during the time offsets. You must use UTF-8 encoding for the caption text.

3. A blank line marks the end of each caption.

The following example demonstrates this simple caption format:

0:01:23.000,0:01:25.000
This text displays for two seconds starting
1 minute and 23 seconds into the video.

0:02:20.250,0:02:23.8
This text displays from 2 minutes and 20.25 seconds after the start
of the video until 2 minutes and 23.8 seconds after the start of the video.

0:03:14.159
This text displays beginning 3 minutes and 14.159 seconds
after the start of the video for an undefined length of time. 

Retrieving a list of available caption tracks

Each video entry contains a <link> tag for which the rel attribute value is http://gdata.youtube.com/schemas/2007#video.captionTracks. (Note that this link is only visible to the owner of a video.) The tag's href attribute identifies the captions URL for the video.

<link rel="http://gdata.youtube.com/schemas/2007#video.captionTracks"
     type="application/atom+xml"
     href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/captions"
     yt:hasEntries="true|false"/>

Caption tracks are available for a video if the <link> tag's yt:hasEntries attribute has a value of true. If caption tracks are available for the video, you can retrieve the list of tracks by submitting an HTTP GET request to the URL in the link tag. You can use any of the following input parameters in a request to retrieve caption tracks:

• lr – This parameter filters the list of caption tracks by language. For example, if you include lr=de in your request, the API response will only list caption tracks in the German language. The parameter value must be an ISO 639-1 two-letter language code. By default, the API response will include tracks for all languages.
• max-results – This parameter specifies the maximum number of caption tracks to include in the results set.
• start-index – This parameter specifies the index of the first caption track that should be included in the result set. The parameter uses a one-based index, meaning the first track is 1, the second track is 2 and so forth.

Sample caption tracks feed

The following sample API response shows a caption tracks feed with a single entry:

<feed xmlns='http://www.w3.org/2005/Atom'  xmlns:app='http://www.w3.org/2007/app'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gd='http://schemas.google.com/g/2005'
  xmlns:xml='http://www.w3.org/XML/1998/namespace'
  gd:etag='W/"DkcNRH4zfSp7ImA9WxJXEUk."'>
  <id>tag:youtube.com,2008:videos:PjLv88-zqkI:captions</id>
  <updated>2009-06-04T19:34:55.085Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#captionTrack'/>
  <title>Caption Tracks for Video XYZ</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/PjLv88-zqkI?v=2'/>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
     href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions?...'/>
  <link rel='service' type='application/atomsvc+xml' 
    href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions?alt=...'/>
  <author>
    <name>andyland74</name>
    <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/"DkECQHk5cSp7ImA9WxJSGEw."'>
    <id>tag:youtube.com,2008:captions:CiELEO...</id>
    <published>2009-05-08T13:31:01.729-07:00</published>
    <updated>2009-05-08T13:31:01.729-07:00</updated>
    <app:edited>2009-05-08T13:31:01.729-07:00</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#captionTrack'/>
    <title>Sample 3</title>
    <content type='application/vnd.youtube.timedtext'
      src='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captiondata/CiELEO...'
      xml:lang='en'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions/CiELEO...'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions/CiELEO...'/>
    <link rel='edit-media' type='application/vnd.youtube.timedtext'
      href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captiondata/CiELEO...'/>
  </entry>
</feed>

Creating a caption track

To create a caption track, post a caption file to the http://schemas.google.com/g/2005#post link for the captions track feed.

• You must set the Content-Type header value to the following value:

  application/vnd.youtube.timedtext

• You should use the Content-Language header to specify the language of the caption track. If you do not specify a language, the API server will attempt to identify the language. However, if the identification fails, then your API request will also fail.

  If you do specify the caption track language, then you must also specify the character set used so that YouTube can decode the file. We recommend that you use UTF-8 encoding whenever possible. To specify the character set, add the charset parameter to the Content-Type header value as shown below:

  application/vnd.youtube.timedtext; charset=UTF-8

• You can use the Slug header to specify a title for the caption track. If you do not specify a title, the API server will use the language as the title of the caption track.

• The caption file must be 1MB or smaller.

The following sample API request demonstrates how to create a caption track:

POST /feeds/api/videos/VIDEO_ID/captions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/vnd.youtube.timedtext; charset=UTF-8
Content-Language: en
Slug: Title of caption track
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

<Caption File Data>

If YouTube successfully handles your request, the API will return a 201 HTTP response code. The Location header in the API response will contain the self link of the caption track entry, which can be used for later retrieval of the entry. The body of the XML response will be the caption track entry.

The XML below shows a successful response to a request to create a caption track:

HTTP 201
Content-Type: application/atom+xml; charset=UTF-8; type=entry
Location: http://gdata.youtube.com/feeds/api/captions/VIDEO_ID/captions/caption_track_id

<entry xmlns='http://www.w3.org/2005/Atom'
  xmlns:app='http://www.w3.org/2007/app'
  xmlns:gd='http://schemas.google.com/g/2005'
  xmlns:xml='http://www.w3.org/XML/1998/namespace'
  gd:etag='W/"DEMCSXc7fip7ImA9WxJXEk4."'>
  <id>tag:youtube.com,2008:captions:CiULE...</id>
  <published>2009-06-05T14:14:28.906-07:00</published>
  <updated>2009-06-05T14:14:28.906-07:00</updated>
  <app:edited>2009-06-05T14:14:28.906-07:00</app:edited>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#captionTrack'/>
  <title>API captions</title>
  <content type='application/vnd.youtube.timedtext'
    src='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captiondata/CiULE...'
    xml:lang='en'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions/CiULE...'/>
  <link rel='edit' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions/CiULE...'/>
  <link rel='edit-media' type='application/vnd.youtube.timedtext'
    href='http://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captiondata/CiULE...'/>
</entry>

If your HTTP request is properly formatted, but YouTube cannot process the captions file you are sending, YouTube will still create an <entry> in the captions feed for the new caption track. The entry will contain an <app:control> tag, which indicates that YouTube did not successfully handle the captions file. That tag, in turn, will contain a <yt:state> tag that contains more information about the failure and an <app:draft> tag that contains a value of yes, which indicates that the track is not publicly visible.

<app:control>
  <app:draft>yes</app:draft>
  <yt:state name="failed" reasonCode="invalidFormat"/>
</app:control>

Retrieving a caption track

Caption tracks are served automatically to the YouTube video players, which means that anyone watching a video can opt to view any caption track for that video. However, you can still retrieve a caption track if you want to modify the caption data or the timecodes that specify when the captions display.

To retrieve a caption track, send an HTTP GET request to the src URL specified in the <content> tag of the caption track entry:

<content type="text/xml" xml:lang="zh-HK"
  src="http://gdata.youtube.com/api/captiondata/caption-id"/>

The API does not return an Atom feed in response to a request for a caption track. Instead, the response contains your caption track in the same format that you uploaded it to YouTube. See the Supported formats for caption files section for details about valid caption file formats.

Updating a caption track

The API enables you to update the captions and timecodes for a caption track. However, you cannot update metadata about the track. So, for example, you cannot update the title or language of a caption track. If the title and/or language of a caption track is incorrect, you need to delete the track with the incorrect information and create a new track with the corrected title and language.

To update a caption track, send an HTTP PUT request to the edit-media link in the caption track entry:

<link rel="edit-media" type="application/atml+xml"
  href="http:/gdata.youtube.com/feeds/api/videos/VIDEO_ID/captiondata/CAPTION_ID" />

Your API request must set the Content-Type header value as described in the Creating a caption track section. In addition, your caption file must be 1MB or smaller. The request below demonstrates how to update a caption track:

PUT /feeds/api/videos/VIDEO_ID/captiondata/CAPTION_TRACK_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/vnd.youtube.timedtext; charset=UTF-8
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

<Binary Caption File Data>

The updated caption track must be in a supported format for caption files.

Deleting a caption track

To delete a caption track, send an HTTP DELETE request to the edit link in the caption track entry. The following sample API request demonstrates how to delete a caption track:

DELETE /feeds/api/videos/VIDEO_ID/captions/CAPTION_TRACK_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

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"
GData-Version: 2
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/opensearch/1.1/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/&quot;DE8HQXo-eip7ImA9WxRQGU4.&quot;'>
  <id>tag:youtube,2008:video:ZTUVgYoeN_b:comments</id>
  <updated>2008-07-18T22:10:57.065Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#comment'/>
  <title>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?v=2'/>
  <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?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?alt=atom-service&v=2'/>
  <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='2.0'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>9051</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;D0YASX47eCp7ImA9WxRQGU8.&quot;'>
    <id>tag:youtube,2008:video:xpI6VNvRTII:comment:F53EAC190E4EA5C9</id>
    <published>2008-07-18T14:57:59.000-07:00</published>
    <updated>2008-07-18T14:57:59.000-07:00</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#comment'/>
    <title>Walking is fun</title>
    <content>I like it a lot.</content>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b?v=2'/>
    <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/ZTUVgYoeN_b/comments/F53EAC190E4EA5C9?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
  </entry>
  <entry>
    ...
  </entry>
  ...
</feed>

Identifying comments that are replies to other comments

YouTube users may respond to a comment with another comment. When displaying these comments, you may want to indent comments that reply to other comments to identify comment threads. You could also link comments that reply to other comments to help users to follow a comment thread. 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"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <content>This is a crazy video.</content>
</entry>

Adding a comment in reply to another comment

The API request for adding a comment in response to a video is nearly identical to the API request for adding a comment in reply to another comment. The only difference is that the latter request contains an additional <link> tag that identifies the comment being replied to. The following instructions explain how to format the <link> tag:

1. Set the rel attribute value to http://gdata.youtube.com/schemas/2007#in-reply-to.
2. Set the type attribute value to application/atom+xml.
3. Set the href attribute value to the self link for the comment being replied to.

The sample XML API request below demonstrates how to add a comment in reply to another comment. The <link> tag that indicates that the comment is a reply to another comment is highlighted in bold text.

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"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <link rel="http://gdata.youtube.com/schemas/2007#in-reply-to"
    type="application/atom+xml" 
    href="http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/comments/COMMENT_ID"/>
  <content>This is a comment about another comment.</content>
</entry>

Note: The POST URL for this API request specifies the video associated with the new comment. The <link> tag identifies the original comment to which the new comment replies. The new comment and the original comment must be associated with the same video.

Video responses

A video response is a video that is associated, as a reply, with a second video. A video can be designated as a video response with exactly one other video. Logged-in users can add or delete video responses, but the user must have uploaded the video that is being added or deleted.

Retrieving a list of video responses

This section explains how to retrieve a feed of video responses for a video. Note that some videos may not have any video responses.

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.responses identifies the URL for retrieving video responses for that video entry. (The <link> tag's href attribute identifies the URL.)

<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"/>

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.

Adding a video response

To add a video response, you will submit an HTTP POST request that identifies two videos – the video that to which you are adding the video response and the video that is being added as a response.

The following XML illustrates the format for a sample request for adding a video response. In the request, the string ORIGINAL_VIDEO_ID identifies the video that to which you are adding the video response, and the string RESPONSE_VIDEO_ID identifies the video that is being added as a response.

POST /feeds/api/videos/ORIGINAL_VIDEO_ID/responses HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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">
  <id>RESPONSE_VIDEO_ID</id>
</entry>

If YouTube successfully handles your request, the API will return a 201 HTTP response code. However, the video response will not be listed in the video responses feed until the response has been approved by the owner of the original video.

Typically, a user will add a video response to a video after watching that video. In some cases, the user will select a video that he has already uploaded as the response. In other cases, the user will upload a new video, which will serve as the video response. The following list identifies the API calls associated with each type of API request:

• The user selects an existing video to serve as a video response.

  1. You retrieve information about a video by submitting an API request to that video's self URL.

  2. The user clicks a link to add a video response to the video and elects to respond with a previously uploaded video. You extract the video response URL for the video to which the user is adding the response.

  3. You send an API request to retrieve the list of videos uploaded by the user. You display the list of videos so that the user can select one of the videos.

  4. When the user selects a video, you send an HTTP POST request to the video response URL for the original video that specifies the <yt:videoid> of the selected video. The Retrieving a list of video responses section explains how to identify the video response URL for a feed entry.

• The user uploads a new video, which will serve as the video response.

  1. This use case also begins with an API request to retrieve information about a video.

  2. The user clicks a link to add a video response to the video and elects to upload (or capture) a new video. You extract the video response URL for the video to which the user is adding the response.

  3. You send an API request to upload the new video to YouTube's video library. If the user first needs to capture the video, you may also need to present a form that lets the user enter a title and other information about the video.

  4. You extract the video ID for the newly added video from the API response to your upload request.

  5. You send an HTTP POST request to the video response URL for the original video to add the newly added video as a video response.

Deleting a video response

To delete a video response, submit an HTTP DELETE request that identifies the two videos, as shown in the following example.

DELETE /feeds/api/videos/VIDEO_ID/responses/VIDEO_RESPONSE_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

Adding a complaint

A user can add a complaint about a video to flag the video for containing inappropriate content. Complaints can be inserted but cannot be updated or deleted. Typically, a user would file a complaint about a video after watching that video.

In an API response, each entry includes a <link> tag that identifies the URL to which you would post an API request to add a complaint about the 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.complaints.

To add a complaint, you will send an HTTP POST request that identifies the target of the complaint, the user who is making the complaint, and the text of the complaint itself. (The user is identified by the authentication token in the HTTP request headers.) The request can also specify the reason for the complaint by using a <category> tag that has a scheme attribute value of http://gdata.youtube.com/schemas/2007/complaint-reasons.cat. The tag's term attribute value must be one of the following terms:

• PORN - The video contains sexual content.
• VIOLENCE - The video contains violent or repulsive content.
• HATE - The video contains hateful or abusive content.
• DANGEROUS - The video contains harmful or dangerous acts.
• RIGHTS - The video infringes on the complainant's rights or copyright.
• SPAM

The following XML demonstrates how to add a complaint about a video.

POST /feeds/api/videos/VIDEO_ID/complaints HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <summary>
    Please ignore this complaint. I'm testing a YouTube API and 
    needed to issue a complaint to test the add complaint function.
    Per the value of the category tag, pretend I am complaining
    about a video that contains violent or repulsive acts.
  </summary>
  <category scheme="http://gdata.youtube.com/schemas/2007/complaint-reasons.cat"
    term="VIOLENCE"/>
</entry>

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

Saving and collecting videos

Favorite videos

A favorite video is a video that a user has explicitly flagged as a favorite. A user can view and edit his list of favorite videos on his account page, and a user's favorite videos are also publicly visible to other YouTube users.

The YouTube Data API enables users to add or delete favorite videos. To add or delete a favorite video, you must provide the YouTube user name for the authenticated user and the YouTube ID of the video being added or deleted.

Retrieving a user's favorite videos

This section explains how to retrieve a feed of a specific user's favorite videos. Note that some users may not have designated any favorite videos.

• To request a feed of the currently logged-in user's favorite videos, 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/favorites

• To request a feed of another user's favorite videos, 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/favorites

  In the URL above, you must replace the text username with the user's YouTube username.

The API response for a favorite videos feed is almost identical to a typical video feed or search results feed. (A sample video feed is shown in the Understanding video feeds and entries section of this document.) However, the favorite videos feed differs a typical video feed in the following ways:

• The value of the term attribute for each <category> tag in the feed will be http://gdata.youtube.com/schemas/2007#favorite rather than http://gdata.youtube.com/schemas/2007#video, identifying the feed contents as favorite videos.

• The <published> tag in a favorite videos feed entry identifies the time that the video was marked as a favorite and not the time that the video was published.

• The <author> tag in a favorite videos feed entry identifies the person who marked the video as a favorite. The <media:credit> tag identifies the owner of the video. In a typical videos feed, both tags identify the video owner.

• Each entry in a favorite videos feed contains a <link> tag for which the rel attribute value is related. You can use this link to navigate from the favorite video entry to the standard video entry for that video.

Adding a favorite video

The following request provides the URL and illustrates the XML format for adding a video to the logged-in user's list of favorite videos:

POST /feeds/api/users/default/favorites HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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">
  <id>VIDEO_ID</id>
</entry>

The following list identifies two common use cases for adding favorite videos and describes the API calls associated with each use case:

• A user watches a video and marks it as a favorite.

  1. This use case begins with an API request to obtain information about a specific video.

  2. After watching the video, the user elects to flag the video as a favorite video.

  3. Your application sends an API POST request to http://gdata.youtube.com/feeds/api/users/default/favorites to add the video to the list of the user's favorites.

• A user looks at a list of videos and marks one or more videos as favorites.

  1. This use case begins with a request to search for videos or to retrieve a particular video feed.

  2. The user selects one or more videos from the list – for example, the user could check a box next to each video.

  3. Your application loops through the selected videos and sends an API request to add each selected video as a favorite. Your application sends each request to http://gdata.youtube.com/feeds/api/users/default/favorites. The <id> tag in each request specifies the <yt:videoid> tag value for the corresponding video in the video feed from the previous step.

Deleting a favorite video

To delete a favorite video, send an HTTP DELETE request to the edit URL for the video entry:

<link rel='edit' type='application/atom+xml'
   href='http://gdata.youtube.com/feeds/api/users/USER_ID/favorites/FAVORITE_VIDEO_ID'>

Note: The ID that you use to delete a favorite video is not the <yt:videoid> for that video but a different value that uniquely associates the video with the user who marked it as a favorite. To delete a favorite video, always send the HTTP DELETE request to the edit URL that the favorite videos feed specifies for the video.

The following sample API request demonstrates how to delete a favorite video:

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

The following list identifies a common use case for deleting favorite videos and describes the API calls associated with that use case:

1. This use case begins with a request to retrieve a feed of the user's favorite videos.

2. The user selects one or more videos from the list – for example, the user could check a box next to each video.

3. Your application loops through the selected videos and sends an HTTP DELETE request to delete each selected video from the user's list of favorites. Your application would send each request to the edit URL for the corresponding favorite video.

Playlists

A playlist is a collection of videos that can be viewed sequentially and shared with other users. A playlist can contain up to 200 videos, and YouTube does not limit the number of playlists that each user creates. A user can view and edit his list of playlists on his account page. Playlists can be public or private. A playlist will be publicly visible to other users unless it has been explicitly been designated as a private playlist.

The YouTube Data API enables users to retrieve, create, modify and delete playlists.

Retrieving a user's playlists

This section explains how to retrieve a feed listing a specific user's playlists. Note that some users may not have created any playlists.

• To request a feed of the currently logged-in user's playlists, 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/playlists?v=2

• To request a feed of another user's playlists, 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/playlists?v=2

  In the URL above, you must replace the text username with the user's YouTube username.

The following XML shows a sample API response containing a playlists feed. The response contains a series of <entry> tags, with each entry describing a playlist. Each entry contains the playlist's title, description, author and modification date as well as a <content> tag that specifies the URL for retrieving the list of videos in the playlist.

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/&quot;Dk8DRn47eCp7ImA9WxRQGEk.&quot;'>
  <id>tag:youtube,2008:user:andyland74:playlists</id>
  <updated>2008-07-21T16:43:25.232Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#playlistLink'/>
  <title>Playlists of andyland74</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/users/andyland74?v=2'/>
  <link rel='alternate' type='text/html'
    href='http://www.youtube.com/profile_play_list?user=andyland74'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?alt=...'/>
  <author>
    <name>andyland74</name>
    <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
  </author>
  <generator version='2.0'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>3</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;Dk8DRn47eCp7ImA9WxRQGEk.&quot;'>
    <id>tag:youtube,2008:user:andyland74:playlist:8BCDD04DE8F771B2</id>
    <published>2007-11-04T17:30:27.000-08:00</published>
    <updated>2008-07-15T12:33:20.000-07:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>2008-07-15T12:33:20.000-07:00</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#playlistLink'/>
    <title>My New Playlist Title</title>
    <summary>My new playlist Description</summary>
    <content type='application/atom+xml;type=feed'
      src='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/view_play_list?p=8BCDD04DE8F771B2'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BCDD04DE8F771B2?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BCDD04DE8F771B2?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:countHint>9</yt:countHint>
  </entry>
  <entry>
    ...
  </entry>
  ...
</feed>

Retrieving a single playlist

As noted in the previous section, each entry in a user's playlists feed contains a <content> tag that specifies the URL for retrieving the list of videos in the playlist. The following example shows the URL for retrieving a playlist as that URL appears in a playlists feed entry:

<content type='application/atom+xml'
  src='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2?v=2'/>

The API response for a playlist feed is almost identical to a typical video feed or set of search results. However, a video entry in a playlist feed differs from a typical video entry in the following ways:

• Each playlist entry contains the <yt:position> tag, which specifies the place that the video appears in the playlist order. The <yt:position> tag is a subtag of the <entry> tag.

• If the user defined a custom title for the video, that title appears in the <atom:title> tag, and the video's original title appears in the <media:title> tag. Note that YouTube no longer enables users to set custom titles or descriptions for playlist entries.

• If the playlist owner defined a custom description for the video, that description will appear in a <summary> tag. The <summary> tag is a subtag of the <entry> tag. The <media:description> tag contains the video's original description. Note that YouTube no longer enables users to set custom titles or descriptions for playlist entries.

Adding a playlist

To create a playlist, you must provide a title and description for the playlist. The <yt:private> tag, which is optional, indicates whether the playlist will be publicly visible. (By default, playlists are visible to other users.)

The following request provides the URL and shows the XML format for creating a new playlist:

POST /feeds/api/users/default/playlists HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <title type="text">Sports Highlights Playlist</title>
  <summary>A selection of sports highlights</summary>
</entry>

The following list identifies two common use cases for creating a playlist and describes the API calls associated with each use case:

• A user watches a video and creates a new playlist that includes the video.

  1. This use case begins with an API request to obtain information about a specific video.

  2. After watching the video, the user clicks a link to add the video to a new playlist. Your application displays a form to allow the user to enter a title and description for the playlist.

  3. Your application sends an HTTP POST request to http://gdata.youtube.com/feeds/api/users/default/playlists to create the playlist. The API request specifies the playlist title and description that the user entered.

  4. Your application sends an additional API request to add the selected video to the playlist.

• A user looks at a list of videos and selects one or more videos to add to a new playlist.

  1. This use case begins with an API request to search for videos or to retrieve a particular video feed.

  2. The user selects one or more videos from the list to add to a new playlist – for example, the user could check a box next to each video.

  3. Your application displays a form to allow the user to enter a title and description for the playlist.

  4. Your application sends an HTTP POST request to http://gdata.youtube.com/feeds/api/users/default/playlists to create the playlist using the title and description entered by the user.

  5. Your application then loops through the selected videos and sends an additional API request to add each selected video to the playlist.

Updating a playlist

The API request for updating a playlist allows the user to update the title, description and public/private status of that playlist. The API defines additional requests for adding a video to a playlist, updating a video in a playlist or removing a video from a playlist.

The following sample request provides the URL and illustrates the XML format for modifying a playlist. Please note that the XML submitted in the request has the same format as a request to create a playlist. However, this request is an HTTP PUT request and the API URL must specify the ID of the playlist being updated.

PUT /feeds/api/users/USER_ID/playlists/PLAYLIST_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <title type="text">Sports Highlights Playlist</title>
  <summary>A selection of sports highlights</summary>
</entry>

The following use case describes a scenario where a user would modify a playlist:

1. This use case begins with a request to retrieve a feed of the user's playlists.

2. The user selects a playlist from the list and clicks a link to update the playlist.

3. Your application displays a form that lets the user update the title and description of the playlist.

4. Your application then sends an HTTP PUT request to the playlist's edit URL to update the playlist.

Adding a video to a playlist

To add a video to a playlist, you will send an API request that identifies the unique ID that YouTube assigned to the playlist as well as the unique ID that YouTube assigned to the video. By default, the newly added video will be added to the end of a playlist. To insert a video into a different spot in the playlist, you must first add the video. Then you must update the playlist entry using the <yt:position> tag to adjust the order in which the video appears in the playlist.

The following request provides the URL and illustrates the XML format for adding a video to a playlist:

POST /feeds/api/playlists/PLAYLIST_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <id>VIDEO_ID</id>
</entry>

The following list identifies two common use cases for adding a video to a playlist and describes the API calls associated with each use case:

• A user watches a video and adds the video to a playlist.

  1. This use case begins with an API request to obtain information about a specific video.

  2. After watching the video, the user clicks a link to add the video to a playlist.

  3. Your application submits an API request to retrieve a list of the user's playlists and then displays the list.

  4. The user selects an existing playlist and your application sends a POST request to the edit URL for that playlist to add the selected video to the playlist.

• A user looks at a list of videos and selects one or more videos to add to a playlist.

  1. This use case begins with an API request to search for videos or to retrieve a particular video feed.

  2. The user selects one or more videos from the list to add to a playlist – for example, the user could check a box next to each video.

  3. Your application submits an API request to retrieve a list of the user's playlists and then displays the list.

  4. The user selects a playlist. Your application loops through the selected videos and sends a POST request to the edit URL for that playlist to add each selected video to the playlist. In each API request, the <id> tag specifies the <yt:videoid> for the video you are adding.

Note: Playlists contain a maximum of 200 videos. As such, you will not be able to add a video to a playlist that already contains that many videos.

Editing video information in a playlist

A user can update the order in which a video appears in a playlist entry. The following sample request illustrates the XML format for modifying a playlist entry. Please note that the XML submitted in the request has the same format as a request to create a playlist entry. However, this request is an HTTP PUT request and the API URL, which specifies the ID of the playlist entry being updated, is different.

PUT /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <yt:position>2</yt:position>
</entry>

The following use case describes a scenario where a user would modify a playlist entry:

1. This use case begins with a request to retrieve a specific playlist. Please note that when you retrieve a list of videos in a playlist, each <entry> tag encapsulates information about a single video in the playlist. To update a playlist entry, send an HTTP PUT request to the edit URL for that entry.

2. Your application displays the list of playlist entries and presents an option for the user to rearrange the order in which YouTube plays the videos in the playlist.

3. The user reorders the playlist entries and clicks a link to update the playlist.

4. Your application loops through the entries in the playlist to update the value of the <yt:position> tag for each entry. Your application will need to send one API request for each entry that it is updating. Each API request must be sent to the playlist entry's edit URL.

Removing a video from a playlist

The following sample API request demonstrates how to delete a playlist entry. Please note that when you retrieve a list of videos in a playlist, each <entry> tag encapsulates information about a single video in the playlist. To delete a playlist entry, send an HTTP DELETE request to the edit URL for that entry.

DELETE /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

The following list describes a common use case for deleting a playlist entry:

1. This use case begins with a request to retrieve a specific playlist.

2. Your application displays the list of the entries in the playlist with a checkbox next to each entry so that the user can check the entries that will be deleted.

3. Your application loops through the selected entries and sends an HTTP DELETE request for each entry that is being deleted from the playlist. Your application would send each API request to the edit URL for the playlist entry being deleted.

Deleting a playlist

Deleting a playlist removes a playlist altogether. The following sample API request demonstrates how to delete a playlist:

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

The following list describes a common use case for deleting a playlist:

1. This use case begins with a request to retrieve a feed of the user's playlists.

2. The user selects a playlist from the list to delete and you send an API request to delete the playlist.

Subscriptions

A subscription refers to an entity that notifies a user when new videos are uploaded. Users can subscribe to another user's channel, another user's list of favorites, a playlist or a keyword tag. A user can view and edit his list of subscriptions on his account page, and a user's subscriptions are also publicly visible to other YouTube users.

The YouTube Data API enables a user to create or delete subscriptions.

Retrieving a user's subscriptions

This section explains how to retrieve a feed listing a specific user's subscriptions. Note that some users may not have created any subscriptions.

• To request a feed of the currently logged-in user's subscriptions, 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/subscriptions?v=2

• To request a feed of another user's subscriptions, 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/subscriptions?v=2

  In the URL above, you must replace the text username with the user's YouTube username.

A subscriptions feed contains a series of <entry> tags, with each entry describing a subscription. Users can subscribe to YouTube channels, other users' lists of favorite videos, playlists, and keyword tags. Each entry in the subscription feed contains a <category> tag for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. The value of the term attribute for that <category> tag indicates whether the subscription is to a channel, a list of favorite videos, a playlist, or a keyword tag.

• If the feed entry describes a channel subscription, the <category> tag's term attribute will have a value of channel. The entry will also contain the <yt:username> element, which specifies the owner of the channel.

• If the feed entry describes a subscription to another user's list of favorite videos, the <category> tag's term attribute will have a value of favorites. The entry will also contain the <yt:username> element, which specifies the user whose favorite videos are being subscribed to.

• If the feed entry describes a playlist subscription, the <category> tag's term attribute will have a value of playlist. The entry will also contain the <yt:playlistId> and <yt:playlistTitle> tags, which identify the playlist as well as the playlist's display title. In addition, the <yt:username> and <media:thumbnail> tags will identify the YouTube user who created the playlist and the thumbnail image for the playlist, respectively.

• If the feed entry describes a keyword subscription, the <category> tag's term attribute will have a value of query. The entry will also contain the <yt:queryString> element, which specifies the keyword that is the subject of the subscription.

The following XML shows a sample API response containing a subscriptions feed. The response contains a series of four entries. The entries show a channel, keyword, playlist and favorite videos subscription. The <content> tag in each entry specifies the URL for retrieving videos in that subscription.

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/&quot;DU4DRX47eCp7ImA9WB9RFEU.&quot;'>
  <id>tag:youtube,2008:user:andyland74:subscriptions</id>
  <updated>2008-07-21T17:10:32.855Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#subscription'/>
  <title>Subscriptions of andyland74</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/users/andyland74?v=2'/>
  <link rel='alternate' type='text/html'
    href='http://www.youtube.com/profile_subscriptions?user=andyland74'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?alt=...'/>
  <author>
    <name>andyland74</name>
    <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
  </author>
  <generator version='2.0'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>3</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;DU4DRX47eCp7ImA9WB9RFEU.&quot;'>
    <id>tag:youtube,2008:user:andyland74:subscription:1BF1kEXir4w</id>
    <published>2007-10-15T15:39:34.000-07:00</published>
    <updated>2007-10-15T15:39:34.000-07:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2007-10-15T15:39:34.000-07:00</app:edited>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='channel'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <title>Videos published by : littlet2009</title>
    <content type='application/atom+xml;type=feed'
      src='http://gdata.youtube.com/feeds/api/users/littlet2009/uploads?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/profile_videos?user=littlet2009'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/1BF1kEXir4w?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/1BF1kEXir4w?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:username>littlet2009</yt:username>
  </entry>
  <entry gd:etag='W/&quot;AkQFRH47eCp7ImA9WxZQF00.&quot;'>
    <id>tag:youtube,2008:user:andyland74:subscription:XFb0XbMIERw</id>
    <published>2008-02-29T10:40:27.000-08:00</published>
    <updated>2008-02-29T10:40:27.000-08:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2008-02-29T10:40:27.000-08:00</app:edited>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='query'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <title>Videos matching : Dog skateboarding</title>
    <content type='application/atom+xml;type=feed'
      src='http://gdata.youtube.com/feeds/api/videos?q=Dog+skateboarding&amp;v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/results?search_query=Dog+skateboarding'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/XFb0XbMIERw?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/XFb0XbMIERw?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:queryString>Dog skateboarding</yt:queryString>
  </entry>
  <entry gd:etag='W/&quot;CkYNRH47eCp7ImA9WxRVGUg.&quot;'>
    <id>tag:youtube,2008:user:andyland74:subscription:Y6FAbqUmEsX</id>
    <published>2008-02-29T11:40:27.000-08:00</published>
    <updated>2008-02-29T11:40:27.000-08:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2008-02-29T11:40:27.000-08:00</app:edited>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='playlist'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <title>Doritos You Make It We Play It</title>
    <content type='application/atom+xml;type=feed'
      src='http://gdata.youtube.com/feeds/api/playlists/C344114E1E41B2FA?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/view_play_list?p=C344114E1E41B2FA'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/Y6FAbqUmEsX?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/Y6FAbqUmEsX?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:playlistTitle>Doritos You Make It We Play It</yt:playlistTitle>
    <yt:username>DoritosYouMakeIt</yt:username>
    <yt:playlistId>C344114E1E41B2FA</yt:playlistId>
    <media:thumbnail url='http://i4.ytimg.com/vi/s_J2ww-ZAzw/default.jpg'/>
  </entry>
  <entry gd:etag='W/&quot;C08FRn47eCp7ImA9WxZXEEg.&quot;'>
    <id>tag:youtube,2008:user:andyland74:subscription:OsaQBQ7TbqY</id>
    <published>2008-02-26T10:50:17.000-08:00</published>
    <updated>2008-02-26T10:50:17.000-08:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2008-02-26T10:50:17.000-08:00</app:edited>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='favorites'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <title>Favorites of : kemlye1</title>
    <content type='application/atom+xml;type=feed'
      src='http://gdata.youtube.com/feeds/api/users/kemlye1/favorites?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/profile_favorites?user=kemlye1'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/OsaQBQ7TbqY?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/OsaQBQ7TbqY?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:username>kemlye1</yt:username>
  </entry>
</feed>

Retrieving new subscription videos

This section explains how to retrieve a feed listing a specific user's new subscription videos. The feed returns the same list of videos that appears on the user's Subscriptions page under the New Videos subheading.

• To request a feed of the currently logged-in user's new subscription videos, send an authenticated HTTP GET request to the following URL:

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

• To request a feed of another user's subscriptions, 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/newsubscriptionvideos

  In the URL above, you must replace the text username with the user's YouTube username.

In addition, a user profile entry contains a <gd:feedLink> tag that contains the URL you would use to retrieve a user's new subscription videos feed as shown in the following sample tag:

<gd:feedLink
  rel='http://gdata.youtube.com/schemas/2007#user.newsubscriptionvideos'
  href='http://gdata.youtube.com/feeds/api/users/andyland74/newsubscriptionvideos'/>

The API response for this query is a videos feed that has the same format as the sample response in the Understanding video feeds and entries section of this document.

Adding a subscription

To create a subscription, you must identify the YouTube user name for the authenticated user who is creating the subscription. You must also use the <category> tag to indicate whether the user is subscribing to a channel, list of favorites, playlist or keyword.

• For a channel subscription or favorite videos subscription, the <yt:username> tag identifies the username associated with the channel or favorites list to which the authenticated user is subscribing.
• For a playlist subscription, the <yt:playlistId> tag identifies the playlist to which the user is subscribing.
• For a keyword search subscription, the <yt:queryString> tag identifies the keyword associated with the new subscription.

The following requests illustrate the XML format for creating different types of subscriptions:

Subscribing to a channel:

POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="channel"/>
    <yt:username>andyland74</yt:username>
</entry>

Subscribing to another user's list of favorites:

POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="favorites"/>
    <yt:username>andyland74</yt:username>
</entry>

Subscribing to a playlist:

POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="playlist"/>
    <yt:playlistId>D8AE0D634D86A94F</yt:playlistId>
</entry>

Subscribing to a keyword:

POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="query"/>
    <yt:queryString>Dog Skateboarding</yt:queryString>
</entry>

The following list identifies common use cases for creating subscriptions and describes the API calls associated with each use case:

• A user watches a video and subscribes to the video owner's channel.

  1. This use case begins with an API request to retrieve information about a specific video.

  2. After watching the video, the user clicks a link to subscribe to the video owner's channel.

  3. Your application sends an API request to http://gdata.youtube.com/feeds/api/users/default/subscriptions to create the subscription. In the XML entry in your request, the <yt:username> tag value specifies the video owner's YouTube username and the <category> tag's term attribute has a value of channel.

• A user watches a video and then subscribes to all videos matching a keyword associated with that video.

  1. This use case begins with an API request to search for videos or to retrieve a particular video feed.

  2. The user clicks on a video in the result set from step 1, prompting a second API request to retrieve information about that specific video. In this step, the user links to a page to watch the selected video.

  3. The page where the user watches the video displays a list of keywords associated with the video and allows the user to subscribe to individual keywords. The user clicks a link to subscribe to a keyword.

  4. Your application sends an API request to http://gdata.youtube.com/feeds/api/users/default/subscriptions to create the subscription. In the XML entry in your request, the <yt:queryString> tag's value is the keyword. The <category> tag's term attribute has a value of query.

Deleting a subscription

The following sample API request demonstrates how to delete a subscription:

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

The following list identifies a common use case for deleting a subscription:

A user looks at his list of subscriptions and removes one or more from the list.

1. This use case begins with a request to retrieve a feed of the user's subscriptions.

2. Your application displays a list of the user's subscriptions, and the user selects one or more subscriptions to delete.

3. Your application loops through the selected subscriptions and sends an HTTP DELETE request to delete each one from the user's list of subscriptions. Each API request is sent to the edit URL for the subscription.

Video Recommendations

A user's recommendations feed contains videos that may appeal to the user. YouTube selects recommendations for a user based on an algorithm that considers signals from a variety of sources that include the user's favorite videos, recently added playlist videos, recently watched videos, ratings and more.

To retrieve a feed containing recommendations for a logged-in user, send an authenticated HTTP GET request to the following URL.

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

Note: For this request, you must provide an authentication token in the Authorization HTTP request header. This requirement ensures that recommendations are tailored to the right user, and the authentication token enables YouTube to identify the user.

The recommendations feed is a video feed as described in the Understanding video feeds and entries section. The feed contains up to eight videos but may include fewer videos if the user has not performed actions that influence the recommendations feed content.

YouTube generates and caches recommendations for a user, and then regenerates recommendations when the cache expires or a threshold fraction of the feed has been viewed.

Enabling user interaction

User profiles

A user profile contains information about a user, such as the user's hobbies, occupation, or favorite books, music and movies. Any personal information that appears in a user profile feed will have been entered by that user for publication on YouTube. The YouTube Data API allows you to retrieve user profiles.

Retrieving a user's profile

This section explains how to retrieve an entry containing information about a specific user's profile.

• To request the currently logged-in user's profile, 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

• To request another user's profile, 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

  In the URL above, you must replace the text username with the user's YouTube username.

An API response to a request for a user profile contains a single <entry> tag. The profile entry contains the following information:

• Several tags in the yt namespace identify personal information that the user added to his YouTube profile, such as his age, favorite books, occupation or school.

• The <media:thumbnail> tag contains a picture that the user has uploaded to his profile or, if no such picture exists, a default image.

• The <yt:statistics> tag contains statistics about the user, inlcuding the number of people who have viewed the user's profile, the number of videos the user has watched and the number of people who subscribe to the user's uploaded videos.

• A series of <gd:feedLink> tags provide URLs for retrieving the user's uploaded videos, favorite videos, playlists, subscriptions and contacts.

The following XML shows a sample API response containing a user profile:

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/'
    xmlns:batch='http://schemas.google.com/gdata/batch'
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/&quot;DkMGRX47eCp7ImA9WxRQGU0.&quot;'>
  <id>tag:youtube,2008:user:andyland74</id>
  <published>2006-10-16T00:09:45.000-07:00</published>
  <updated>2008-02-26T11:48:21.000-08:00</updated>
  <category
    scheme='http://gdata.youtube.com/schemas/2007/channeltypes.cat'
    term='Standard'/>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#userProfile'/>
  <title type='text'>andyland74 Channel</title>
  <link rel='http://gdata.youtube.com/schemas/2007#featured-video'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/PlVJ88-zqkI?v=2'/>
  <link rel='related' type='text/html'
    href='http://andyland74.example.com'/>
  <link rel='alternate' type='text/html'
    href='http://www.youtube.com/profile?user=andyland74'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
  <author>
    <name>andyland74</name>
    <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
  </author>
  <yt:firstName>33</yt:firstName>
  <yt:lastName>Jones</yt:lastName>
  <yt:aboutMe>My favorite number is 33.</yt:aboutMe>
  <yt:age>33</yt:age>
  <yt:username>andyland74</yt:username>
  <yt:books>Catch-22</yt:books>
  <yt:gender>m</yt:gender>
  <yt:company>Google</yt:company>
  <yt:hobbies>Testing YouTube APIs</yt:hobbies>
  <yt:hometown>Philadelphia, PA</yt:hometown>
  <yt:location>Boston, MA 02043, US</yt:location>
  <yt:movies>Aqua Teen Hungerforce</yt:movies>
  <yt:music>Elliott Smith</yt:music>
  <yt:relationship>taken</yt:relationship>
  <yt:occupation>Technical Writer</yt:occupation>
  <yt:school>University of North Carolina</yt:school>
  <media:thumbnail url='http://i.ytimg.com/vi/YFbSxcdOL-w/default.jpg'/>
  <yt:statistics viewCount='9' videoWatchCount='21' subscriberCount='1'
    lastWebAccess='2008-02-25T16:03:38.000-08:00'/>
  <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.favorites'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/favorites?v=2' countHint='4'/>
  <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.contacts'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?v=2' countHint='1'/>
  <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.inbox'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox?v=2' countHint='0'/>
  <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.playlists'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?v=2'/>
  <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.subscriptions'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?v=2' countHint='4'/>
  <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/uploads?v=2' countHint='1'/>
  <gd:feedLink
    rel='http://gdata.youtube.com/schemas/2007#user.newsubscriptionvideos'
    href='http://gdata.youtube.com/feeds/users/andyland74/newsubscriptionvideos?v=2'/>
</entry>

Contacts

The YouTube Data API enables a user to add, update or delete contacts.

Retrieving a user's contacts

This section explains how to retrieve a feed containing a list of a specific user's contacts.

• To request the currently logged-in user's contact list, 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/contacts?v=2

• To request another user's contact list, 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/contacts?v=2

  In the URL above, you must replace the text username with the user's YouTube username.

An API response to a request for a contact list contains a series of <entry> tags. Note that the API returns a maximum of 100 contacts for any given contact feed request even if more contacts match the request parameters. Each entry in a contact feed contains the following information for an individual contact:

• The edit URL, which you would use to update or delete the contact. The Identifying feeds related to a feed entry section explains how to identify the edit URL for a feed entry.

• The <category> tag indicates whether the contact is a friend or family.

• The <yt:username> tag specifies the contact's YouTube username.

• The <yt:status> tag indicates the contact's status. This tag only appears if you are retrieving the contacts of the currently authenticated user. This tag will have one of the following values:

  • accepted - The feed owner and the contact have marked each other as friends.
  • requested - The contact has asked to be added to the authenticated user's contact list, but the request has not yet been accepted (or rejected).
  • pending - The authenticated user has asked to be added to the contact's contact list, but the request has not yet been accepted or rejected.

The following XML shows a sample API response containing a contact:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/&quot;Dk4MQX05fyp7ImA9WxRQGUk.&quot;'>
  <id>tag:youtube,2008:user:andyland74:contacts</id>
  <updated>2008-07-21T17:34:54.371Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#friend'/>
  <title>Contacts of andyland74</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='alternate' type='application/atom+xml'
    href='http://www.youtube.com/profile_friends?user=andyland74'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?alt=...'/>
  <author>
    <name>andyland74</name>
    <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
  </author>
  <generator version='2.0'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>4</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;Dk4MQX05fyp7ImA9WxRQGUk.&quot;'>
    <id>tag:youtube,2008:user:andyland74:contact:davydanciu</id>
    <published>2007-10-17T10:45:41.000-07:00</published>
    <updated>2008-07-21T17:34:54.370Z</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2008-07-21T17:34:54.370Z</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#friend'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/contact.cat'
      term='Friends'/>
    <title>davydanciu</title>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/davydanciu?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/profile?user=davydanciu'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts/davydanciu?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts/davydanciu?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:username>davydanciu</yt:username>
    <yt:status>accepted</yt:status>
  </entry>
  <entry>
    ...
  </entry>
  ...
</feed>

Adding a contact

To add a contact, you will send an API request that identifies two users: the user who is adding the contact and the contact being added. The request can also use the <category> tag to specify whether the contact is being added to the user's list of family or friends. If the request does not specify a category for the contact, then the contact will appear in the user's list of contacts but will not be placed into either the family or friends category.

The following request provides the URL and illustrates the XML format for adding a contact:

POST /feeds/api/users/default/contacts HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <category scheme="http://gdata.youtube.com/schemas/2007/contact.cat"
    term="Friends"/>
  <yt:username>CONTACT_ID</yt:username>
</entry>

The following list identifies a common use case for adding a contact:

• A user watches a video and then adds the video owner as a friend.

  1. This use case begins with a request to retrieve information about a specific video.

  2. After watching the video, the user clicks a link to view the video owner's profile.

  3. Your application submits an API request to retrieve the video owner's profile.

  4. The page on your site that displays information about the video owner displays a link to add the video owner as a friend. If the user clicks this link, then your application submits an API request to http://gdata.youtube.com/feeds/api/users/default/contacts to create the contact. In the request, the <yt:username> tag identifies the YouTube user who is being added as a contact. In addition, the <category> tag's term attribute indicates whether the contact is a friend (term="Friends") or family (term="Family").

Updating a contact

To update a contact, submit an HTTP PUT request to the edit url for that contact. The XML excerpt below shows how the edit URL appears in a contact entry:

<entry>
  <id>http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID</id>
  ...
  <link rel='edit' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID'/>
  ...
</entry>

The API enables a user to update a contact in two ways:

• A user can accept a contact that has a status of requested. To update a contact in this fashion, in your API request, set the value of the <yt:status> tag to accepted as shown in the sample request below. (Similarly, to reject a contact, set the value of the <yt:status> tag to rejected.

• Contacts can be categorized as friends or as family. You can use the API to recategorize contacts into either of these groups. If you categorize a contact as a friend, then the <category> tag's value must be Friends. If you categorize a contact as family, then the <category> tag's value must be Family.

The following sample request demonstrates how to update a contact. In the example, the contact is being accepted and classified as family. Please note that in the example, the variable USER_ID refers to the user who is adding the contact and the variable CONTACT_ID refers to the contact being added.

PUT /feeds/api/users/USER_ID/contacts/CONTACT_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <category scheme="http://gdata.youtube.com/schemas/2007/contact.cat"
      term="Family"/>
  <status>accepted</status>
</entry>

The following use case describes a scenario where a user would modify a contact:

1. This use case begins with a request to retrieve a user's list of contacts. Each <entry> tag in the API response encapsulates information about a single contact. To update or delete a contact, send an API request to the edit URL for that contact entry.

2. Your application displays the list of contacts as well as a select menu next to each contact allowing the user to recategorize the contact as family or as a friend. Your application also lets users accept or reject contacts that have a status of either pending or requested.

3. The user modifies one or more contacts and submits his changes.

4. Your application loops through the contacts and sends an HTTP PUT request to update each modified contact. Your application would submit each API request to the edit URL for the contact being updated.

Deleting a contact

The following sample API request demonstrates how to delete a contact.

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

The following list describes a common use case for deleting a contact:

1. As with the use case for modifying a contact, this use case begins with a request to retrieve a user's list of contacts.

2. Your application displays the list of contacts as well as a checkbox next to each contact allowing the user to delete that contact.

3. The user checks one or more contacts and submits his changes.

4. Your application loops through the contacts and sends an HTTP DELETE request to delete each selected contact. Your application would send each API request to the edit URL for the corresponding contact.

Messages and video sharing

Video messages enable YouTube users to easily share videos with other YouTube users. On the YouTube website, a video page displays a link, allowing the user to share that video with one or more people from the user's contact list or with other YouTube users.

The YouTube Data API enables you to retrieve video messages sent to the currently logged-in user's inbox, send a video message from that user to another user, and delete video messages from that user's inbox. Note that the API does not retrieve other types of messages in the user's inbox.

Retrieving messages from a user's inbox

To retrieve a feed containing a list of the messages in the currently logged-in user's inbox, 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. This restriction ensures that a user can only retrieve messages from her own inbox. The authentication token enables YouTube to identify the user.

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

An API response to a request for an inbox feed contains a series of <entry> tags. Each entry contains information about a video message sent to the user, and inbox feed entries are very similar to entries in a video feed. Inbox entries contain the following key differences:

• The <name> tag identifies the sender of the message rather than the owner of the video being sent.

• The <title> tag contains the subject of the message rather than the video title. The video title still appears in the <media:title> tag.

• The <summary> tag is included in an inbox feed entry. The tag contains the text of the message.

• The <content> tag contains the text of the message. This tag contains the same value as the <summary> tag.

• The <published> tag specifies the date and time that the message was sent rather than the date and time that a video was uploaded.

• The <link> tag that has a rel attribute value of alternate specifies the URL for the video sent in the message. The user can watch the video at that URL.

• The <link> tag that has a rel attribute value of edit specifies the edit URL for the message. You would send an HTTP DELETE request to this URL to delete the message.

The following XML shows a sample API response containing an inbox feed:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/&quot;C0QHQ347eCp7ImA9WxdQEU4.&quot;'>
  <id>tag:youtube,2008:user:andyland74:inbox</id>
  <updated>2008-07-21T17:54:30.236Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#videoMessage'/>
  <title>Inbox of andyland74</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='alternate' type='text/html'
    href='http://www.youtube.com/my_messages?folder=inbox&amp;filter=videos'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox?alt=...'/>
  <author>
    <name>andyland74</name>
    <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
  </author>
  <generator version='2.0'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>1</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;C0QHQ347eCp7ImA9WxdQEU4.&quot;'>
    <id>tag:youtube,2008:user:andyland74:inbox:D_uaXzLRX1U</id>
    <published>2008-06-10T13:55:32.000-07:00</published>
    <updated>2008-06-10T13:55:32.000-07:00</updated>
    <app:edited
  xmlns:app='http://www.w3.org/2007/app'>2008-06-10T20:55:32.000Z</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#videoMessage'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/keywords.cat'
      term='surfing'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/categories.cat'
      term='People' label='People &amp; Blogs'/>
    <title>andyland74sFriend sent you a video!</title>
    <summary>Check out this video!</summary>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/watch?v=jXE6G9CYcJs'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.responses'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/responses?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/ratings?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.complaints'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/complaints?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#mobile'
      type='text/html' href='http://m.youtube.com/details?v=jXE6G9CYcJs'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.related'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/related?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs?v=2'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox/ffb9a5f32cd5f55?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox/ffb9a5f32cd5f55?v=2'/>
    <author>
      <name>andyland74sFriend</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74sFriend</uri>
    </author>
    <media:group>
      <media:title type='plain'>Learning the ABCs</media:title>
      <media:description type='plain'>
        A great method for teaching kids the alphabet.
      </media:description>
      <media:keywords>alphabet, teaching, children</media:keywords>
      <yt:duration seconds='202'/>
      <yt:videoid>jXE6G9CYcJs</yt:videoid>
      <media:credit role='uploader' scheme='urn:youtube'>andyland74sFriend</media:credit>
      <media:category label='Education'
        scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>
        Education</media:category>
      <media:content url='http://www.youtube.com/v/jXE6G9CYcJs'
        type='application/x-shockwave-flash' medium='video' isDefault='true'
        expression='full' duration='202' yt:format='5'/>
      <media:content
        url='rtsp://rtsp2.youtube.com/ChoLENySANFEgGDA==/0/0/0/video.3gp'
        type='video/3gpp' medium='video' expression='full'
        duration='202' yt:format='1'/>
      <media:content
        url='rtsp://rtsp2.youtube.com/ChoLENySARFEgGDA==/0/0/0/video.3gp'
        type='video/3gpp' medium='video' expression='full'
        duration='202' yt:format='6'/>
      <media:player url='http://www.youtube.com/watch?v=jXE6G9CYcJs'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/2.jpg'
        height='97' width='130' time='00:01:41'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/1.jpg'
        height='97' width='130' time='00:00:50.500'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/3.jpg'
        height='97' width='130' time='00:02:31.500'/>
      <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/0.jpg'
        height='240' width='320' time='00:01:41'/>
    </media:group>
    <yt:statistics viewCount='286355' favoriteCount='201'/>
    <gd:rating min='1' max='5' numRaters='877' average='3.88'/>
    <gd:comments>
      <gd:feedLink
        href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/comments'
        countHint='1088'/>
    </gd:comments>
  </entry>
</feed>

Sending a video message

To send a message, you will send an authenticated HTTP POST request that identifies the user to whom the message is being sent. The XML sent in the request body specifies the <yt:videoid> of the video being sent and the text of the message.

The following sample request demonstrates how to send a video through the API:

POST /feeds/api/users/MESSAGE_RECIPIENT_USER_ID/inbox HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
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:yt="http://gdata.youtube.com/schemas/2007">
  <id>Qm6znjThL2Y</id>
  <summary>sending a message from the api</summary>
</entry>

Note: A user can only send videos to users in his contact list.

The following steps describe a common use case for sending a message:

1. This use case begins with a request to retrieve information about a specific video.

2. After watching the video, the user clicks a link to share the video.

3. Your application submits a request to retrieve the contact list for the currently authenticated user.

4. Your application displays a form that allows the user to select one or more contacts to send the video to. The form could also display a text area to allow the user to write a message to those contacts.

5. After the user submits the completed form, your application loops through the list of selected contacts and submits an API request to send the video to each user.

Deleting a message

The following sample API request demonstrates how to delete a message:

DELETE /feeds/api/users/default/inbox/MESSAGE_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

The following steps describe a common use case for deleting a message:

1. This use case begins with a request to retrieve the video messages in a user's inbox.

2. Your application displays the list of video messages as well as a checkbox next to each message allowing the user to delete that message from her inbox.

3. The user checks one or more messages and submits her changes.

4. Your application loops through the messages and sends an HTTP DELETE request to delete each selected message. Your application would send each API request to the edit URL for the corresponding message.

Activity feeds

Activity feeds list actions that a particular user or set of users has taken on the YouTube site. The API enables you to retrieve two types of activity feeds:

• A user activity feed identifies actions taken by one or more users who are specified in the API request.
• A friend activity feed identifies actions that an authenticated user's friends have recently taken on the YouTube site.

Activity feeds list the following user actions:

• Rating a video
• Sharing a video
• Marking a video as a favorite
• Commenting on a video
• Uploading a video
• Adding a friend
• Creating a subscription to a channel

The following sections explain how to retrieve and process activity feeds:

Retrieving an activity feed

An activity feed contains a series of <entry> tags, with each entry describing a particular event, like someone rating a video or creating a subscription. An event should appear in activity feeds within 30 minutes and may show up much sooner than that. Each feed entry contains the following elements that combine to identify the event:

• Each entry contains an <author> tag, which encapsulates information about the user associated with the event. (Specifically, the <name> tag within the <author> tag identifies the user's username.)

• Each entry contains a <category> tag for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/userevents.cat. That tag's term attribute identifies the type of event that the entry describes. The following list identifies possible values for the term attribute. The list also identifies additional tags that will appear for each type to identify the specific event associated with the entry.

  • video_rated – A user rated a video. For this type of event, an entry will also contain the following tags:
    

    • The <yt:videoid> tag identifies the rated video.
    • The <gd:rating> tag identifies the rating given to the video.

  • video_shared – A user shared a video. For this type of event, an entry will also contain the following tag:
    

    • The <yt:videoid> tag identifies the shared video.

  • video_favorited – A user marked a video as a favorite. For this type of event, an entry will also contain the following tag:
    

    • The <yt:videoid> tag identifies the video that was marked as a favorite.

  • video_commented – A user commented on a video. For this type of event, an entry will also contain the following tags:
    

    • The <yt:videoid> tag identifies the video to which the comment was added.
    • The <link> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007#comments contains a link to the feed URL for the comment that was added.
    • The <link> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007#video contains a link to the feed URL for the video to which the comment was added.

  • video_uploaded – A user uploaded a video. For this type of event, an entry will also contain the following tag:
    

    • The <yt:videoid> tag identifies the shared video.

  • friend_added – A user added a friend. For this type of event, an entry will also contain the following tag:
    

    • The <yt:username> tag identifies the user who was added as a friend.

  • user_subscription_added – A user added a subscription. For this type of event, an entry will also contain the following tag:
    

    • The <yt:username> tag identifies the user who owns the channel that was subscribed to. Only channel subscriptions are included in activity feeds.

Sample activity feed

User activity feeds and friend activity feeds have the same structure, though the tags included within each feed entry varies slightly as described in the Retrieving an activity feed section.

The XML below shows a sample user activity feed for the following API request.

http://gdata.youtube.com/feeds/api/events?author=tayzonzay&v=2

The XML contains one entry, which identifies an instance of a video being marked as a favorite video.

<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"D0EGSH47eCp7ImA9WxRVGEg.&quot;'>
  <id>tag:youtube.com,2008:events</id>
  <updated>2009-01-28T09:13:49.000Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#userEvent'/>
  <title>Activity of tayzonzay</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/events?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/events/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/events?author=tayzonzay&start-index=...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/events?alt=atom-service&v=2'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>12</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/"D0EGSH47eCp7ImA9WxRQQEg."'>
    <id>tag:youtube.com,2008:event:VGF5Wm9uZGF5MzEyaIl2MTMxOTcxMDk3NzQ5MzM%3D</id>
    <updated>2009-01-16T09:13:49.000Z</updated>
    <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
      term='video_favorited'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#userEvent'/>
    <title>tayzonzay has favorited a video</title>
    <link rel='alternate' type='text/html' href='http://www.youtube.com'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/z3U0kuLH974?v=2'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/events/VGF5Wm9uZGF5MzEyaIl2MTMxOTcxMDk3NzQ5MzM%3D?v=2'/>
    <author>
      <name>tayzonzay</name>
      <uri>http://gdata.youtube.com/feeds/api/users/tayzonzay</uri>
    </author>
    <yt:videoid>z3U0kuLH974</yt:videoid>
  </entry>
</feed>

User activity feeds

User activity feeds list user events that occurred within the last 60 days. You can request a user activity feed for a single user or you can retrieve a single feed that lists actions from multiple users. You can also use the published-min and published-max parameters to specify that the API response should only contain events that occurred between specific times, such as events that occurred within the previous day or week. However, you cannot use the API to retrieve events that occurred more than 60 days before the time of your request.

Please see the Google Data APIs Protocol Reference for more information about these parameters.

The YouTube API provides two ways to retrieve a user activity feed. If you need to track updates for a large number of user activity feeds, consider using the Simple Update Protocol, which is supported if you use the first of the two retrieval methods described below.

• To retrieve a single user's activity feed, send a request to the following URL. Replace the text username with the user's YouTube username.

  http://gdata.youtube.com/feeds/api/users/username/events?v=2

  You can also retrieve the user activity feed for the currently logged-in user by sending an HTTP GET request to the following URL. Note that for this request, you need to provide an authentication token in the Authorization HTTP request header, which enables YouTube to identify the user.

  http://gdata.youtube.com/feeds/api/users/default/events?v=2

• To retrieve a user activity feed that combines the actions of multiple users, send an HTTP request to the following URL. (You can also use this method to retrieve a user activity feed for a single user.) Your request must identify your developer key. In the request, set the author parameter value to a comma-separated list of up to 20 YouTube usernames. The API response will contain activities performed by any of those users.

  http://gdata.youtube.com/feeds/api/events?author=usernames
  

  Note that this feed URL does not support the Simple Update Protocol.

Friend activity feeds

To retrieve a friend activity feed for the logged-in user's friends, send an HTTP request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. This restriction ensures that a user can only retrieve the friend activity feed for her own friends.

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

Friend activity feeds contain events that occurred within the last 14 days. Note that these feeds only contain events for contacts who are explicitly labeled as being in the user's Friends group, and they do not contain events for all of the user's contacts. As with user activity feeds, you can use the published-min and published-max parameters to specify that the API response should only contain events that occurred between specific times, such as events that occurred within the previous day or week. However, you cannot use the API to retrieve events that occurred more than 14 days before the time of your request. Please see the Google Data APIs Protocol Reference for more information about these parameters.

Retrieving additional metadata for activity feed entries

Even though an activity feed identifies the video or user associated with a particular event, the feed does not necessarily contain metadata about that video or user. For example, a feed entry that identifies a video_rated event contains the YouTube video ID for the video and the rating that the user gave to that video. However, the entry does not contain other metadata like the video's title, description or owner.

To retrieve additional information about the videos or users identified in an activity feed, you can submit a batch processing request. A batch processing request can retrieve up to 50 video entries or user profile entries.

• To retrieve a list of video entries in a batch processing request, send an HTTP POST request to the following URL:

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

  Each entry in the request will use the <id> tag to identify a video for which you want to retrieve additional information. Use the <yt:videoid> values from the activity feed entries to construct the <id> tag values for the batch processing request.

  Activity feed:
  
      <entry>
        ...
        <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
          term='video_favorited'/>
        <yt:videoid>5EDAB37EA1823E58</yt:videoid>
      </entry>
  
  Batch processing request:
  
      <entry>
        <id>http://gdata.youtube.com/feeds/api/videos/<yt:videoid></id>
      </entry>
  

• To retrieve a list of user profiles in a batch processing request, send an HTTP POST request to the following URL:

  http://gdata.youtube.com/feeds/api/users/batch

  Each entry in the request will use the <id> tag to identify a user whose profile you want to retrieve. Use the <yt:username> values from the activity feed entries to construct the <id> tag values for the batch processing request.

  Activity feed:
  
      <entry>
        ...
        <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
          term='user_subscription_added'/>
        <yt:username>GoogleDevelopers</yt:username>
      </entry>
  
  Batch processing request:
  
      <entry>
        <id>http://gdata.youtube.com/feeds/api/users/<yt:username></id>
      </entry>
  

Note: You cannot retrieve video entries and user profile entries in the same batch processing request, so you would need to submit separate requests (to different URLs) to retrieve video entries as well as user profile entries.

Sample request for additional metadata

For example, the following batch processing request retrieves entries for three videos:

<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'>
  <batch:operation type='query'/>
  <entry>
    <id>http://gdata.youtube.com/feeds/api/videos/ADos_xW4_J0</id>
  </entry>
  <entry>
    <id>http://gdata.youtube.com/feeds/api/videos/iIp7OnHXBlo</id>
  </entry>
  <entry>
    <id>http://gdata.youtube.com/feeds/api/videos/cBPzPdcMj1s</id>
  </entry>
</feed>

Please see the batch processing documentation for additional information, including a sample response to a batch processing request.

Monitoring activity feeds with SUP

This section explains how to use the Simple Update Protocol (SUP) to monitor user activity feeds for YouTube users. This functionality will likely be most appealing to sites that maintain their own friend graphs or that want to monitor the activities of many users.

At a general level, SUP enables an API provider (such as YouTube) to notify API users when a feed is updated. SUP is particularly useful for API users that want to monitor many different feeds at once. With SUP, an API user can issue a single query to identify all updated resources, which is a much more efficient way to monitor changes than frequent polling. The API user can then retrieve data only for the modified resources, eliminating the need to ever issue polling requests on unchanged resources.

The following subsections explain how to use SUP to monitor user activity feeds:

Understanding the SUP feed format

An SUP feed consists of a JSON object that maps the keys in the list below to their corresponding values:

• The since_time field specifies the earliest time that a resource could have changed and still have been included in the SUP feed.

• The updated_time field specifies the latest time that a resource could have changed and still have been included in the SUP feed. As such, the feed identifies resources that were updated within the inclusive time range beginning at the since_time and ending at the updated_time.

• The period field specifies the duration of the time interval for which the SUP feed includes updates. As defined in the SUP specification, the number of seconds between between the since_time and the updated time must be equal to or greater than the interval that the period field specifies.

• The available_periods field contains a map that identifies the different SUP available for a feed. The map key contains a number that specifies the length of time (period) for which the corresponding feed contains updates. The value associated with the map key specifies the feed URL.

• The updates field contains an array of two-element lists, where the first element identifies an updated resource and the second element is a string used to distinguish between updates. In YouTube's SUP feed, this field identifies updated user activity feeds.

The sample SUP feed below contains updates for a five-minute (300 second) period and indicates that feeds are also available covering updates that occurred within 10-minute or 15-minute periods.

{ "updated_time": "2009-04-28T21:29:20Z",
  "since_time": "2009-04-28T21:24:19Z",
  "period": 300,
  "available_periods": {
    "300": "http://gdata/youtube.com/sup?seconds=300",
    "600": "http://gdata/youtube.com/sup?seconds=600",
    "900": "http://gdata/youtube.com/sup?seconds=900"
  },
  "updates": [
    ["159aa827", "6e19"],
    ["9559d1d", "6e19"],
    ["159aa827", "6f22"],
    ...
  ]
}

Retrieving YouTube's SUP feed

To retrieve YouTube's SUP feed, send an HTTP GET request to the following URL. Note that you can also use the seconds parameter to retrieve a feed that identifies all of the activity feeds that changed within a specific time interval. The SUP feed's available_periods field identifies the supported time intervals and their associated feed URLs.

http://gdata.youtube.com/sup

In YouTube's SUP feed, each item in the updates array is a two-element list that identifies an updated user activity feed:

• The first element in the list is the key that YouTube uses to uniquely identify a user activity feed.
• The second element distinguishes between updates. (For example, an SUP feed could indicate that the same activity feed changed several times during a given interval.) The value is required in the SUP specification but does not serve a practical purpose in this feed.

Discovering hash keys for activity feeds

To use the SUP feed, you also need to discover the hash keys that YouTube has assigned to the user activity feeds that you want to monitor. You can then determine whether any of those feeds were updated by matching the hash keys in your database to the hash keys in the SUP feed.

To locate the hash key for a particular user's user activity feed, you need to retrieve the user's activity feed from the following URL. (Replace the text username with the user's YouTube username.)

http://gdata.youtube.com/feeds/api/users/username/events?v=2

You can also retrieve the user activity feed for the currently logged-in user by sending an HTTP GET request to the following URL. Note that for this request, you need to provide an authentication token in the Authorization HTTP request header.

http://gdata.youtube.com/feeds/api/users/default/events?v=2

In the API response, the <feed> tag will contain a <link> tag for which the rel attribute value is updates. That href attribute contains a link to YouTube's SUP feed, and the link embeds the hash key that uniquely identifies the activity feed.

<link rel='updates' type='application/json'
  href='http://gdata.youtube.com/sup?seconds=300#47677e0a'/>

SUP in action

The Über Activity Viewer, a sample application demonstrated at Google I/O 2009, uses SUP to monitor the activities of participating YouTube users.

The application has two main components:

• A Java daemon periodically fetches YouTube's SUP feed and checks to see whether any participating users (members) are identified in the feed. The daemon creates multiple threads to retrieve updated activity feeds and store the updates in a database.

• A PHP website retrieves a list of activities from the database and then sends API requests to retrieve additional metadata about each activity. For example, while the Java daemon records that an event, such as a user added a favorite video or a friend, the PHP application retrieves metadata about the video or the new friend's profile. The PHP application also lets new users join the Über Activity Viewer user list, retrieving the SUP user hash for each new user and storing the hash and YouTube username in the database.

You can download sample code for the Über Activity Viewer at http://code.google.com/p/gdata-samples/source/browse/#svn/trunk/uberviewer.

Watch a video of Jeff Fisher and Jochen Hartmann explaining SUP and presenting the Über Activity Viewer at Google I/O 2009. (The part of the presentation that covers SUP begins at the 23:38 mark of the video.)

Using batch processing with the YouTube Data API

The YouTube Data API supports batch processing, enabling you to execute up to 50 operations with a single API request rather than submit a separate request for each individual operation. A batch processing request can combine multiple query (HTTP GET), insert (POST), update (PUT) and delete (DELETE) operations. Each operation is contained within an <entry> tag in the request. This section explains how to format batch processing requests and handle the API responses to those requests.

Batch operations are available for all YouTube feeds, and different types of feeds support different types of batch operations. For example, you can update, insert or delete playlists. However, you can only insert or delete favorite videos since favorite videos cannot be updated.

Note: Batch processing requests support query (HTTP GET) operations for feed entries but not for entire feeds. For example, if you are sending a batch request for a playlist, you can include one or more entries that retrieve information about individual playlist entries. However, the batch request cannot retrieve the entire feed for the playlist.

When you submit a batch processing request, the API server will try to perform each requested operation even if some of the operations in the request are not completed successfully.

Submitting a batch processing request

To submit a batch processing request, you will send an HTTP POST request to a batch URL. Each feed has its own batch URL, and when you submit a request to that URL, you can execute API operations on any entry in that feed. The batch URL for a feed appears in a <link> tag with a rel attribute value of http://schemas.google.com/g/2005#batch. The <link> tag is a subtag of the <feed> tag for that feed.

<feed xmlns='http://www.w3.org/2005/Atom' ...>
  <id>http://gdata.youtube.com/feeds/users/USERNAME/playlists</id>
  ...
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/USERNAME/playlists/batch?v=2'/>
  ...

In the example above, the batch URL for the user's playlists feed is http://gdata.youtube.com/feeds/api/users/USERNAME/playlists/batch?v=2.

Important: Each feed has its own batch URL, and when you submit a request to that URL, you can execute API operations on any entry in that feed. However, every entry in the request must be associated with the same batch URL. As such, you cannot use a single batch processing request to insert videos to a playlist and to flag those videos as a user's favorite videos since the playlist's feed has a different batch URL than the favorite videos feed.

In a batch processing request, <batch:operation> tags specify the type(s) of API requests that you want to execute. The <batch:operation> tag can be a subtag of either <feed> or <entry>. As a subtag of <feed>, the <batch:operation> tag specifies the default type of operation (query, insert, update or delete) that you are requesting for each entry in the feed. As a subtag of <entry>, the <batch:operation> tag specifies the type of operation that you want to perform on that particular entry.

Batch processing guidelines

This section lists several important guidelines for batch processing requests. Some of these guidelines highlight specific ways that YouTube Data API's batch processing functionality differs from the batch processing functionality for other Google Data APIs.

• Batch processing requests may contain up to 50 entries. Other Google Data APIs may allow requests to contain more than 50 entries.

• Batch processing requests must be 1MB or smaller.

• In your batch processing request, entries that are for query, update or delete operations should include both the <id> and the edit URL for the resource that is being queried, updated or deleted.

Sample batch processing request

The following batch processing request performs the following operations on a playlist:

1. Insert one video.
2. Delete two videos.
3. Update the playback order of three videos.

In the example, the <feed> tag has a <batch:operation> subtag that indicates that the default API operation for the batch processing request is update. Each entry in the request that does not correspond to an update operation contains a <batch:operation> tag that overrides this default setting.

<feed xmlns='http://www.w3.org/2005/Atom'
      xmlns:media='http://search.yahoo.com/mrss/'
      xmlns:batch='http://schemas.google.com/gdata/batch'
      xmlns:yt='http://gdata.youtube.com/schemas/2007'>
  <batch:operation type="update"/>
  <entry>
    <batch:operation type="insert"/>
    <id>tag:youtube,2008:video:ZTUVgYoeN_b</id>
    <batch:id>InsertedVideo1</batch:id>
  </entry>
  <entry>
    <batch:operation type="delete"/>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:F1A9BE54EF1EBD7A</id>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/77473B5FB369B676?v=2'/>
  </entry>
  <entry>
    <batch:operation type="delete"/>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:FE7E71CC9E49DB43</id>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/B21A4EE5CD829174?v=2'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:77773B5FB389A676</id>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/B7D3D08BD2F219CF?v=2'/>
    <yt:position>1</yt:position>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:B7D8D08CD2F119CF</id>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/E7F3D18BA3E217CB?v=2'/>
    <yt:position>2</yt:position>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:E2C8AD924E46577B</id>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/C1A3B17AC5E587AB?v=2'/>
    <yt:position>3</yt:position>
  </entry>
</feed>

The activity feeds section also includes a sample batch processing request that retrieves a list of video entries.

Handling the API response for a batch processing request

When you submit a batch processing request, the API will return an XML response that contains one <entry> for each operation in your request. The order of the entries in the response will correspond to the order of the entries in the request. The <batch:status> tag in each entry identifies the HTTP response code that the API returned for the corresponding entry in the batch request, indicating whether YouTube processed the entry successfully.

Note: You may receive a response that indicates that some operations were completed successfully while other operations failed.

The XML below shows the API response to the sample batch processing request shown in the previous section. Some tags in the entries for the inserted and updated entries have been omitted to highlight the tags that are specifically used for batch processing or the values that were updated in the batch processing request.

<?xml version='1.0' encoding='UTF-8'?>
<feed
  xmlns:atom='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <updated>2008-07-11T19:37:13.547Z</updated>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:A5B2B2C5FFCF79AB</id>
    <yt:position>11</yt:position>
    <batch:id>InsertedVideo1</batch:id>
    <batch:status code='201' reason='Created'/>
    <batch:operation type='insert'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:77473B5FB369B676</id>
    <updated>2008-07-11T19:37:13.970Z</updated>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='delete'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:B21A4EE5CD829174</id>
    <updated>2008-07-11T19:37:13.970Z</updated>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='delete'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:B7D3D08BD2F219CF</id>
    ...
    <yt:position>1</yt:position>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='update'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:E7F3D18BA3E217CB</id>
    ...
    <yt:position>2</yt:position>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='update'/>
  </entry>
  <entry>
    <id>tag:youtube,2008:playlist:8BCDD04DE8F771B2:C1A3B17AC5E587AB</id>
    ...
    <yt:position>3</yt:position>
    <batch:status code='200' reason='Success'/>
    <batch:operation type='update'/>
  </entry>
</feed>

Tracking operations in a batch processing request

You can use the following mechanisms to track the success or failure or operations in a batch processing request:

• For update, delete and query operations, you can use the value of the <id> tag to identify the resource that was updated, deleted or retrieved.

• You can specify a <batch:id> to identify an entry in your batch processing request. The API response will return this ID in the response entry that corresponds to the request entry. This tracking method is particularly useful for insert operations because newly inserted resources are assigned new ID values that are not known when the batch processing API requests are submitted.

  The sample batch processing request contains one entry that adds a video to a playlist. That entry contains an <id> tag with the value tag:youtube,2008:video:ZTUVgYoeN_b. But in the sample response, the <id> tag for that entry has the value tag:youtube,2008:playlist:8BCDD04DE8F771B2:A5B2B2C5FFCF79AB. The values are different because the entry in the request specifies the ID of a video that is being added to a playlist, but the entry in the response specifies the ID for the playlist entry. However, both entries include the <batch:id> tag with the value InsertedVideo1, simplifying efforts to track the insert operation. (See how the <batch:id> tag is used in the sample request or response.)

• The order of the entries in the API response corresponds to the order of the entries in the request. Thus, your application could use a numeric index to track failures identified in the API response and then correlate that index to the batch processing request to identify the specific operations that failed.

Identifying interrupted batch processing

If your request did not contain properly formed XML, then the API response may not contain the same number of entries as the original batch processing request. In such cases, the API response will use the <batch:interrupted> tag to identify the entry with the malformed XML. That entry might be the last one in the API response, and other entries after the one with the malformed XML might not have been processed. (The API server will attempt to indicate in the response how many entries were not processed.)

<batch:interrupted
  reason="[Line 14, Column 34, element entry] Invalid type for batch:operation: 'PUT'"
  success="8" failures="3" parsed="14"/>

Testing and troubleshooting

This section explains two resources, the interactive API demo and the YouTube API staging server, that YouTube provides to help you implement the API. In addition, this section discusses several aspects of an API implementation that developers may find challenging. It provides an overview of each issue and explains how to handle the issue correctly.

Using the Interactive API Demo

YouTube's interactive API demo lets you explore the YouTube Data API by generating and executing different types of API requests and viewing the API responses for those requests. The following steps, which also appear on the demo page, explain how the demo works:

1. You select an API operation that you want to perform. For example, you could search for (query) videos, retrieve standard feeds, create favorite videos or delete complaints. The demo supports almost all of the operations available in the API.

   When you select an operation, the forms on the page will update to enter the categories and keywords, request parameters, and request headers appropriate for that type of operation. For example, you do not need to enter a user name or have an authentication token to search for videos, but you can filter results using a number of request parameters (format, location, etc.). On the other hand, when you create a playlist, the request parameters are irrelevant but you do need to provide a username and an authentication token.

2. Construct the API request.

   • If you are performing a query (search) operation, enter search parameters and then edit the resulting request URL.
   • If you are inserting, updating or deleting a resource, enter information about that resource and then tweak the XML in the body of the generated request.

3. Click the Submit button. The XML response will display at the bottom of the page.

Using the staging server

YouTube posts updated versions of the API, which could include new features or bug fixes, to a staging server before those updates are released to production. The staged API instance helps YouTube ensure that API releases do not include any unexpected or undesired changes before the API is released to production. The staged API instance offers you the opportunity to test your applications before API releases affect your live site, and it should only be used for testing. Please do not use it in any live, publicly available application.

Warning: The staged API instance is not a sandboxed environment. It uses live data and you could lose information in your YouTube account if you use it when testing against the staging server. We recommend that you create a test account and only use that account when running queries against the staging server.

To use the staged API instance, you need to submit API requests to a different hostname. You also need to use a different hostname to test video uploads to the staged instance. The URLs for the production and staged versions of the API are listed below:

All queries except uploads:
Production: http://gdata.youtube.com/feeds/api/videos
Stage: http://stage.gdata.youtube.com/feeds/api/videos

Uploads:
Production: http://uploads.gdata.youtube.com/feeds/api/videos
Stage: http://uploads.stage.gdata.youtube.com/feeds/api/videos

Each release that is released to the staging server will be announced in the YouTube APIs Announcement Forum. You can subscribe to the group to receive email updates about new API releases.

Troubleshooting common API challenges

The following sections discuss several aspects of the API that many developers find challenging. Each section presents an overview of a specific issue and explains how to confirm that your code handles the issue correctly.

Filtering API responses

Like the YouTube website, the YouTube API does not support search parameters, including the category, format and orderby parameters, in requests for feeds that aggregate videos. For those feeds, the YouTube API also does not filter videos that are not available in the user's territory or that have been removed or blocked from appearing on the YouTube website. This policy affects the following types of feeds:

• Related videos
• Video responses
• Favorite videos
• Playlist – retrieving all videos in a specific playlist
• Inbox (messages)

The impact of this policy is that a feed may contain information about videos that are not actually playable for any of the following reasons:

• It is not available in the selected format.
• It is not playable in the user's location.
• It has been removed from YouTube by the user who uploaded the video.
• It has been claimed by a YouTube content partner, such as a record label or movie studio, and blocked from appearing on YouTube by that owner.

This policy benefits users because it ensures that feeds do not filter out removed or unavailable videos that the user might expect to see listed. For example, suppose a user creates a playlist with 10 videos and five of those videos are subsequently removed by their owners. If the user retrieves the playlist, she might be confused to see five videos listed instead of 10. In addition, this policy ensures that the number of videos in a feed, such as a playlist feed, does not change if a user tries to access the feed from different locations. As such, This policy ensures that all of the videos can be listed on the page even if some of the videos are not playable.

On the YouTube website, when a video is unavailable, YouTube still displays video metadata like the video's title and description. However, the video title does not link to a video watch page and the text "[video unavailable]" appears next to the title.

If a video is not playable, the entry for that video will not contain a <media:content> tag. In addition, the entry may contain an <app:control> tag that contains an explanation of why the video is not playable, as shown in the following example:

Example 1:
<app:control>
  <app:draft>yes</app:draft>
  <yt:state name="rejected" reasonCode="blocked"
    helpUrl="http://www.youtube.com/t/community_guidelines">
    Blocked by content owner
  </yt:state>
</app:control>

Example 2:
<app:control>
  <app:draft>yes</app:draft>
  <yt:state name="restricted" reasonCode="requesterRegion">
    This video is not available in your country
  </yt:state>
</app:control>

Using "public" and "private" video URLs

The YouTube API supports two different URLs for retrieving information about a single video:

• The public URL lets you retrieve information about a video on behalf of any user, including unauthenticated users. The public URL may return cached results.
• The private URL lets you retrieve uncached information about a video that was uploaded by the currently logged-in user.

Please see the Retrieving information about a single video section for more information.

Using the right URL for ClientLogin authentication

The YouTube Data API, like other Google Data APIs, supports ClientLogin authentication, which lets you associate all API actions with a single (YouTube) account. However, the YouTube Data API uses a different URL for authenticating users than other Google Data APIs.

To authenticate a user to use the YouTube API using ClientLogin, send a POST request to the following URL:

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

Other Google Data APIs use the following URL for ClientLogin authentication:

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

Calculating the content-length for direct upload requests

Direct upload requests are multipart requests, in which one part of the request is the API XML request and another part is the actual media file. Developers frequently calculate Content-Length header values that are too small. Ultimately, the incorrect value causes the API server to ignore the part of the request that contains the file binary and respond with the following error:

Multipart must have Atom and media part

To calculate the proper Content-Length, you need to count the full string length of the POST request. However, in addition to the XML component and the file binary, a direct upload request also defines a boundary string that separates the different parts of the request. So the calculation of the Content-Length needs to account for the size of the XML and file binary as well as of the inserted boundary strings and newlines.

Identifying a video for a particular operation

A number of different API operations require you to identify a video to add or update a resource. These operations include adding a favorite video, adding a playlist entry and sending a message.

To identify a video, use the <yt:videoid> for that video. Developers often substitute the <id> for the video, which is not always the same value. For example, the same video could appear in a search results feed, a playlist feed, and a favorite videos feed. In each of those feeds, the video would have a different <id> but the same <yt:videoid>.

For example, to add a video response you send an HTTP POST request to the following URL, with the string ORIGINAL_VIDEO_ID identifying the video to which you are adding the video response:

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

The request includes the following XML, in which the string RESPONSE_VIDEO_ID identifies the video that is being added as a response:

<entry xmlns="http://www/w3.org/2005/Atom">
  <id>RESPONSE_VIDEO_ID</id>
</entry>

In both cases, the value that you would use to identify the corresponding video is the <yt:videoid> value for that video.

Uploading private videos

When uploading or updating a video, you can use the <yt:private> tag to make the video a private video. Private videos are only visible to the video owner and to contacts with whom the owner has shared the video. Search results do not include private videos.

You can upload private videos and then later change those videos to be publicly visible. However, this process may delay the inclusion of those videos in the YouTube search index. This approach may also delay the availability of those videos in API responses.

Caching video metadata to avoid quota issues

The YouTube API enforces quotas to prevent problems associated with irregular API usage. Specifically, a too_many_recent_calls error indicates that the API servers have received too many calls from the same caller in a short amount of time. If you receive this type of error, then we recommend that you wait a few minutes and then try your request again.

To avoid quota errors, high-traffic websites should cache video metadata fetched through the API for one to two hours.

Uploading a large batch of videos

If you are uploading a large batch of videos, please do not upload more than one video every three to five minutes. This process helps to ensure that you will not receive a quota error for trying to upload too many videos in too short a time.

Retrieving Insight data for a video

YouTube Insight, an analytics and reporting engine, provides viewing statistics, popularity metrics and demographic information for videos. A video entry contains a link to an Insight data feed if the authenticated user retrieving the entry owns the video. The link appears in a <link> tag for which the rel attribute value is http://gdata.youtube.com/schemas/2007#insight.views.

<link rel='http://gdata.youtube.com/schemas/2007#insight.views'
  type='text/html'
  href='http://insight.youtube.com/video-analytics/csvreports?query=PlVJ88-zqkI&type=...'/>

The URL in the <link> tag points to a zip file that contains two Insight reports in CSV (comma-separated values) format. Each report contains worldwide data for the previous seven-day period. (As such, the REGION in each filename listed below will be "world".) This list identifies the reports that are included in the zip file and defines the fields in each report:

• Referrers (filename: VIDEOID_DATERANGE_REGION_referrers_1.csv) – This report explains how users reached the video. Each row in the report identifies the number of referred views from a particular referrer on a specific date in a specific region. Note that this report will be omitted if the video was not viewed at least once during the reporting period. The report contains the following fields:

  • Date – The day that the referred video views occurred.

  • Region – The country where the referred video views occurred. The value will be a ISO 3166 two-letter country code.

  • VideoID – The YouTube video ID that uniquely identifies the video.

  • Title – The title of the video.

  • Source type – The referrer for the video views. This field will contain one of the following values:

    • ADVERTISING – The viewer was referred to the video by an advertisement.
    • EMBEDDED – The video was embedded in a web page when it wsa viewed. The "Detail" field in the row will identify the web page where the video was embedded.
    • EXT_URL – The video views were referred from a link on a web page. The "Detail" field in the row will identify the web page.
    • GOOGLE_SEARCH – The video views were referred from Google search results.
    • GVIDEO_SEARCH – The video views were referred from Google Video search results.
    • PROMOTED – The video views were referred from an unpaid YouTube promotion, such as the YouTube "Spotlight Videos" page.
    • VIRAL_OTHER – YouTube did not identify a referrer for the views, indicating that the user navigated directly to the video, perhaps by copying and pasting the URL from another location.
    • YT_OTHER_PAGE – The video views were referred from a link other than a search result or related video link that appeared on a YouTube page.
    • YT_RELATED – The video views were referred from a related video on YouTube.
    • YT_SEARCH – The video views were referred from YouTube search results.

  • Detail – Additional information about the traffic referral source. This type of information that the field provides depends on the value of the "Source Type" field:

    • If the source type is a search results page (YT_SEARCH, GOOGLE_SEARCH, GVIDEO_SEARCH), then the "Detail" field contains the search term(s) for that page.
    • If the source type is another video (YT_RELATED), then the "Detail" field contains the YouTube video ID for that video.
    • If the source type is another web page (EXT_URL, YT_OTHER_PAGE, EMBEDDED), then the "Detail" field contains the URL of that page.

    For all other source types, the "Detail" field will be empty or will contain the word "Other".

  • Referred views – The number of video views that originated from the data source on the specified day in the specified region.

• Views (filename: VIDEOID_DATERANGE_REGION_views_1.csv) – This report provides insight into the way that viewers interacted with the video. Each row in the report identifies the number of views that occurred on a specific date in a specific region. The report contains the following fields:

  • Date – The day that the video views occurred.

  • Region – The country where the video views occurred. The value will be a ISO 3166 two-letter country code.

  • VideoID – The YouTube video ID that uniquely identifies the video.

  • Title – The title of the video.

  • Views – The number of times that the video was watched.

  • Unique users – The number of unique users who watched the video.

  • Popularity – A metric that measures the popularity of a video, as measured by views, relative to other videos in a region. For example, a popularity score of 0.75 indicates that a video has been viewed more frequently than 75 percent of all other videos available in the region.

  • Comments – The number of comments that viewers left on the video.

  • Favorites – The number of times that the video was marked as a favorite video.

  • Rating 1 – The number of times that the video received a rating of 1.

  • Rating 2 – The number of times that the video received a rating of 2.

  • Rating 3 – The number of times that the video received a rating of 3.

  • Rating 4 – The number of times that the video received a rating of 4.

  • Rating 5 – The number of times that the video received a rating of 5.

Understanding API error responses

This section discusses the XML response that may accompany a failed API request. Please see the reference guide for more information about the HTTP response codes that the API returns.

When an API request fails, YouTube will return an HTTP 4xx or 5xx response code that generically identifies the failure as well as an XML response that provides more specific information about the error(s) that caused the failure. For each error, the XML response includes a <domain> element, <code> element and possibly a <location> element. The following subsections explain the possible values for these elements and provides a sample error response for each error. Note that error responses may contain more than one error.

Validation errors

A validation error, which is identified by a <domain> tag value of yt:validation, reports a problem related to an XML element value in a request to insert or update an entry. API functions that insert or update videos or other data can report yt:validation errors. Validation errors are typically reported with an HTTP 400 response code.

For all validation errors, the <location> tag defines the error location as an Xpath pointing to the XML tag that caused the request to fail. The Xpath location is specified relative to the <entry> tag in the request.

For validation errors, the <code> tag will contain one of the following values:

• required - This code indicates that a required field is missing or has an empty value.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>required</code>
      <location type='xpath'>media:group/media:title/text()</location>
    </error>
  </errors>
  

• deprecated - This code indicates that an element's value has been deprecated and is no longer valid. For example, a video category name that has been retired may not be associated with newly added or updated videos.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>deprecated</code>
      <location type='xpath'>
        media:group/media:category[@scheme='http://gdata/youtube.com/schemas/2007/categories.cat']/text()
      </location>
    </error>
  </errors>
  

• invalid_format - This code indicates that an XML element's value does not match an expected format. For example, you could receive this error if you specify invalid coordinates in the <gml:pos> tag.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>invalid_format</code>
      <location type='xpath'>georss:where/gml:point/gml:pos/text()</location>
    </error>
  </errors>
  

• invalid_character - This code indicates that an XML field value contains an invalid character. For example, video titles may not contain a less than (<) character.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>invalid_character</code>
      <location type='xpath'>media:group/media:title/text()</location>
    </error>
  </errors>
  

• too_long - This code indicates that an XML element's value exceeds the maximum allowable length. For example, video titles must be 60 characters or less.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>too_long</code>
      <location type='xpath'>media:group/media:title/text()</location>
    </error>
  </errors>
  

Quota errors

A quota error, which is identified by a <domain> tag value of yt:quota, identifies a problem related to irregular API usage.

For quota errors, the <code> tag will contain one of the following values:

• too_many_recent_calls - This code indicates that the API servers have received too many calls from the same caller in a short amount of time. This error will not specify a location. The API response will not include a <location> tag for this type of error.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:quota</domain>
      <code>too_many_recent_calls</code>
    </error>
  </errors>
  

  If you receive this error, then your application has exceeded our current limits on API calls. We recommend that you wait a few minutes and then try your request again.

• too_many_entries - This code indicates that the user is attempting to exceed a storage limit on his account and must delete existing entries before inserting new entries. For this type of error, the <location> tag identifies the feed that caused the error.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:quota</domain>
      <code>too_many_entries</code>
      <location type='other'>http://gdata.youtube.com/feeds/users/username/uploads</location>
    </error>
  </errors>
  

Authentication errors

An authentication error, which is identified by a <domain> tag value of yt:authentication, identifies a problem related to an improperly authenticated request to execute an API function requiring user authentication. Authentication errors could be identified with HTTP 401 or 403 response codes.

Authentication errors may include a <location> element. If so, the element's value will identify the header that caused the authentication error.

For authentication errors, the <code> tag will contain one of the following values:

• InvalidToken - This code indicates that the authentication token specified in the Authorization header is invalid.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:authentication</domain>
      <code>InvalidToken</code>
      <location type='header'>Authorization: GoogleLogin</location>
    </error>
  </errors>
  

• TokenExpired - This code indicates that the authentication token specified in the Authorization header has expired.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:authentication</domain>
      <code>TokenExpired</code>
      <location type='header'>Authorization: GoogleLogin</location>
    </error>
  </errors>
  

Service errors

A service error, which is identified by a <domain> tag value of yt:service, identifies an authentication error that occurs when the YouTube site is undergoing temporary maintenance. This error may occur if you are trying to execute insert (POST), update (PUT) or delete (DELETE) operations. This error will not occur if you are only executing read (GET) operations.

For service errors, the <code> tag will contain the following value:

• disabled_in_maintenance_mode - This code indicates that POST, PUT and DELETE operations cannot be executed because the site is temporarily in maintenance mode. If you receive this error, wait a few minutes and try your request again.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:service</domain>
      <code>disabled_in_maintenance_mode</code>
    </error>
  </errors>
  

Revision History

November 5, 2009

This update contains the following changes:

• The new caption parameter lets you restrict a search result set to only include videos that have caption tracks. The parameter is specified without a value, and its presence indicates that all videos in the result set must have captions.

• The prettyprint parameter, which is a standard Google Data API parameter, is now documented for the YouTube Data API. This parameter, which was already supported, may be useful for testing and debugging your application.

• The description of the video upload process for browser-based uploading has been updated to note that before allowing a user to submit the form for uploading a video, your application should ensure that the user has selected a file to upload. If the user submits the form without specifying a file, YouTube will display an error page indicating that the file was missing in the request but will not redirect the user to the nexturl specified in the request. By ensuring that the user has specified a file, you can prevent the user from reaching that error page.

August 31, 2009

This update contains the following changes:

• The time parameter is now supported for search queries as well as for standard feeds.

• The definition of the author parameter has been updated to explain how this parameter functions in a request for a standard feed.

• The Friend activity feeds section has been updated to note that friend activity feed only contain events for contacts who are explicitly labeled as being in the user's Friends group, and that these feeds do not contain events for all of the user's contacts.

• The definition of the <yt:state> tag's reasonCode attribute has been updated to better describe the meaning of the limitedSyndication code for a restricted video.

• The sortorder parameter, which had enabled comments to be sorted in ascending or descending order, has been deprecated.

• The most_linked standard feed has been deprecated. Queries for this feed will now return an empty feed.

July 29, 2009

This update contains the following changes:

• The new Video recommendations section explains the new recommendations feed, which contains videos that may appeal to a logged-in user. YouTube selects recommendations for a user based on an algorithm that considers signals from a variety of sources that include the user's favorite videos, recently added playlist videos, recently watched videos, ratings and more.

• The new Retrieving Insight data for a video section explains how to retrieve Insight reports for a video entry. Note that a video entry only contains a link to an Insight data feed if the authenticated user retrieving the entry owns the video. This section also defines the fields that appear in the Insight reports.

July 21, 2009

This update contains the following changes:

• The new Providing captions for a video section explains how to add captions to a video file. Captions can help users to locate and understand a video. The new section provides formatting guidelines for caption files and also explains how to create, retrieve, update or delete caption tracks.

June 17, 2009

This update contains the following changes:

• You can now use the Simple Update Protocol (SUP) to monitor user activity feeds for YouTube users. SUP enables an API provider such as YouTube to notify API users when a feed is updated. SUP is particularly useful for API users that want to monitor many different feeds at once. This functionality will likely be most appealing to sites that maintain their own friend graphs or that want to monitor the activities of many users.

  In conjunction with the SUP change, the User activity feeds section has been updated to explain that the API now supports two query formats for retrieving user activity feeds. Only one of these formats contains hash keys that you will need if you plan to use SUP in your application.

• The new Developer's Guide adviser lets you tailor the YouTube API documentation to meet the needs of your application.

  • You identify the features that you want to implement and then the adviser hides information about any other features from the left menu.
  • The adviser customizes your pagination links so that you can page back and forth between only the features that you want to use.
  • The adviser stores your preferences in a cookie, so even if you can't finish your application in one browser session, your customized documents will not change.
  • The adviser displays links to edit or clear your preferences as well as a link that you can either bookmark or send to other developers.

April 8, 2009

This update contains the following changes:

• The new Testing and troubleshooting section explains two resources, an interactive API demo and a staging server, that YouTube provides to help you implement the API. In addition, this section discusses several aspects of an API implementation that developers may find challenging. It provides an overview of each issue and explains how to handle the issue correctly.

• The Custom query parameters for the YouTube Data API section has been updated to contain a list of parameters used to request any type of feed. The section also now lists parameters that are only used to request a particular type of feed, such as video search results, standard feeds, video feeds or comment feeds. Finally, the API parameter definitions have been updated to highlight cases where a parameter is only supported for search requests.

• The restriction parameter definition has been updated to note that you should include this parameter in any request to retrieve a list of videos, including search results, playlists, favorite videos, video responses and so forth. If a video in the API response is not playable in the location that you're using to restrict availability of the content, the entry for that video will not contain a <media:content> tag. However, it will contain a <yt:state> tag that indicates that the video is restricted.

March 27, 2009

This update contains the following changes:

• The new Searching for playlists section explains how to search for YouTube playlists matching a particular keyword or set of keywords.

March 3, 2009

This update contains the following changes:

• The new Retrieving data for a single video section explains how to submit an API request that returns an Atom entry containing information about a single video.

• The Videos uploaded by a specific user section has been updated to explain how to ensure that you are requesting the most up-to-date information available when requesting a feed of the logged-in user's uploaded videos.

February 24, 2009

This update contains the following changes:

• The new Activity feeds section introduces user activity feeds, which let you retrieve a feed of actions that a particular user or set of users has taken on YouTube. This section also includes information about friend activity feeds, which were released in December.
  
  The Activity feeds section explains the different types of events that are listed in activity feeds. It also explains how user activity feeds and friend activity feeds are different. Finally, it provides instructions for submitting requests for each feed type.

• The definition of the author parameter has been updated to explain how the parameter is used in a request to retrieve a user activity feed.

December 10, 2008

This update contains the following changes:

• The new OAuth for web applications section explains how to authenticate users with the OAuth protocol, a standard way for accessing protected data on different websites.

• The new Friend activity feeds section explains a new type of feed now available via the API. User activity feeds identify actions that an authenticated user's friends have recently taken on the YouTube site. Through the feed, a YouTube user can learn about videos that the user's friends have rated, shared, uploaded or marked as favorites.

• The Subscriptions, Retrieving a user's subscriptions and Adding a subscription sections have been updated to explain playlist subscriptions, a new subscription type.

• The new Searching for channels section explains how to search for YouTube channels matching a particular keyword or set of keywords.

• The new key parameter provides an alternate way to identify your developer key when submitting an API request. The API client libraries always use HTTP request headers to specify your developer key (and client ID). However, developers who are not using one of the client libraries may find it easier to use the key (and client) query parameters to specify those values. The Using a developer key and client ID section has also been updated to explain how to use query parameters rather than HTTP request headers to provide your client ID and developer key.

• The Deleting a favorite video section has been updated to note that the ID that you specify to delete a favorite video is not that video's <yt:videoid>, but another value that uniquely associates that video with the user who marked it as a favorite. This change only clarifies existing behavior and does not reflect changes in functionality.

• The Playlists section has been updated to note that YouTube no longer lets playlist owners define custom titles and descriptions for playlist entries. The API still accepts requests that specify custom titles and descriptions, but it ignores those values. If playlist owners have already set custom titles or descriptions for playlist entries, the API will continue to return those values in playlist feeds as previously documented.

November 13, 2008

This update contains the following changes:

• The API versioning section has been updated to simplify the instructions for specifying the API version that YouTube will use to handle an API request.

• The new Backward Compatibility Guidelines document identifies API behaviors that may change even if you do not modify the API version that should be used to handle your API requests. The guidelines also identify API behaviors that are not intended to change for a particular API version. Finally, the guidelines discuss best practices for ensuring that your application properly handles API updates.

October 20, 2008

This update contains changes associated with the release of version 2 of the YouTube Data API. YouTube still supports API version 1. (See documentation for API version 1).

• The new API versioning section explains how to specify the version of the API that YouTube should use to handle the request.

• All XML examples in this document have been updated to specify that YouTube should use API version 2 to handle the API request. Similarly, all XML examples have been updated to match the output for API version 2.

• The list of API query parameters has been divided into lists of standard Google Data API query parameters and custom query parameters for the YouTube Data API. In addition, the following API parameters have been updated:

  • The new v parameter can be used to specify the API version that YouTube will use to handle the API request.
  • The new safeSearch parameter indicates whether YouTube should include restricted content as well as standard content. The safeSearch parameter replaces the racy parameter, which has been deprecated with this API release.
  • The location parameter definition now explains how that parameter, in conjunction with the new location-radius parameter, can be used to request videos associated with a particular geographic area.
  • The new strict parameter can be used to instruct YouTube to reject API requests that contain invalid request parameters.
  • The new uploader parameter can be used to restrict search results to only contain partner videos.
  • The name of the vq parameter has changed to q.

• The values of <id> tags in feed entries no longer specify a URI. In API version 2, the <id> tag value is a URN in a format like tag:youtube,2008:videos or tag:youtube,2008:video:24Ryj1ywoqw or tag:youtube,2008:favorite:24Ryj1ywoqwji5_MqicxSo.

• The <summary> tag is a new tag that replaces the <yt:description> tag, which has been deprecated with this API release.

• The <content> tag has replaced the <gd:feedLink> tag in playlists feeds and subscriptions feeds.

• The type attribute has been removed from the <title> and <content> tags.

• The <media:credit> tag is a new tag in playlist and inbox feed entries that identifies the YouTube user who uploaded a video. The <author> tag definition has been updated to reflect the fact that in playlist and inbox feed entries, the <author> tag does not identify the user who uploaded the video.

• The <feed> and <entry> tags both in API responses now include a gd:etag attribute. Etags are a standard Google Data API feature for version 2 APIs, but the YouTube Data API does not use them at this time. Note that etags are also an HTTP standard.

October 3, 2008

This update contains the following changes:

• The new Authenticating requests from Flash applications section explains how to use the X-HTTP-Method-Override header to submit a GET, PUT or DELETE request from a Flash application. Since Flash applications must send an HTTP POST request to set an Authorization header, the additional X-HTTP-Method-Override header must be set to submit a request that is not actually a POST request.

• The new sortorder parameter, which is only valid for comments feeds, lets you specify whether the API will return comments in ascending order (oldest to newest) or descending order (newest to oldest).

• The new Retrieving new subscription videos section explains how to retrieve a feed listing a user's new subscription videos. The feed returns the same list of videos that appears on the Subscriptions page of the user's YouTube account under the New Videos subheading.

August 18, 2008

• The category parameter now provides an alternate way to search for videos that are in certain categories or are tagged with particular keywords">Browsing with categories and keywords section have all been updated to demonstrate how to use either the category parameter or the standard URL notation for searching by category, keyword or developer tag.

• The Technical requirements for uploaded videos section contains a small correction. Previously, that section incorrectly stated that you could compress video files using the .zip format before uploading them. The guide now correctly states that you can compress API requests, including video uploads, using gzip transfer-encoding.

July 16, 2008

This update contains the following changes:

• The newly added Using batch processing with the YouTube Data API section explains how to use batch processing to execute up to 50 operations with a single API request.

• The guide includes a new section that explains how to add a comment in reply to another comment.

• The Error responses section now describes service errors. A service error indicates that an API request failed because YouTube's services are temporarily unavailable. The only service error that has been defined thus far indicates that a request failed because the YouTube site is undergoing temporary maintenance.

• The time query parameter now supports the most_popular standard feed in addition to the top_rated and most_viewed standard feeds.

June 12, 2008

This update contains the following changes:

• The Messages section has been added to the document to explain new API functionality that enables a user to retrieve, send and delete messages from her inbox.

• The Uploading videos section has been updated to note that the API will not let you upload additional videos to accounts that already contain 2000 or more videos.

• The Assigning Developer Tags section has been updated to note that developer tags can only be associated with a video when that video is uploaded. In addition, the developer tags assigned when a video is uploaded cannot be changed thereafter.

• The Standard feeds section has been updated to reflect the addition of a new feed, which is for YouTube's most popular videos. The section also now includes a short description of each feed.

• The list of YouTube Data API query parameters has been updated to reflect the addition of the location query parameter. This parameter lets you request videos that have a geographic location specified in their metadata. You do not need to specify a parameter value for this parameter.

• The Technical requirements for uploaded videos section has been updated to reflect the fact that the maximum size for uploaded videos has been increased from 100MB to 1GB. In addition, this section now correctly notes that the maximum length of uploaded videos is 10 minutes.

May 6, 2008

• The Videos uploaded by a specific user and Direct uploading sections have been updated to clarify the meaning of the term default when that term appears in an API URL. Specifically, the term default identifies the currently logged-in user in a number of API commands. The user is, in turn, identified by the authentication token that you submit with the request.

• The Handling the Upload API response section, which discusses the API response for partners that use direct uploading, has been updated to explain the format of the API response in more detail. Specifically, the section now explains how to use the self link in the API response to check the status of an uploaded video.

• In conjunction with the previous update in this list, the Checking the status of an uploaded video section has also been updated to explain that, if you use the direct uploading method, you can use the self link in the API response to check the status of an uploaded video.

May 2, 2008

• The Retrieving a user's contacts section has been updated to note that the API returns a maximum of 100 contacts for any given contact feed request even if more contacts match the request parameters.

• The racy parameter definition has been updated to note that feed entries for videos that contain restricted content will contain the <media:rating> element.

• The restriction parameter definition has been updated with a recommendation that you always include this parameter in API requests, setting the parameter value to the end user's IP address.

April 7, 2008

This document contains the following changes:

• The newly added Revision History highlights important changes to this document. The revision history will not mention minor changes such as spelling corrections.

• The API now supports the client parameter, which provides an alternate way of identifying your application. You can also use the X-GData-Client header to identify your application.

• The Uploading videos section has been updated to note that the API will not allow you to upload new videos to an account that already contains 1000 or more videos.

• The Playlists section has been updated to note that a playlist cannot contain more than 200 videos.