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.

The current version of the API is 2, and you must use either the v parameter or the GData-Version HTTP request header to specify this version. Using the most current version of the API may allow your application to access API features that are not available in older versions of the API. For example, captions, partial responses, and partial updates are all supported in version 2 of the API but are not supported in version 1.

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 and demonstrate how to use version 2 of the API.

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

A developer key uniquely identifies a product that is submitting an API request. Please visit http://code.google.com/apis/youtube/dashboard/ to obtain a developer key.

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

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

  X-GData-Key: key=<developer_key>
  

• Include the key query parameter in the request URL.

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

Note: Specifying your developer key is very simple if you are using one of our client libraries. In the client libraries, you provide your developer key when initializing the YouTube service object, and all subsequent requests sent using that object will contain the 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. By providing the username and password for the user’s YouTube user account, you are 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/accounts/ClientLogin

Note: This URL was updated in October 2010. The old URL has been deprecated in accordance with the policy explained in our Terms of Service. If you are updating an application that used the old URL (https://www.google.com/youtube/accounts/ClientLogin), note that the new URL does not return the user’s YouTube account name as the YouTubeUser value in response to a successful ClientLogin request. For any API request that requires you to specify a YouTube username, you can use the term default to identify the currently logged-in user as long as you also send an Authentication token with the request. See the Revision History for more details.

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=<username>&Passwd=<password>
    &service=youtube&source=<source>
  

  You need to make the following changes to this string:

  • Replace the <username> and <password> strings with one of the following combinations of values:
    1. If the user’s YouTube account is linked to a Google Account, specify either the YouTube account name or the email address associated with the Google Account as the <username> and specify the Google Account password as the <password>.
    2. If the user’s YouTube account is not linked to a Google Account, specify the user’s YouTube account name as the <username> and the user’s YouTube account password as the <password>.
  • Replace the string <source> with a short string that identifies your application for logging purposes.
• The <username>, <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. You must extract the authentication token from the page and then submit that value 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/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 token values have been shortened in the example.)

SID=DQAAALQAAAA6wx7byZp-s4BizDqS1OaT21j9dmY6wMjexpQdNC3
LSID=DQAAALUAAAARH_PvRXoaz23Dv_UmOSUz2_0vh-4XbUedCN9XTZ
Auth=DQAAALUAAAARH_PvRXoaz23Dv_UmOSUz2_jxJVCGjoulKlhWbU

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

Retrieving region-specific standard video feeds

The API enables you to retrieve region-specific standard feeds by inserting a region ID in the feed URL. The following URL demonstrates the format of the URLs that you would use to retrieve region-specific standard feeds:

http://gdata.youtube.com/feeds/api/standardfeeds/regionID/feedID?v=2

For example, to retrieve a list of the top-rated videos in Japan, you would send an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/standardfeeds/JP/top_rated?v=2

Note: Region-specific versions of the watch_on_mobile standard feed are not available.

The following tables identify the countries for which the YouTube Data API supports localized feeds and the regionID associated with each country:

Retrieving category-specific standard video feeds

The API also enables you to retrieve category-specific standard feeds by appending an underscore and a category name to the standard feed URL. The following URL demonstrates the format of the URLs that you would use to retrieve category-specific standard feeds:

http://gdata.youtube.com/feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME?v=2

For example, to retrieve a list of the top-rated comedies in Japan, you would send an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/standardfeeds/JP/top_rated_Comedy?v=2

Please note the following guidelines when generating URLs for category-based standard feeds:

• The Category list for uploaded videos section explains how to retrieve the categories that could be used to classify video content. That section also explains how to identify the regions where each category is browsable.
• If you retrieve a localized category list, the category name that you append to the URL is still the English word that is the value of the <atom:category> tag’s term attribute in the category list.

  Category listing:
  <atom:category term='Entertainment' label='Divertissement' xml:lang='fr-FR'>
  
  URL for feed of top-rated entertainment videos in France:
  http://gdata.youtube.com/feeds/api/standardfeeds/FR/top_rated_Entertainment
  

• The regionID in the feed URL is optional. If you do not specify a region ID, the API response will contain a category-based standard feed that is not restricted to a particular locale.
• If your request does specify a regionID, then the specified category must be browsable in the specified region. For example, you can request a feed of the top-rated nonprofit videos in the United States because “Nonprofit” is a browsable category in the United States. However, you cannot request the top-rated nonprofit videos in France since “Nonprofit” is not a browsable category there.

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:

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

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 information about the currently logged-in user’s videos

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

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

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

Retrieving and searching for channels

The following sections explain how to use the API to retrieve a list of channels matching a user-specified search term or to retrieve standard feeds of the channels with the most video views or subscribers:

Searching for channels

You can search for channels matching a user-specified search term by submitting an HTTP GET request to the following URL and using the q query parameter to specify a search term. YouTube could match the search term to the channel name, description or other channel-related fields.

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.

Standard feeds for channels

The API also lets you retrieve standard feeds that list the most viewed or most subscribed YouTube channels. Standard channel feeds are only supported in version 2 of the API. To retrieve a standard channel feed, send an HTTP GET request to the URL associated with that feed.

The following table identifies the URL associated with each standard feed:

Entries in a standard channel feed differ in a few ways from entries in channel search results feeds:

• Standard channel feed entries contain the <yt:channelStatistics> tag, which contains statistics like the number of videos uploaded to the channel and the total number of times all of the videos in the channel have been viewed.
• Standard channel feed entries contain a <media:thumbnail> tag, which specifies the location of a thumbnail image that can be used to represent the channel.

The XML excerpt below shows the format of a standard channel feed entry:

<entry>
  <id>tag:youtube.com,2008:standardchannel:expertvillage</id>
  <updated>2010-10-28T19:07:55.377Z</updated>
  <title>Expert Village - Watch and Learn</title>
  <summary>Welcome to the official YouTube channel of Expert Village. We
    are known for our largest choice of informative videos from trusted
    sources to provide answers to your everyday questions.</summary>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/channelstandardfeeds/most_viewed/c/expertvillage?v=2'/>
  <author>
    <name>expertvillage</name>
    <uri>http://gdata.youtube.com/feeds/api/users/expertvillage</uri>
  </author>
  <yt:channelStatistics commentCount='887' totalUploadViewCount='1481786054'
    videoCount='138756' viewCount='22295173'/>
  <media:group>
    <media:thumbnail
      url='http://i2.ytimg.com/i/QlGBspQdj17WOPBQMT1k9A/1.jpg?v=89e277'/>
    <media:title>Expert Village - Watch and Learn</media:title>
  </media:group>
</entry>

Both standard channel feeds support the time query parameter, which lets you restrict the feed to only contain relevant results from the previous day, week or month. For example, to retrieve the most viewed channels from the previous day, you would send an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/channelstandardfeeds/most_viewed?time=today&v=2

Note: YouTube does not generate a feed of the most subscribed channels from the previous day. As such, the only supported values of the time parameter for the most_subscribed feed are this_week, this_month, and all_time.

Retrieving region-specific standard channel feeds

The API enables you to retrieve region-specific standard channel feeds by inserting a region ID in the feed URL. (You would also use a region ID to retrieve a region-specific video feed.) The following URL shows the format of the request URL for retrieving region-specific standard channel feeds:

http://gdata.youtube.com/feeds/api/channelstandardfeeds/regionID/feedID?v=2

For example, to retrieve a list of the most-viewed channels in Sweden, you would send an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/channelstandardfeeds/SE/most_viewed?v=2

See the Retrieving region-specific standard video feeds section for a list of supported countries and their associated regionID values.

Retrieving category-specific standard channel feeds

You can retrieve category-specific standard channel feeds by appending the string /-/ and a single category name to the feed URL. YouTube associates a category with a channel based on the type of videos uploaded to that channel.

The following URL shows the format of the request URL for retrieving category-specific standard channel feeds. (Note that the regionID in the URL is optional.)

http://gdata.youtube.com/feeds/api/channelstandardfeeds/regionID/feedID/-/CATEGORY_NAME?v=2

For example, to retrieve a list of the most viewed music channels in Brazil, you would send an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/channelstandardfeeds/BR/most_viewed/-/Music?v=2

The Category list for uploaded videos section of the Reference Guide explains how to retrieve the categories that could be used to classify video content. That section also explains how to identify the regions where each category is browsable. Please refer to the Retrieving category-specific standard video feeds section for a list of other guidelines for category-specific standard feeds.

Retrieving standard channel feeds by user type

You can retrieve standard channel feeds for specific types of users by appending an underscore and a user type to the feed type in the feed URL. For example, the following URL retrieves a feed of the most viewed musician channels in the United States:

http://gdata.youtube.com/feeds/api/channelstandardfeeds/US/most_viewed_Musicians?v=2

Valid user types that can be appended to the feed URL are Comedians, Directors, Gurus, Musicians, Non-profit, Partners, Politicians, Reporters, and Sponsors. These values are case-sensitive and can be found in the channeltypes.cat XML document.

Note: If you request a standard channel feed for a specific user type, you can also specify a region but you cannot also specify a category name.

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.

  The API also supports a direct, resumable uploading process, which can be restarted from the point of interruption if the connection between your application and YouTube is lost at any point during the uploading process.

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 to upload a video. 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 username and password.
3. The user submits his 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 a username and password that identify the YouTube account associated with the video. As described in the previous section, the username could be either a YouTube account name or a Google Account email address. The password will be the Google Account password for YouTube accounts that are linked to Google Accounts and the YouTube account password for YouTube accounts that are not linked to Google Accounts.
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

Legal requirements

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.

Technical requirements

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

Metadata requirements

Each uploaded video must have a title and must also be associated with a category. You can choose any of the following methods to set these values:

• You can specify the title and category for an uploaded video using the <media:title> and <media:category> elements.
• You can include the <yt:incomplete> element in the uploaded video’s metadata. This element instructs YouTube to automatically generate certain metadata values if they are not otherwise specified. YouTube uses the following rules to generate metadata if the <yt:incomplete> element is included in the metadata for the uploaded video:
  • If the entry does not contain a <media:title> element, YouTube sets the video’s filename as the video title. If you use browser-based uploading, the filename is passed in the file input field. If you use direct uploading, including resumable uploading, the filename is the value of the Slug HTTP request header.
  • If the entry does not contain a <media:keywords> element, YouTube sets the video’s filename as the video’s keyword tag.
  • If the entry does not contain a <media:category> element, YouTube sets the video’s category to the category of the last video that the user uploaded. If no prior upload exists, YouTube sets the video’s category to People.

  For example, the sample direct uploading request below would upload a video with the title summer_vacation.mp4 and keyword summer_vacation.mp4 in the Travel & Events category.

  POST /feeds/api/users/default/uploads HTTP/1.1
  Host: uploads.gdata.youtube.com
  Authorization: AuthSub token="DXAA...sdb8"
  GData-Version: 2
  X-GData-Key: key=adf15ee97731bca89da876c...a8dc
  Slug: summer_vacation.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>
      <yt:incomplete/>
      <media:category
        scheme="http://gdata.youtube.com/schemas/2007/categories.cat">Travel
      </media:category>
    </media:group>
  </entry>
  --f93dcbA3
  Content-Type: video/mp4
  Content-Transfer-Encoding: binary
  
  <Binary File Data>
  --f93dcbA3--
  

• If you are uploading videos via the resumable uploading process, you can upload a video without any metadata whatsoever. See the Uploading a video without metadata section for details about this option for resumable uploads. In this case, YouTube will handle the absence of metadata as if the upload request consisted of an <entry> that only contained a <yt:incomplete> element.

You can only include the <yt:incomplete> element in a video entry at the time that you upload the video. When you retrieve a video entry for a video uploaded with incomplete metadata, the entry will contain the <yt:incomplete> element. If you choose to update the video, you must at least remove the <yt:incomplete> element from the entry before submitting your update request.

Note that videos uploaded with the <yt:incomplete> element will not be included in YouTube’s search index, and therefore will not appear in search results, until their metadata has been updated. After the video’s metadata is updated, and the <yt:incomplete> element is removed from the metadata, then the video will be eligible for inclusion in YouTube’s search index.

Setting access controls for a video

When uploading (or updating) a video, you can specify access controls for that video. The table below defines the access controls that you can set for each video and lists the permissions that you can set for each control. The default setting for each control is marked with an asterisk.

To set access controls for a video, include one <yt:accessControl> tag for each control that you want to set as shown in the following example:

<item>
  ...
  <yt:accessControl action='videoRespond' permission='allowed'>
</item>

If you do not specify access control settings when you upload (or update) a video, YouTube will apply the default access controls for that video. If you only specify some access controls, then default settings will be applied for the unspecified controls. Finally, the API will return an error if you specify multiple permissions for the same access control, with the exception of the special use case for comments described below.

Setting special permissions for comments

The access control for comments also supports a special use case in which you can specify different permissions for friends than for other users. The XML excerpt below indicates that comments from the video owner’s friends are allowed but that the owner will moderate comments from other users. In the <yt:accessControl> tag that sets permissions for the user’s friends, the type attribute is set to group, and the tag value is set to friends.

<yt:accessControl action='comment' permission='moderated'>
<yt:accessControl action='comment' permission='allowed'
    type='group'>friends</yt:accessControl>

If you do set access controls for comments, your request must specify the permissions that you want to set for all users. For example, if you set access controls for friends, but not for other users, then the API will return an error.

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. Please note the following restrictions:

• Each developer tag must be at least three bytes long.
• Each developer tag cannot be longer than 25 bytes.
• The total length of all developer tags cannot exceed 240 bytes.

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

• 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.
• developer_key – This value uniquely identifies the application 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:

POST /action/GetUploadToken HTTP/1.1
Host: gdata.youtube.com
Authorization: AuthSub token="DXAA...sdb8"
GData-Version: 2
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-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 value:

• 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.
• developer_key – This value uniquely identifies the application 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-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.

Resumable uploads

This section explains how to upload videos using YouTube’s direct, resumable uploading process. Direct uploading lets you add videos to YouTube from your video library. In addition, resumable uploads can be restarted from the point of interruption if the connection between your application and YouTube is lost at any point during the uploading process.

You should choose a direct-upload implementation if either of the following conditions is true:

• You have a collection of videos that want to upload to YouTube.
• You want to host or store videos uploaded through your site and also add those videos to YouTube.
• You want to upload videos from a device with a low-bandwidth or unstable Internet connection, such as a mobile device.

If you implement direct uploading for a website, then when a user uploads a video to 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.

This page contains the following sections:

Step 1 – Uploading video metadata

To begin a resumable upload, send an HTTP POST request that contains the video filename and the metadata for the video to the following URL. Note that this URL is almost the same one that you would use for non-resumable direct uploading, with the difference being the addition of the resumable path prefix in the URL.

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

Note: In the above URL, the value default indicates that the logged-in user is resuming the upload. The authentication token that you submit with the request identifies the user. You can substitute a YouTube username in the URL as long as the authentication token that you submit with the request also identifies that user.

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

POST /resumable/feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: AuthSub token="<authentication_token>"
GData-Version: 2
X-GData-Key: key=<developer_key>
Content-Length: <content_length>
Content-Type: application/atom+xml; charset=UTF-8
Slug: <video_filename>

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

• 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.
• developer_key – This value uniquely identifies the application 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.
• video_filename – This value contains the file name of the source video that you are uploading.
• 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:

POST /resumable/feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: AuthSub token="DXAA...sdb8"
GData-Version: 2
X-GData-Key: key=adf15ee97731bca89da876c...a8dc
Content-Length: 1941255
Slug: my_file.mp4
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>

Uploading a video without metadata

When using the resumable uploading process, you can upload a video without specifying any metadata at all. In such cases, YouTube will handle the request as if it contained an entry that only included a <yt:incomplete> element. YouTube would then generate certain metadata values for the video as discussed in the metadata requirements for uploaded videos.

A resumable upload request that does not specify any metadata differs from the sample resumable upload request shown above in three ways:

• The Content-Length HTTP request header value must be 0.
• The Content-Type HTTP request header must be omitted from the request.
• The Atom XML entry is omitted from the request.

The example below shows an API request to upload a video without metadata using the resumable uploading process:

POST /resumable/feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: AuthSub token="DXAA...sdb8"
GData-Version: 2
X-GData-Key: key=adf15ee97731bca89da876c...a8dc
Content-Length: 0
Slug: my_file.mp4

Step 2 – Extracting the upload URL from the API response

When you submit an API request to upload video metadata, the API returns an HTTP response that contains a Location header, which identifies the URL that you will use to upload the actual video file. You need to extract this URL and use it to upload the video file.

The example below shows a sample API response to a request to upload video metadata for a resumable upload:

HTTP/1.1 200 OK
Location: http://uploads.gdata.youtube.com/resumableupload/AF8GKF...0Glpk0Aw
Date: Fri, 04 Dec 2009 16:14:30 GMT
Pragma: no-cache
Expires: Fri, 01 Jan 1990 00:00:00 GMT
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 0
Content-Type: text/html

Step 3 – Uploading the video file

After extracting the upload URL from the API response, you need to upload the actual video file content. You will upload the video content to the URL extracted in step 2. The example below demonstrates the format of the video upload request. Note that you do not need to provide any authentication headers in this step.

PUT <upload_url> HTTP/1.1
Host: uploads.gdata.youtube.com
Content-Type: <video_content_type>
Content-Length: <content_type>

<Binary_file_data>

Variables in the upload request

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

• upload_url – This value is the URL that you extracted in step 2 from the Location header of the API response for the metadata upload request.
• video_content_type – This value specifies 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.
• content_length – This value specifies the length, in bytes, of the entire body of the HTTP PUT request.
• Binary File Data – This value contains the binary code for the video file that you are uploading.

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

PUT /resumableupload/AF8GKF...0Glpk0Aw HTTP/1.1
Host: uploads.gdata.youtube.com
Content-Type: video/mpeg
Content-Length: 124905
<Binary File Data>

Step 4 – Completing the upload process

When you submit a request to upload the video content for a resumable upload, one of two scenarios could occur:

• If the upload completes, then the API returns a response indicating whether the upload succeeded or failed.
  • For a successful upload, the API returns an Atom entry that contains information about the uploaded video. The entry has the same format as an entry in a user’s uploaded videos feed, and the response may contain properly escaped HTML tags. The Checking the status of an uploaded video section explains how to check the status of the uploaded video.
  • For an unsuccessful upload, the response contains an error response that helps to explain the cause of the upload failure.
• If the upload fails because the connection between the YouTube server and your application is lost, then your application will not receive an API response. In this case, you may be able to resume the upload from the point of the interruption. The following steps explain how to resume a video upload:
  Checking the current status of an upload
  Resuming a resumable upload

  Checking the status of a resumable upload

  To query the status of an interrupted resumable upload, send an empty HTTP PUT request to the upload URL that you retrieved in step 2 and also used in step 3. In your request, you need to set the Content-Range header value to bytes */* as shown in the following example:

  PUT <upload_url> HTTP/1.1
  Host: uploads.gdata.youtube.com
  Content-Range: bytes */*
  

  If the upload URL refers to an upload that completed, regardless of whether the upload succeeded or failed, the API will return the same response that it sent when the upload originally completed. As discussed above, if the upload succeeded, the response will contain an Atom entry. If the upload failed, the response will contain the original error response.

  However, if the upload was interrupted by a lost connection, the API will return a 308 HTTP response code (Resume Incomplete). The sample response below shows the format of an API response for an upload that can still be completed:

  308 Resume Incomplete
  content-length: 0
  expires: Fri, 01 Jan 1990 00:00:00 GMT
  range: bytes=0-408
  pragma: no-cache
  cache-control: no-cache, no-store, must-revalidate
  date: Fri, 04 Dec 2009 13:45:41 GMT
  content-type: text/html
  

  In the response, the range header indicates how many bytes from the video file have already been successfully uploaded to YouTube. The bytes are indexed from 0. Thus, the sample response above indicates that the first 409 bytes of the file were received. If nothing has been uploaded yet, the range header will be absent from the response.

  Note: The API response for an upload that can still be completed may use the Location header to specify a new unique upload URI that your application should use to complete the upload. Your client should check the API response for an updated location and, if one is present, use it to upload the remaining data.

  Resuming an upload

  To resume the upload, you will submit a new HTTP PUT request to the upload URL captured in step 2. The resumed upload request has the following format:

  PUT <upload_url> HTTP/1.1
  Host: uploads.gdata.youtube.com
  Content-Type: <video_content_type>
  Content-Length: <content_length>
  Content-Range: bytes <first_byte>-<last_byte>/<total_content_length>
  
  <Partial Binary File Data> 
  

  Variables in the resumed upload request

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

  • upload_url – This value is the upload URL that you extracted in step 2.
  • video_content_type – This value specifies 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.
  • content_length – This value specifies the length, in bytes, of the entire body of the HTTP PUT request. If you are uploading the remainder of a video file, you can calculate this value by subtracting the first_byte from the total_content_length. (Both of these values are defined below.)
  • The Content-Range header specifies the part of the video file that you are uploading. The header specifies three values:
    • The first_byte specifies the 0-based numeric index of the byte number from which you are resuming the upload. This value will be one number higher than the second number in the range header retrieved in the previous step. In the previous example, the range header value was 0-408. The first byte in a subsequent resumed upload would be 409.
    • The last_byte specifies the 0-based numeric index of the last byte included in the binary file that you are uploading. Typically, this will be the last byte in the file. In step 3, the Content-Length header value was 124905. Thus, the last byte in the file would be number 124904.
    • The total_content_length specifies the total size of the video file in bytes. This value is the same as the Content-Length submitted in the original upload request.
  • Binary File Data – This value contains the binary code for the portion of the video file that you are uploading.

  The example below shows a sample request to resume an upload:

  PUT /resumableupload/AF8GKF...0Glpk0Aw HTTP/1.1
  Host: uploads.gdata.youtube.com
  Content-Type: video/mpeg
  Content-Length: 124496
  Content-Range: bytes 409-124904/124905
  
  Partial Binary File Data
  

  Note: You cannot upload a noncontinuous block of the binary file. If you try to upload a noncontinuous block, none of the remaining binary content will be uploaded. As such, the first byte in the upload request must be the next byte after the last byte successfully uploaded to YouTube as identified in the range header of the 308 HTTP response. Thus, if the last byte in the range header is 408, the first byte in the request to resume the upload must be byte 409 (using a 0-based index). If you try to resume the upload from byte 408 or lower (overlapping bytes) or byte 410 or higher (skipping bytes), none of the binary content will be uploaded.

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/USER_ID/uploads/VIDEO_ID'>

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:accessControl
• yt:location
• yt:private
• 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. Similarly, if you do not specify access control settings when updating a video, YouTube will restore the default access control settings for that video. If you only specify some access control settings in an update, the unspecified controls will be restored to their default settings.

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-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>
  <yt:accessControl action="comment" permission="allowed"/>
  <yt:accessControl action="commentVote" permission="allowed"/>
  <yt:accessControl action="videoRespond" permission="allowed"/>
  <yt:accessControl action="rate" permission="allowed"/>
  <yt:accessControl action="list" permission="allowed"/>
  <yt:accessControl action="embed" permission="allowed"/>
  <yt:accessControl action="syndicate" permission="allowed"/>
</entry>

Updating a video with incomplete metadata

If a video entry contains a <yt:incomplete> element, you must remove that element before updating the entry. The element’s presence indicates that when the video was uploaded, it was flagged as having incomplete metadata. Consequently, YouTube may have automatically generated some of the video’s metadata values, such as its title, category, or keywords.

A video that was uploaded with incomplete metadata will not be included in YouTube’s search index and, therefore, will not appear in search results. After the video’s metadata has been updated, and the <yt:incomplete> element has been removed, the video will subsequently be eligible to be included in YouTube’s search index.

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-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. You can add captions to a video via the API by creating a caption track and uploading it. YouTube supports a variety of caption file formats, including plain text transcripts.

YouTube may also use automatic speech recognition (ASR) to generate a caption track for a video.

This section discusses the caption file formats that YouTube supports. It also explains how to use the API to create, retrieve, update and delete caption files. These issues are explained in the following subsections:

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 two entries. The first entry contains a <yt:derived> tag that indicates that the track was generated using automatic speech recognition.

<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:yt='http://gdata.youtube.com/schemas/2007'
  gd:etag='W/"DkcNRH4zfSp7ImA9WxJXEUk."'>
  <id>tag:youtube.com,2008:videos:EdDc7sWjCL4:captions</id>
  <updated>2010-08-18T22:42:42.179Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#captionTrack'/>
  <title>
    Caption Tracks for Learn about HTML5 and the Future of the Web
  </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/EdDc7sWjCL4?v=2'/>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
     href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions?...'/>
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions?v=2'/>
  <link rel='service' type='application/atomsvc+xml' 
    href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions?alt=...'/>
  <author>
    <name>GoogleDevelopers</name>
    <uri>http://gdata.youtube.com/feeds/api/users/googledevelopers</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:ChkLEO3ZhwUaEAi-kYyt7J236BESAmVuGgAM</id>
    <published>2010-06-09T06:31:35.256-07:00</published>
    <updated>2010-06-09T06:31:35.256-07:00</updated>
    <app:edited>2010-06-09T06:31:35.256-07:00</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#captionTrack'/>
    <title/>
    <content type='application/vnd.youtube.timedtext'
      src='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captiondata/ChkLEO...'
      xml:lang='en'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/ChkLEO...'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/ChkLEO...'/>
    <link rel='edit-media' type='application/vnd.youtube.timedtext'
      href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captiondata/ChkLEO...'/>
    <yt:derived>speechRecognition</yt:derived>
  </entry>
  <entry gd:etag='W/"DkECQHk5cSp7ImA9WxJSGEw."'>
    <id>tag:youtube.com,2008:captions:CiMLEO3ZhwUaGgi-kYyt7J236B...</id>
    <published>2010-06-20T23:46:22.156-07:00</published>
    <updated>2010-06-20T23:46:22.156-07:00</updated>
    <app:edited>2010-06-20T23:46:22.156-07:00</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#captionTrack'/>
    <title>auto-timed</title>
    <content type='application/vnd.youtube.timedtext'
      src='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captiondata/CiMLEO...'
      xml:lang='en'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/CiMLEO...'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/CiMLEO...'/>
    <link rel='edit-media' type='application/vnd.youtube.timedtext'
      href='http://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captiondata/CiMLEO...'/>
  </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-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 request below demonstrates how to retrieve a caption track:

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

Note that 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.

If you are retrieving a track that YouTube generated using automatic speech recognition (ASR), then you must also use the fmt parameter to specify the format in which the track should be returned. (In a caption tracks feed, the <yt:derived> tag indicates whether a track was generated using ASR.) If you do not specify a format when retrieving an ASR track, the API server will return an HTTP 400 response code (Bad Request).

The API supports two additional options for retrieving caption tracks:

Note: YouTube does not save translated or reformatted caption tracks that you request through the API, and those tracks will not appear in the list of caption tracks available for a video. You can upload a translated or reformatted track, however, to make it available to viewers.

Retrieving a translation of a caption track

To retrieve a translation of a caption track, append the lang parameter to the src URL specified in the <content> tag of the caption track entry. Set the parameter value to the ISO 639-1 two-letter language code that identifies the desired caption language.

The request below demonstrates how to retrieve a translated caption track:

GET /feeds/api/videos/VIDEO_ID/captiondata/TRACK_ID?lang=ISO_639_CODE HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

If your request is successful, the response will contain the translated caption track in the same format that you uploaded the original track to YouTube. If a translation cannot be generated, or if the language code that you specified is not a valid value, the API will return an HTTP 400 response code.

Retrieving a caption track in an alternate format

To retrieve a caption track in a different format than the one you originally uploaded, append the fmt parameter to the src URL specified in the <content> tag of the caption track entry. Set the parameter value to one of the following values:

• sbv – Subviewer-compatible
• srt – Subrip-compatible

The request below demonstrates how to retrieve a caption track in an alternate format:

GET /feeds/api/videos/VIDEO_ID/captiondata/TRACK_ID?fmt=TARGET_FORMAT HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

You can specify a target language and a target format by specifying values for both the lang and fmt parameters.

If YouTube cannot convert the original caption track to the requested format, the API will return an HTTP 400 response code.

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-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-Key: key=DEVELOPER_KEY

Using community features

Ratings

The YouTube API allows users to rate videos, and it also returns rating information in any feed entry that contains information about a video. As such, ratings information appears in video feed entries, favorite videos feed entries, playlist feed entries, and so forth. (Playlist feed entries identify individual videos in a specific playlist.) Ratings information also appears in user event feeds when an event describes a user’s rating of a video.

YouTube currently uses a rating system that lets users indicate whether they like or dislike a video. However, until March 2010, YouTube used a 1-5 rating system in which 1 was the lowest rating that could be given. The YouTube API currently supports both rating systems and uses different XML elements to provide rating information for each system:

• The <yt:rating> element contains information about the number of users who gave the video a positive or negative rating as well as the total number of ratings that the video received. The totals do account for ratings that were given using the 1-5 rating system. This element is only returned if the video has been rated.

  The XML excerpt below shows how this element appears in an API response:

  <feed>
    <entry>
      ...
      <yt:rating numDislikes='28' numLikes='143'/>
    </entry>
  </feed>
  

• The <gd:rating> element identifies the rating scale (1-5), the number of ratings that the video received, and the video’s average rating. Again, the figures also account for ratings that were submitted using the like-or-dislike system, with positive and negative ratings equating to scores of 5 and 1, respectively. This element is only returned if the video has been rated.

  The XML excerpt below shows how this element appears in an API response:

  <feed>
    <entry>
      ...
      <gd:rating average='4.24' max='5' min='1' numRaters='171'
          rel='http://schemas.google.com/g/2005#overall'/>
    </entry>
  </feed>
  

  Note: The <gd:rating> element has been deprecated. The API will stop supporting the 1-5 rating system at the end of the deprecation period explained in our Terms of Service.

Rating information in JSON-C responses

Ratings information for the like-or-dislike rating system is communicated in JSON-C feeds using the following properties:

• likeCount – The number of voters who liked the video. This tally includes ratings submitted using the 1-5 rating system.
• ratingCount – The total number of voters who have rated the video using either rating system. The number of voters who disliked the video can be calculated by subtracting the likeCount from the ratingCount.
• rating – The average rating, calculated on a 1-5 scale, for the video. For ratings submitted using the like-or-dislike system, positive ratings are assigned a score of 5, and negative ratings are assigned a score of 1.

The JSON-C excerpt below shows how these properties will appear in a JSON-C feed:

{
 "data": {
   "id": "XrMTsMDUle8",
   ...
   "likeCount": 143,
   "ratingCount": 171,
   "rating": 4.24,
   ...
 }
}

Rating information in JSON responses

Ratings information for the like-or-dislike rating system is communicated in JSON feeds using the yt$rating property and its child properties:

• numLikes – The number of voters who liked the video. This tally includes positive ratings submitted using the 1-5 rating system.
• numDislikes – The number of voters who liked the video. This tally includes negative ratings submitted using the 1-5 rating system.

The JSON excerpt below shows how these properties will appear in a JSON feed:

{
 "version": "1.0",
 "encoding": "UTF-8",
 "entry": {
   "xmlns$app": "http://www.w3.org/2007/app",
   ...
   "yt$rating": {
     "numDislikes": 28,
     "numLikes": 143
   }
 }
}

Adding a rating

Every feed entry that describes a video contains a <link> element that identifies the URL to use to add a rating to that video. Since each entry includes several <link> element, you must use the URL from the element 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.ratings'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/ratings'/>
  </entry>
</feed>

To add a rating to a video, send an authenticated HTTP POST request to the video’s ratings URL. The user who is rating the video must be identified by the authentication token. To change a user’s rating of a video, send another POST request that identifies the new rating. The API does not support rating changes via HTTP PUT requests. The API also does not let users delete ratings.

The following sections explain how to add ratings using either the like-or-dislike rating system (<yt:rating>) or the numeric rating system (<gd:rating>). If you include both types of ratings in a request to add a rating, YouTube will ignore the numeric rating unless the <gd:rating> tag or one of its attributes specifies an invalid value, which will instead generate an error.

Adding a ‘like’ or ‘dislike’ video rating

The following XML demonstrates how to add a rating to a video using the like-or-dislike rating system. Please note that the <yt:rating> element’s value attribute can be set to either like or dislike.

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-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:rating value="like"/>
</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 <yt:rating> element’s value attribute.

Adding a numeric (1-5) video rating

The following XML demonstrates how to add a rating to a video using the 1-5 rating system. Please note that the <gd:rating> element’s value attribute must be an integer between 1 and 5 that identifies the rating being given. As noted above, the <gd:rating> element has been deprecated.

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-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. The API will return an error if your original request specifies an invalid value for the <gd:rating> element’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-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-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-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-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-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

To add a favorite video, you must provide the video ID that YouTube uses to uniquely identify that video. The following request shows the URL and format of an XML request to add 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-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-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-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-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, 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-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 that the user created. To update the position of a playlist entry, send an authenticated HTTP PUT request to the following URL, replacing PLAYLIST_ID and PLAYLIST_ENTRY_ID with the appropriate values:

http://gdata.youtube.com/feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID

The following sample request illustrates the XML format for modifying a playlist entry.

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-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-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-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 notifies a user when new videos are added to a channel or when another user takes one of several actions on YouTube, such as uploading a video, rating a video, or commenting on a video. 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 retrieve, 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. Each entry contains a <category> tag for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. The value of that tag’s term attribute identifies the type of subscription that the entry represents.

• If the feed entry describes a subscription to another user’s activities, the <category> tag’s term attribute will have a value of user.
• If the feed entry describes a channel subscription, the <category> tag’s term attribute will have a value of channel.

In addition, the entry will also contain the <yt:username> element, which specifies the user whose activities are associated with the subscription or the channel associated with the subscription.

The following XML shows a sample API response containing a subscriptions feed. The entries in the response show a user activity subscription, followed by a channel subscription. The <content> tag in each entry specifies the URL for retrieving videos for the subscription. Note that an entry for a user activity subscription will only contain the <content> tag if your request to retrieve subscriptions specifies a developer key.

<?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/"CEAHQX47eCp7ImA9WxBSEUQ."'>
    <id>tag:youtube.com,2008:user:andyland74:subscription:ps2fD3tG7-s</id>
    <published>2009-12-18T19:18:50.000-08:00</published>
    <updated>2009-12-18T19:18:50.000-08:00</updated>
    <app:edited>2009-12-18T19:18:50.000-08:00</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='user'/>
    <title>Activity of : TrustNordisk</title>
    <content type='application/atom+xml;type=feed'
        src='http://gdata.youtube.com/feeds/api/users/trustnordisk/events?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/user/TrustNordisk'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/ps2fD3tG8-s?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/ps2fD3tG8-s?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <media:thumbnail url='http://s.ytimg.com/yt/img/no_videos_140-vfl121214.png'/>
    <yt:username> TrustNordisk</yt:username>
  </entry>

  <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>
</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 submit an HTTP POST request that identifies the YouTube user name for the authenticated user who is creating the subscription. The body of the POST request is an XML entry that contains the following elements:

• The <category> tag identifies the type of subscription that the user is creating. Set the tag’s term attribute value to user to indicate that the user is subscribing to another user’s activities (uploading videos, ratings, marking videos as favorites, etc.), or set the term attribute value to channel to indicate that the user is subscribing to a channel.
• The <yt:username> tag identifies the channel or the user whose activity is being subscribed to.

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

Subscribing to a user’s activities

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-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="user"/>
    <yt:username>andyland74</yt:username>
</entry>

If a user creates a subscription to another user’s activities and already has a subscription to the other user’s channel, the user activity subscription will replace the channel subscription.

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

If a user creates a subscription to another user’s channel and already has a subscription to the other user’s activities, the channel subscription will replace the user activity subscription.

The following steps explain a common use case for creating subscriptions, in which a user watches a video and subscribes to the video owner’s activity or 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 activity or 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 user if you are creating a user activity subscription or channel if you are creating a channel subscription.

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-Key: key=DEVELOPER_KEY

The following steps explain a common use case for deleting a subscription, in which a user looks at his list of subscriptions and removes one or more subscriptions 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, including the number of people who have viewed the user’s channel, the number of videos the user has watched, the number of people who subscribe to the user’s uploaded videos, and the total number of views for all of the user’s 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 lastWebAccess='2008-02-25T16:03:38.000-08:00'
      viewCount='9' videoWatchCount='21' subscriberCount='1'
      totalUploadViews='124'/>
  <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

  If you try to retrieve contacts for the default user without providing proper authentication, the API returns a 401 (User authentication required) HTTP response.

• To request another user’s contact list, send an HTTP GET request to the following URL. In the URL, you must replace the text username with the user’s YouTube username.

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

  This request does not require authentication, but you will only be able to retrieve the contacts of users who display the Friends module on their channel pages. (If a user’s contacts are displayed on the user’s channel, then the user is already making the contact list public, and YouTube therefore allows API clients to access that same information.)

  If you try to retrieve contacts for a specific user who does not display the Friends module on his channel, the API will return a 403 (Forbidden) HTTP response.

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-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-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-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-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-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 <yt:rating> tag specifies the rating given to the video. Activity feeds only identify videos that were given positive (‘like’) ratings.
    • The <gd:rating> tag identifies a numeric 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.

If you set the inline parameter value to true when retrieving an activity feed, then any event that involves a video – video_rated, video_shared, video_favorited, video_commented and video_uploaded – will include a video entry that contains all of the metadata for that video. The video entry will be encapsulated inside the <link> element that has a rel attribute value of http://gdata.youtube.com/schemas/2007#video. This feature is discussed in more detail in the Retrieving additional metadata for activity feed entries section.

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:VGF5Wm9uZNzQ5MzM%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 metadata about videos associated with particular events, you can either use the inline parameter or you can submit a batch processing request. Both of these options are explained below.
• To retrieve additional metadata about users associated with particular events, you can submit a batch processing request.

Using the inline parameter

If you set the inline parameter value to true when retrieving an activity feed, then any event that involves a video – video_rated, video_shared, video_favorited, video_commented and video_uploaded – will include a video entry that contains all of the metadata for that video. The video entry will be encapsulated inside the <link> element that has a rel attribute value of http://gdata.youtube.com/schemas/2007#video.

The sample feed below shows how an inlined video entry appears in an activity feed. The video entry appears in italics in the sample feed, and the event entry in the XML is the same one that appears in the Sample activity feed section. Only a few tags from the video entry are shown in the example, though an actual feed would contain a complete video entry.

<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;'>
  <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>
  <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."'>
    <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'/>

      <entry gd:etag='W/"CUECRX47eCp7ImA9WxBbF0g."'>
        <id>z3U0kuLH974</id>
        <published>2010-03-13T22:45:09.000Z</published>
        <updated>2010-03-16T15:34:24.000Z</updated>
        <category scheme='http://schemas.google.com/g/2005#kind'
          term='http://gdata.youtube.com/schemas/2007#video'/>
        <category scheme='http://gdata.youtube.com/schemas/2007/categories.cat'
          term='People' label='People & Blogs'/>
        ...
      </entry>

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

Submitting a batch processing request

You can submit a batch processing request to retrieve additional information about the videos or users identified in an activity feed. 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 batch processing 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"/>

Retrieving a partial response (Experimental )

Important: This is an experimental feature, which means that it might change unexpectedly.

The YouTube Data API, like several other GData APIs, enables you to submit an API request in which you specify the fields that will be included in the API response. By only requesting information that it will actually display, a client application can more efficiently use network, CPU and memory resources. By contrast, an application that retrieves a full API feed, parses it and then drops unused fields is likely to waste some resources along the way.

This section explains how to submit requests for partial feeds and also describes the format of the API responses to those requests.

Submitting a request for a partial feed response

To request a partial API response, add the fields parameter to the URL that you would use to retrieve the full API response. This parameter can be used for either or both of the following purposes:

• It can specify the data fields that will be included in the API response. When used in this context, the parameter limits the data fields that are returned for the feed or for specific entries in the feed. However, it does not affect which entries are included in the result set.
• It can filter the entries in the result set by ensuring that they match specific criteria. For example, you could use this parameter to specify that the API should only return entries for videos with more than 20 views, where the view count for each entry is identified in an XML element in the feed. In this case, the parameter does not necessarily affect the number of data fields that the API returns for an entry, but it can affect the number of entries actually returned.

  Note: The API handles filters identified in the fields parameter value differently than filters identified in other query parameters, such as the category or q parameters. The examples below demonstrate how the API processes the fields parameter value when it is used as a filter:

  • This example shows a simple query that retrieves the first 10 videos matching the keyword “surfing.” It does not use the fields parameter to filter results.

    GET http://gdata.youtube.com/feeds/api/videos?q=surfing&max-results=10

  • This example uses the fields parameter to filter the results that would have been obtained in the previous example. The query specifies that the API should return videos that match the keyword “surfing” and that have more than 1,000,000 views:

         GET http://gdata.youtube.com/feeds/api/videos?q=surfing&max-results=10 \
           &fields=entry[yt:statistics/@viewCount > 1000000]

    In this case, the API retrieves the first 10 results matching the keyword “surfing” and then applies the view count filter. If two of the first 10 results have more than 1,000,000 views, then the API will only return two results. Since this example shows results ordered by relevance, which is the default behavior, there may be additional results with more than 1,000,000 views.

    You may be able to use the orderby parameter to avoid this behavior. For example, if you request videos matching the keyword “surfing” and order results by view count, then all videos with more than 1,000,000 views will appear at the beginning of the results feed.

The example below demonstrates how to request a feed of a user’s uploaded videos that only contains the title, number of comments (and comment URL), and viewing statistics for each video:

http://gdata.youtube.com/feeds/api/users/default/uploads?
    fields=entry(title,gd:comments,yt:statistics)

Note: The fields parameter can be used with any API request that returns a feed, including GET, POST, and PUT requests. In the case of POST and PUT requests, the parameter only affects the API response. It does not affect the data that you are required to provide or the way that YouTube handles the request. For example, if you set the fields parameter value to title on a PUT request, you are not just updating the title of the associated entry. Rather, you will be updating the entire entry, but the API response will only contain the title of the updated entry.

Formatting the fields parameter value

The fields parameter value is formatted using a syntax inspired by XPath. Note, however, that this syntax does not support many expressions that are valid in XPath.

The guidelines below list several basic rules for formatting the parameter value and provide examples for each rule to explain how the parameter value affects the API response. The table below the list identifies all of the syntax that the API supports for the parameter value. The API will return a 400 HTTP response code (Bad Request) if the value uses unsupported syntax or is otherwise invalid.

• The parameter value is a comma-delimited list of fields, and each field is specified relative to the root element in the API response. Thus, if you are retrieving a feed, fields are specified relative to the <feed> tag, and if you are retrieving a single entry, fields are specified relative to the <entry> tag. You can also use parentheses to filter a response so that it only contains a particular set of child elements.

  Example 1: Retrieve number of items in feed, index of
  first item in result set, and all entries in the feed:
  
      fields=openSearch:totalResults,openSearch:startIndex,entry
  
  Example 2: Retrieve the title, player URL, and thumbnail images for a single
  video entry. Note that this example uses parentheses to list the child elements
  of <media:group> that should be included in the API response.
  
      fields=title,media:group(media:player,media:thumbnail)
  

• You can specify that an API response should only include the text content for a particular element or that it should only include certain attributes for that element. Just as you use parentheses to specify that a response should only contain particular child elements, you also use parentheses to specify whether the response should include the text content and/or attributes for a particular element. If you do not specify otherwise, the response will include the text content and all attributes for any element included in the response.

  Example 1: Retrieve all <entry> tags in feed, including any 
  attributes of the <entry> tag as well as all subtags in those entries,
  but do not retrieve other subtags of <feed>:
  
      fields=entry
  
  Example 2: Retrieve all <entry> tags in feed, but only include the
  <media:group> tag and all of its subtags in each entry. Do not
  retrieve attributes of the <entry> tag or other subtags of <feed>:
  
      fields=entry(media:group)
  
  Example 3: Retrieve all thumbnail URLs for the entries in the feed. The 
  response will be a feed of <entry> tags, each of which contains a
  <media:group> tag. Each <media:group> tag will contain a list of
  <media:thumbnail> tags that provide a value for their url attribute
  but do not include any other attributes:
  
      fields=entry(media:group(media:thumbnail(@url)))
  
  Example 4: Retrieve the <title>, <content> and <media:category>
  tags for videos in the result set. For each <media:category> tag, only
  return the tag's text content and the label attribute. The
  release notes discuss this feature and the evolution of the query syntax
  for partial responses in more detail.
  
      fields=entry(title,content,media:group(media:category(@label,text())))
  

• By default, if your request specifies an element that occurs more than once, the partial response will include all instances of that element. However, you can also specify that the response should only include elements that have a particular attribute value as shown in the examples below.

  Example 1: Retrieve title as well as all link elements and
  all thumbnail images for all feed entries:
  
      fields=entry(title,link,media:group(media:thumbnail))
  
  Example 2: Retrieve title, edit link and
  all thumbnail images for all feed entries:
  
      fields=entry(title,link[@rel='edit'],media:group(media:thumbnail))
  
  Example 3: Retrieve title, self and edit links
  and all thumbnail images for all feed entries:
  
      fields=entry(title,link[@rel='self' or @rel='edit'],media:group(media:thumbnail))
  
  Example 4: Retrieve title, edit link and all
  90-pixel-high thumbnail images for all feed entries:
  
      fields=entry(title,link[@rel='edit']media:group(media:thumbnail[@height='90']))
  

Retrieving videos for playback on mobile devices

To ensure that an API response only contains videos that are suitable for playback on a mobile device, set the fields parameter to the following value. Note that the hash character (#) that appears in the parameter value must be escaped (%23).

fields=entry[link/@rel='http://gdata.youtube.com/schemas/2007%23mobile']

If you are developing an application for mobile devices, you may also want to specify the mobile projection in API requests.

Supported syntax

The following table shows a complete list of supported syntax for the fields parameter value:

Handling a partial feed response

When you submit a partial retrieval request, the API will return an XML response in which the root element is the <gd:partial> tag. That tag will contain the requested subset of the typical API response.

The following XML shows the sample request from the previous section and the API response to that request. (The request is for the titles, comment counts, and viewing statistics for the authenticated user’s uploaded videos.)

Request:
GET /feeds/api/users/default/uploads?fields=@gd:*,entry(@gd:*,title,gd:comments,yt:statistics)
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

Response:
<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/' 
    xmlns:gd='http://schemas.google.com/g/2005' 
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    gd:etag='W/"Dk8BGDw9cSp7ImA9WxBWGE8."'
    gd:fields='entry(title,gd:comments,yt:statistics)'>
  <entry gd:etag='W/"Ef2SLAw9cSp7ImA9WxBWGE8."'
        gd:fields='@gd:*,title,gd:comments,yt:statistics'>
    <title>Why is Google Chrome Fast? Spotlight on DNS pre-resolution</title>
    <gd:comments>
      <gd:feedLink
          href='http://gdata.youtube.com/feeds/api/videos/FhDDwmOyRmk/comments?v=2'
          countHint='46'/>
    </gd:comments>
    <yt:statistics favoriteCount='25' viewCount='13050'/>
  </entry>
  <entry gd:etag='W/"L9UkCD19cSp7ImA9WxBWGE8."'
        gd:fields='@gd:*,title,gd:comments,yt:statistics'>
    <title>Why is Google Chrome Fast? Spotlight on DOM bindings</title>
    <gd:comments>
      <gd:feedLink
          href='http://gdata.youtube.com/feeds/api/videos/8QRTkPrFbVQ/comments?v=2'
          countHint='0'/>
    </gd:comments>
    <yt:statistics favoriteCount='37' viewCount='6888'/>
  </entry>
  <!-- more entries -->
</feed>

Submitting partial update (PATCH) requests (Experimental )

Important: This is an experimental feature, which means that it might change unexpectedly.

This section explains how to send an HTTP PATCH request to only update specific metadata fields for an entry in a YouTube API feed. You can send a single PATCH request to add, replace and/or delete specific fields for a particular resource.

Submitting a partial update request

To add, update or delete specific metadata fields for a resource, your application will send an HTTP PATCH request to the same URL that you would normally use to update the resource with an HTTP PUT request. The body of the PATCH request is an <entry> that only contains the fields that you want to update.

The example below shows the format for a request to update the title and keywords for a video without changing any other video metadata:

PATCH /feeds/api/users/USER_ID/uploads/VIDEO_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY


<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields=media:group(media:title,media:keywords)>
  <title>New title</title>
  <media:group>
    <media:title type="plain">New title</media:title>
    <media:keywords>new, keywords, fancy multi-word keyword</media:keywords>
  </media:group>
</entry>

Formatting a partial update request

The body of the PATCH request is an XML document that identifies the metadata that you are adding, updating or deleting, and a single PATCH request can perform any combination of these operations at once. In a PATCH request, you can modify any of the following elements:

• media:title
• media:description
• media:category
• media:keywords
• yt:accessControl
• yt:location
• yt:private
• gml:pos

The guidelines below explain the format of a PATCH request. Also see the Changing access controls with partial updates section below for more details about updating access controls.

1. If you identify an element in the <entry> tag’s gd:fields attribute value, the element will be deleted from the resource. For example, the following request deletes the location and geographic coordinates associated with a video:

   <entry xmlns='http://www.w3.org/2005/Atom'
       xmlns:media='http://search.yahoo.com/mrss/'
       xmlns:yt='http://gdata.youtube.com/schemas/2007'
       xmlns:gd='http://schemas.google.com/g/2005'
       xmlns:gml="http://www.opengis.net/gml'
       xmlns:georss="http://www.georss.org/georss'
       gd:fields='yt:location,georss:where'/>

   In this example, the gd:fields attribute specifies that the <georss:where> element should be deleted even though the <gml:pos> element actually contains the geographic coordinates for the video. However, since <gml:pos> is a required child element of <gml:Point>, which, in turn, is a required child element of <georss:where>, you must delete the full contents of <georss:where> to delete the coordinates associated with a video.

   You also cannot delete required elements, such as <media:title>, unless you replace them with new values.

   If the gd:fields attribute value in your request specifies an element that has child elements, then the API will try to delete the element and all of its children. For example, to delete the geographic coordinates associated with a video, which are specified in the <gml:pos> element, you can set the gd:fields value to georss:where. In processing the request, the API server will delete the <georss:where> element from the resource as well as its child element, <gml:Point>, and that element’s child element, which is <gml:pos>.

2. If you identify an element in the <entry> tag’s gd:fields attribute value, and you also include that element in the XML request, then the element in the XML request will replace the existing element. For example, the following request replaces the title of a video:

   <entry xmlns='http://www.w3.org/2005/Atom'
       xmlns:media='http://search.yahoo.com/mrss/'
       xmlns:yt='http://gdata.youtube.com/schemas/2007'
       xmlns:gd='http://schemas.google.com/g/2005'
       gd:fields='media:group/media:title'>
     <media:group>
       <media:title type='plain'>New video title</media:title>
     </media:group>
   </entry>

   Note: To avoid any ambiguity in your request, we recommend that you always use the gd:fields attribute to list the specific elements that you want to replace.

   This syntax also lets you add a metadata field to a resource. For example, the following request makes a video private:

   <entry xmlns='http://www.w3.org/2005/Atom'
       xmlns:media='http://search.yahoo.com/mrss/'
       xmlns:yt='http://gdata.youtube.com/schemas/2007'
       xmlns:gd='http://schemas.google.com/g/2005'
       gd:fields='media:group/yt:private'>
     <media:group>
       <yt:private/>
     </media:group>
   </entry>

3. Elements that appear in the XML request but that are not identified in the <entry> element’s gd:fields attribute value are merged into the existing metadata for the resource according to the following rules:
   1. If the resource does not already contain an element that appears in the PATCH request, then the new element – including its content, attributes, and child elements – is added to the resource. For example, if a video is not associated with a set of geographic coordinates, and your PATCH request contains a <gml:pos> tag, the coordinates specified in that tag are associated with the video.
   2. If a non-repeating element in the PATCH request already appears in the resource, and the element does not have child elements, then the new element in the request replaces the existing element in the resource. For example, a video can only be associated with one location. As such, if a video is associated with a location, and your PATCH request contains a <yt:location> tag, the location specified in the request replaces the one already associated with the video. As a result, the following request has the same effect even if you do not include the <entry> tag’s gd:fields attribute.

      <entry xmlns='http://www.w3.org/2005/Atom'
          xmlns:media='http://search.yahoo.com/mrss/'
          xmlns:yt='http://gdata.youtube.com/schemas/2007'
          xmlns:gd='http://schemas.google.com/g/2005'>
        <yt:location>New location</yt:location>
      </entry>

      All of the fields that can be updated in the YouTube API are non-repeating elements with the exception of <yt:accessControl>, which is discussed in the Changing access controls with partial updates section below.

   3. If a non-repeating element in the PATCH request already appears in the resource, and the element has child elements, then the child elements included in the request will replace the corresponding child elements in the resource. However, child elements that are not included in the PATCH request will not be affected by the update. For the YouTube API, this rule only applies to partial updates of the <media:group> element and its children.

      For example, the request below does not specify a value for the <entry> element’s gd:fields attribute. As a result, the API server would handle this request by only replacing child elements of the <media:group> element that are specified in the PATCH request. In this case, the request would update the video’s title and make the video private. The request would not affect the existing values of the <media:category>, <media:description> or <media:keywords> elements.

      <entry xmlns='http://www.w3.org/2005/Atom'
          xmlns:media='http://search.yahoo.com/mrss/'
          xmlns:yt='http://gdata.youtube.com/schemas/2007'
          xmlns:gd='http://schemas.google.com/g/2005'>
        <media:group>
          <media:title type='plain'>New video title</media:title>
          <yt:private/>
        </media:group>
      </entry>

Changing access controls with partial updates

Following the guidelines in the previous section, the examples below demonstrate how to update access controls for a video. Access controls, which are specified in the <yt:accessControl> element, determine whether users are allowed to rate a video, add comments about the video, rate comments about the video, add a video response to the video, or embed the video on third-party websites. Another setting indicates whether YouTube can show the video on Youtube properties other than the YouTube.com website.

Note: Each access control specifies a default setting. As a result, if you delete an access control but do not provide a new setting for it, the control will revert to its default setting. See the Uploading Videos section for more information about default access control settings.

• To delete the access controls for a video and insert new controls, use the <entry> tag’s gd:fields attribute to remove the existing controls. Then specify the new control settings in the XML that you submit for the request as shown below:

  <entry xmlns='http://www.w3.org/2005/Atom'
      xmlns:yt='http://gdata.youtube.com/schemas/2007'
      xmlns:gd='http://schemas.google.com/g/2005'
      gd:fields='yt:accessControl'>
    <yt:accessControl action='comment' permission='allowed'/>
    <yt:accessControl action='commentVote' permission='allowed'/>
    <yt:accessControl action='embed' permission='allowed'/>
    <yt:accessControl action='rate' permission='allowed'/>
    <yt:accessControl action='list' permission='allowed'/>
    <yt:accessControl action='syndicate' permission='allowed'/>
    <yt:accessControl action='videoRespond' permission='allowed'/>
  </entry>

• To replace one access control without changing other control settings, use the <entry> tag’s gd:fields attribute to identify the setting you want to replace. In this case, you need to define the gd:fields value narrowly to avoid deleting other tag values that you want to keep.

  The request below updates a video so that it can be embedded on other websites. The request does not affect other access controls for the video. The gd:fields value instructs the API to delete the <yt:accessControl> tag that has an action of embed. The <yt:accessControl> tag in the XML request specifies a new embed setting that replaces the deleted one.

  <entry xmlns='http://www.w3.org/2005/Atom'
      xmlns:yt='http://gdata.youtube.com/schemas/2007'
      xmlns:gd='http://schemas.google.com/g/2005'
      gd:fields='yt:accessControl[@action="embed"]'>
    <yt:accessControl action='embed' permission='allowed'/>
  </entry>

• As described in the Uploading videos section, there is a special access control setting that lets you allow friends to submit comments on a video but moderate comments from other users. The example below shows how to enable this setting in a PATCH request:

  <entry xmlns='http://www.w3.org/2005/Atom'
      xmlns:yt='http://gdata.youtube.com/schemas/2007'
      xmlns:gd='http://schemas.google.com/g/2005'
      gd:fields='yt:accessControl[@action="comment"]'>
    <yt:accessControl action='comment' permission='moderated'/>
    <yt:accessControl action='comment' permission='allowed'
      type='group'>friends</yt:accessControl>
  </entry>

Alternate notation for applications that do not handle PATCH method

If your application cannot properly handle the PATCH method, send an HTTP POST request, then you can send an HTTP POST request and set the X-HTTP-Method-Override HTTP header to PATCH. For example, Flash applications must send an HTTP POST request to be able to set an Authorization header. (See the Authenticating Requests from Flash Applications section for more details.) Since all PATCH requests require authentication, to submit a PATCH request from a Flash application you would send an authenticated POST request and set the X-HTTP-Method-Override HTTP header to PATCH as shown below. This alternate notation does not affect the formatting of the request body or other HTTP request headers.

POST /feeds/api/videos/ HTTP/1.1
X-HTTP-Method-Override: PATCH
Host: gdata.youtube.com
Content-Type: application/xml
...

Handling the response to a partial feed update

When you submit a partial feed update request, the API will return a 200 HTTP response code. The body of the response will be the complete entry that you updated unless your PATCH request specified a value for the fields parameter. If it did specify a fields parameter value, then the API response will only contain the fields that you specified. See the Formatting the fields parameter value for instructions on how to specify the data fields that you want to be included in an API response.

If the body of your partial update request contained invalid XML, or if you specified an invalid value for the fields, the API will return a 400 (Bad Request) response code.

Error handling for partial update (PATCH) requests

The list below explains specific types of errors that may cause a YouTube API PATCH request to fail. In general, please see the Understanding API error responses section for more information about specific error messages that the API returns. Also see the reference guide for more information about the HTTP response codes that the API returns.

• If a resource specifies a deprecated value for a specific element, the PATCH request will fail unless it updates that value. In this case, the API returns a yt:validation error with the <code> value of deprecated. For YouTube API requests, this error is most likely to occur if you try to do a partial update of a video that is associated with a deprecated category. This type of error can be confusing because the API response identifies the element containing the deprecated value as the location of the error in your PATCH request even if the request did not actually include that element.

  For example, the YouTube category document indicates that the “Short Movies” video category has been deprecated. As such, if you attempt to update the title of a video in that category, the update will fail unless you also update the video’s category. In addition, the API response will identify the <media:category> tag as the location of the error in your API request even though your request may not have included that element.

  The sample response below shows the format of this error:

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

  See the Category list for uploaded videos section of the reference guide for more information about assignable video categories.

• If the gd:fields attribute value and the contents of the <entry> element provide conflicting instructions as to which fields should be updated, the API server will return a 422 (Unprocessable Entity) HTTP response code. For example, in the following request, the gd:fields attribute specifies that only the <media:title> element should be replaced. However, the XML request also contains a <media:keywords> element, and the API server cannot determine whether to update (i) the <media:title> element; (ii) the <media:title> and <media:keywords> elements; or (iii) all of the child elements of <media:group>.

  <entry xmlns='http://www.w3.org/2005/Atom'
      xmlns:media='http://search.yahoo.com/mrss/'
      xmlns:gd='http://schemas.google.com/g/2005'
      gd:fields='media:group/media:title'>
    <media:group>
      <media:title type='plain'>New video title</media:title>
      <media:keywords>new,keywords,here</media:keywords>
    </media:group>
  </entry>

• If you try to update the access controls for a video, the API will return a too_many validation error unless you use the gd:fields attribute to identify the controls that you are updating. This error occurs because the <yt:accessControl> tag is a repeating element. As such, if you include the tag in a PATCH request, the API will add any access controls that you specify to the existing set of controls for a video. However, a video cannot specify more than one access control for a specific action (“embed”, “rate”, etc.).

  The API response below shows an error resulting from an attempt to update the access control setting that determines whether a video can be embedded on other websites. This error would occur if the original PATCH request did not use the <entry> tag’s gd:fields attribute to identify the embed setting as the one being replaced.

  <?xml version='1.0' encoding='UTF-8'?>
  <errors>
    <error>
      <domain>yt:validation</domain>
      <code>too_many</code>
      <location type='xpath'>yt:accessControl[@action='embed']</location>
    </error>
  </errors>

  There are two ways to indicate that you want to update an access control setting for a video:

  • To update an individual setting or a specific group of settings, use the gd:fields value to explicitly identify the settings that you want to replace. For example, the following request updates the access control settings for comments and ratings:

    <?xml version="1.0" encoding="UTF-8"?>
    <entry xmlns="http://www.w3.org/2005/Atom"
              xmlns:yt="http://gdata.youtube.com/schemas/2007"
              xmlns:gd="http://schemas.google.com/g/2005"
              gd:fields="yt:accessControl[@action='comment' or @action='rate']">
      <yt:accessControl action="comment" permission="moderated"/>
      <yt:accessControl action="rate" permission="allowed"/>
    </entry>

  • To update all access controls, you would set the gd:fields value to yt:accessControl. Any access controls that are defined in the XML request will be applied to the video, and all other access controls will return to their default settings. For example, the following request sets the access control setting for comments to moderated and reverts all other access controls to their default settings:

    <?xml version="1.0" encoding="UTF-8"?>
    <entry xmlns="http://www.w3.org/2005/Atom"
              xmlns:yt="http://gdata.youtube.com/schemas/2007"
              xmlns:gd="http://schemas.google.com/g/2005"
              gd:fields="yt:accessControl">
      <yt:accessControl action="comment" permission="moderated"/>
    </entry>

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. In addition, the default API version used on the staging server is version 2. As such, you do not need to use the v parameter or the GData-Version HTTP request header to use version 2 of the API on the staging server. However, you do still need to use the v parameter or the GData-Version HTTP request header to use version 2 of the API on the production API servers. 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 “” 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.

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:

• Demographics (filename: VIDEOID_demographics_1.csv) – This report provides a demographic breakdown of the viewers who have watched a video. The report contains the following fields:
  • VideoID – The YouTube video ID that uniquely identifies the video.
  • Title – The title of the video.
  • Gender – The gender of the demographic group.
  • Age group – The age group of the demographic group. Reported age groups are 13-17, 18-24, 25-34, 35-44, 45-54, 55-64, and 65-.
  • Percentage – The percentage of the video’s viewers who are in the specified gender and age group.
• 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 or a “dislike” rating.
  • 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 or a “like” rating.

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>