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.

Experimental features ()

Some of the API features described in this documentation are experimental features, which means that they are still in development and are subject to change or even be removed without notice.

In the documentation, these features are identified by a blue flask icon (). Experimental features may be released to enable developers to explore new ideas and to enable the API team to innovate rapidly. Our deprecation policy does not apply to experimental features.

Supported API feeds

The lists below identify the different types of feeds and feed entries that you can retrieve (GET) using the YouTube Data API. The API also supports methods to add (POST), update (PUT), or delete (DELETE) entries from many of these feeds.

• Video feeds contain a list of videos.

  • Video search feeds list videos that match parameter values, such as a query term or video duration.
  • Standard video feeds list videos that either reflect YouTube user behavior or that were selected by YouTube staff. Examples include top-rated, most viewed, and recently featured videos. Movie and trailer charts are standard feeds that only contain videos that appear in YouTube's Movies or Trailers category, respectively.
  • A user uploads feed identifies videos uploaded by a specified user.
  • A favorite videos identifies videos that a specified user has flagged as a favorite.
  • A playlist feed lists the videos in a specified playlist.
  • A watch later feed lists videos that a specified user has flagged to watch at a later time.
  • A watch history feed lists videos that the user has watched on the YouTube website.
  • A video recommendations feed contains videos that may appeal to a specified user.
  • A related videos feed identifies videos related to a specified video.
  • A video responses feed identifies videos that have been explicitly designated as responses to a specified video.
  • A new subscription videos feed identifies videos that were recently uploaded by users that a specified user subscribes to.

• Channel feeds contain a list of channels.

  • Channel search feeds list channels that match a specified search term.
  • Standard channel feeds list channels that reflect YouTube user preferences, such as most viewed and most subscribed channels.

• Playlists feeds contain a list of playlists. Note that a playlists feed is different than a playlist feed, which is a type of video feed.

  • Playlist search feeds list playlists that match a specified search term.
  • A user playlists feed identifies playlists created by a specified user.

• Event feeds contain a list of events.

  • Live event charts contain standard feeds of events, such as featured events, upcoming events, or currently live events.
  • A user events feed lists a specific user's live events.

• Comment feeds list comments that users have submitted about a specified video.

• Subscription and activity feeds

  • A user subscription feed lists channels or users that a specified user has subscribed to.
  • User activity feeds list different actions performed by one or more specified users. Actions include rating a video, marking a video as a favorite, uploading a video, and more.

• Inbox and contact feeds

  • A user inbox feed lists messages in the logged-in user's inbox.
  • A user contacts feed lists a specified user's contacts.

• A user profile entry contains information about a specified user. Any personal information that appears in a user profile feed will have been entered by that user for publication on YouTube.

In addition, the API supports methods for adding ratings and complaints, though neither of those can be retrieved via the API.

API versioning

An API request 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.

YouTube actively supports API versions 2 and 2.1, and you must use either the v parameter or the GData-Version request header to specify one of these two versions. The list below briefly explains the two API versions:

• API version 2 allows access to all currently supported API features to users who have YouTube accounts. A YouTube account provisions a YouTube channel name, enabling the user to upload videos. Users with YouTube accounts can access many other YouTube features that require user authentication, such as the ability to create playlists, create subscriptions, rate videos, add comments, and more.

• API version 2.1 enables users who have a Google Account but who do not have a YouTube channel to also access many features that are dependent on user authentication. While a user still needs a YouTube channel to upload videos, she does not need a YouTube channel to rate videos, add videos to a 'Watch Later' playlist, or access several other site features.

  On YouTube.com, and in API version 2.1, the latter group of features is available to users who have a Google Account (but not a YouTube channel). In this documentation, such accounts are referred to as unlinked Google Accounts. For example, a user who has a Gmail account or an Android device is certain to have a Google Account but may not have already linked that Google Account to a YouTube channel.

  By specifying API version 2.1 in your application, you are indicating that your application has been upgraded to properly handle requests from users with unlinked Google Accounts. The Comparing API versions 2 and 2.1 section provides a detailed list of the features that are supported in API version 2.1 for users with unlinked Google Accounts. It also explains how API responses in version 2.1 are different from the same responses in version 2 for users with unlinked Google Accounts.

Note: Unless otherwise noted, all of the sample requests in this documentation use the GData-Version request header and demonstrate how to use version 2 of the API. 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 the now-deprecated version 1.

If a request does not specify an API version, then YouTube will use API version 1 to handle that request. (Note, however, that requests to the API staging server use API version 2 by default.)

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.

Comparing API versions 2 and 2.1

As discussed in the previous section, YouTube supports API versions 2 and 2.1. The following list shows the differences between the two versions.

• The versions return different HTTP response codes and error messages for requests that require authentication and are made on behalf of users with unlinked Google Accounts.

  • API version 2 returns an HTTP 401 response code and the message NoLinkedYouTubeAccount if a user with an unlinked Google Account attempts any operation that requires authentication.

  • API version 2.1 returns an HTTP 200 response code for a subset of the requests that cause a 401 NoLinkedYouTubeAccount response in API version 2.

    This version also returns an HTTP 403 Forbidden response with a youtube_signup_required error for the remaining unsupported requests. The following XML shows a sample response with this error:

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

    If you want to modify your application to support users with unlinked Google Accounts, we recommend that you focus on gracefully handling this error. Since the list of features supported for unlinked Google Accounts is likely to grow, hardcoding your application to only display certain features to users with those accounts would likely prevent users from accessing supported features until you could update your application.

    If an API response specifies the youtube_signup_required error, your application should indicate that the requested operation requires the user to have a YouTube channel and should display an option to link to https://www.youtube.com/create_channel. If you are building a mobile application, you can bypass a redirect by presenting a link to https://m.youtube.com/create_channel instead.

• API version 2.1 lets users with unlinked Google Accounts access some, but not all, API features that require user authentication. In API version 2, those features are only available to users with YouTube accounts.

  Specifically, API version 2.1 supports the features listed below for users with authenticated Google Accounts and should return an HTTP 200 response code for API requests related to these features:

  • Rating a video
  • Flagging a video for inappropriate content (adding a complaint)
  • Subscribing to a channel or user activity feed
  • Adding videos to a "watch_later" playlist

  As such, users with unlinked Google Accounts must add a YouTube channel to be able to use the following API features. (The API will return a 403 Forbidden response, as described above, for requests related to these features.)

  • Uploading videos (or video responses)
  • Adding comments
  • Identifying favorite videos
  • Creating playlists (other than the watch_later playlist)
  • Retrieving personalized video recommendations
  • Adding or retrieving contacts
  • Sending messages to other YouTube users
  • Retrieving their own activity feed

• In version 2.1, a YouTube user profile entry for a user with an unlinked Google Account will contain a <yt:incomplete> tag. This tag is useful if you prefer to modify your application so that it does not display unsupported features (or provides a different display for those features) to users with unlinked Google Accounts.

  In addition, in version 2.1, a profile entry for a user with an unlinked Google Account only contains a few of the tags that can be included in a profile entry for a user with a YouTube account. The <entry> tag definition lists the tags that may appear within a profile entry for both YouTube accounts and unlinked Google Accounts.

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 the following authentication schemes – OAuth 2.0, OAuth, AuthSub, or ClientLogin – that are available to enable users to access account-specific YouTube features. The following list will help you to select the authentication scheme that is appropriate for your application.

• The OAuth protocol provides a standard way to access protected data on different websites and it is the recommended authentication mechanism for Google APIs. OAuth is an open protocol that may be implemented for many APIs, including Google APIs. 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. All Google APIs support OAuth 2.0 and OAuth 1.0, and OAuth 2.0 is generally regarded as the easier of the two to implement. See http://oauth.net to learn more about Oauth.

• AuthSub is Google's proprietary authorization API for web applications. It lets you authenticate users to their YouTube accounts without having to access the user's YouTube username and password. If you are building a new application, we recommend that you use the OAuth 2.0 or OAuth 1.0 authorization protocol instead.

• ClientLogin is Google's proprietary authorization API for installed applications. It lets you associate all API actions with a single YouTube account. If you are building a new application, we recommend that you use the OAuth 2.0 authorization protocol instead.

  As background, ClientLogin was designed for standalone, single-user, installed clients, such as desktop applications. An application would ask the user to enter his YouTube username and password and would 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.

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.

  https://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.

OAuth 2.0

The YouTube Data API supports the OAuth 2.0 protocol for authorizing access to private user data. The list below explains some core OAuth 2.0 concepts:

• When a user first attempts to use functionality in your application that requires the user to be logged in to a Google Account or YouTube account, your application initiates the OAuth2 authentication process.

• Your application directs the user to Google's authorization server. The link to that page specifies the scope of access that your application is requesting for the user's account. The scope specifies the resources that your application can retrieve, insert, update, or delete when acting as the authenticated user.

• If the user consents to authorize your application to access those resources, Google will return a token to your application. Depending on your application's type, it will either validate the token or exchange it for a different type of token.

  For example, a server-side web application would exchange the returned token for an access token and a refresh token. The access token would let the application authenticate requests on the user's behalf, and the refresh token would let the application retrieve a new access token when the original access token expires.

This section of the API documentation covers the following topics:

• The Register your application with Google section walks you through the registration process, which is a prerequisite to using OAuth 2.0 authentication.

• The OAuth 2.0 flows section explains different flows for obtaining OAuth 2.0 access tokens for either server-side web applications, client-side web applications, installed applications, or devices.

• The Calling the YouTube Data API section explains how to use the OAuth 2.0 tokens that your application obtains to make authenticated API requests on a user's behalf.

• The Client libraries section describes client library support for OAuth 2.0.

Register your application with Google

You need to register your application with Google to be able to use OAuth 2.0 authentication. The following steps explain how to register your application and create an OAuth 2.0 client ID to use in that application.

1. Create a project in the Google APIs console.

   • If you have not created a project before, the console page will display a big Create project button.

     

   • If you have created a project before, you can create a new project via the console menu shown below.

     

2. Click the API Access tab in the navigation menu.

   

3. Click the Create an OAuth 2.0 client ID button.

   

4. Enter a product name for your application and, if you wish, a URL for your product logo. By default, we will use your email address as the support email for your application. You can change the email address by signing in to the API console with a different account that has an email address that you have verified.

   

   Click the Next button to proceed.

5. Indicate whether your application is a web application or an installed application. If it is a web application, you will need to also provide a domain or hostname.

   

   After you direct a user to Google's authorization server, and the user logs in and decides whether to grant access to your application, Google will redirect the user to a redirect_uri that you specified.

   For web applications, you need to register the redirect_uri that your application uses with Google before you will be able to complete the steps needed to obtain OAuth 2.0 access tokens. You can register more than one redirect_uri.

   The console will define a default redirect URI and a default, authorized JavaScript source. You can register additional redirect_uri values and add or change authorized JavaScript sources by clicking the more options link in the Client ID Settings window.

6. Click the Create client ID button.

OAuth 2.0 flows

Google supports several OAuth 2.0 use cases:

• The server-side flow supports web applications that can securely store persistent information.
• The client-side flow supports JavaScript applications running in a browser.
• The installed application flow supports applications installed on a device, such as a phone or computer.
• The device flow supports devices with limited input capabilities, such as game consoles and video cameras.

Server-side web applications

This flow is designed for web applications with servers that can store information and maintain state. While this section walks through the steps your code would go through to use OAuth 2.0 in a server-side web application, you could also use one of several client libraries in your OAuth 2.0 implementation.

The following steps explain the server-side flow:

1. Getting an access token

   When a user first tries to perform an action that requires API authentication, direct the user to Google's authorization server at https://accounts.google.com/o/oauth2/auth. The authorization server will refuse HTTP connections because it is only accessible over SSL (HTTPS). It supports the following URL parameters:

   Parameter	Description
   client_id	Required. The OAuth 2.0 client ID for your application.
   redirect_uri	Required. A registered redirect_uri for that client ID.
   response_type	Required. Set this parameter's value to code.
   scope	Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf.
   approval_prompt	This parameter indicates whether the user should be prompted to grant account access to your application each time he tries to complete a particular action. The default value is auto, which indicates that a user would only need to grant access the first time he tried to access a protected resource. Set the parameter value to force to direct the user to a consent page even if he has already granted access to your application for a particular set of scopes.
   access_type	Recommended. Set this parameter value to offline. At the moment, this is the only supported parameter value (and also the default value). It indicates that your application can refresh access tokens using the method described later in this document. In the future, Google's authorization server will support an additional value, online, that will provide an alternate, JavaScript-based method of refreshing an access token as long as the user is actively using the browser. We recommend that you explicitly set the access_type parameter to offline because we anticipate that when the online value is introduced, it will be as the default behavior. This could cause unexpected changes in your application since it would affect the way that your application is allowed to refresh access tokens. By explicitly setting the parameter value to offline, you can avoid any changes in your application's functionality. Note: OAuth 2.0 is still marked as an experimental feature to indicate that such unexpected changes might occur.
   state	Any string that your application would use to maintain state between the request and redirect response. Your application will receive the same value that it sends for this parameter. For example, you could use this parameter to redirect the user to a particular resource in your application.

   The sample URL below shows a redirect to Google's authorization server for an application requesting permission to submit YouTube Data API requests on the user's behalf:

   https://accounts.google.com/o/oauth2/auth?
     client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
     redirect_uri=http://localhost/oauth2callback&
     scope=https://gdata.youtube.com&
     response_type=code&
     access_type=offline
   

2. Google's authorization server will display the name of your application and the Google services that it is requesting permission to access on the user's behalf. The user can then consent or refuse to grant access to your application.

   You can test this flow by clicking on the sample URL in step 1. If you also place a file on your server at http://localhost/oauth2callback, you will also be able to see how the user's response appears in the redirect URI. (See step 3 for more details.)

3. After the user consents or refuses to grant access to your application, Google will redirect the user to the redirect_uri that you specified in step 1.

   • If the user granted access to your application, Google will have appended a code parameter to the redirect_uri. This value is a temporary authorization code that you can exchange for an access token as discussed in step 4.

     http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf

   • If the user refused to grant access to your application, Google will have included the access_denied error message in the hash fragment of the redirect_uri:

     http://localhost/oauth2callback#error=access_denied

4. Assuming the user has granted access to your application, exchange the authorization code obtained in step 3 for a refresh token and access token. To do so, send a POST request to https://accounts.google.com/o/oauth2/token that includes the following key-value pairs in the request body:

   Key	Value
   code	The authorization code that Google returned to your redirect_uri in step 3.
   client_id	The OAuth 2.0 client ID for your application.
   client_secret	The client secret associated with your client ID. This value is displayed in the Google APIs console.
   redirect_uri	A registered redirect_uri for your client ID.
   grant_type	Set this value to authorization_code.

   A sample request is displayed below:

   POST /o/oauth2/token HTTP/1.1
   Host: accounts.google.com
   Content-Type: application/x-www-form-urlencoded
   
   code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf&
   client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
   client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
   redirect_uri=http://localhost/oauth2callback&
   grant_type=authorization_code
   

5. Google will respond to your POST request by returning a JSON object that contains a short-lived access token and a refresh token.

   {
     "access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc",
     "token_type" : "Bearer",
     "expires_in" : 3600,
     "refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74"
   }
   

   Your application should store both values.

   • The Calling the YouTube Data API section explains how to submit an authorized request using the access token.

   • The Refreshing an access token section explains how to use the refresh token to obtain a new access token if the one that you have expires.

Client-side web applications

This flow is designed for JavaScript-based web applications that cannot maintain state over time.

The following steps explain the client-side flow:

1. Getting an access token

   When a user first tries to perform an action that requires API authentication, direct the user to Google's authorization server at https://accounts.google.com/o/oauth2/auth. The authorization server will refuse HTTP connections because it is only accessible over SSL (HTTPs). It supports the following URL parameters:

   Parameter	Description
   client_id	Required. The OAuth 2.0 client ID for your application.
   redirect_uri	Required. A registered redirect_uri for that client ID.
   response_type	Required. Set this parameter's value to token.
   scope	Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf.
   approval_prompt	This parameter indicates whether the user should be prompted to grant account access to your application each time he tries to complete a particular action. The default value is auto, which indicates that a user would only need to grant access the first time he tried to access a protected resource. Set the parameter value to force to direct the user to a consent page even if he has already granted access to your application for a particular set of scopes.
   state	(optional) A string used to maintain state between the request and redirect. This value will be appended to your redirect_uri after the user consents to or denies your application's access request.

   The sample URL below shows a redirect to Google's authorization server for an application requesting permission to submit YouTube Data API requests on the user's behalf:

   https://accounts.google.com/o/oauth2/auth?
     client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
     redirect_uri=http://localhost/oauth2callback&
     scope=https://gdata.youtube.com&
     response_type=token
   

2. Google's authorization server will display the name of your application and the Google services that it is requesting permission to access on the user's behalf. The user can then consent or refuse to grant access to your application.

   You can test this flow by clicking on the sample URL in step 1. If you also place a file on your server at http://localhost/oauth2callback, you will also be able to see how the user's response appears in the redirect URI. (See step 3 for more details.)

3. After the user consents or refuses to grant access to your application, Google will redirect the user to the redirect_uri that you specified in step 1.

   • If the user granted access to your application, Google will have appended a short-lived access token in the hash fragment of the redirect URI. The response will also include the expires_in and token_type parameters. These parameters describe the lifetime of the token in seconds and the kind of token that is being returned, respectively. Finally, hte response will include the state parameter if a state parameter was included in the original request to the authorization server.

     http://localhost/oauth2callback#access_token=1/QbIbRMWW&token_type=Bearer&expires_in=3600

     Note: Your application should also allow other fields to be returned in the response. The list provided above identifies the minimum set of fields that will be appended to the redirect_uri.

     JavaScript code running on your page can capture the access token from the window.location.hash value and either store the token in a cookie or POST it to a server.

   • If the user refused to grant access to your application, Google will have included the access_denied error message in the hash fragment of the redirect_uri:

     http://localhost/oauth2callback#error=access_denied

4. Assuming the user has granted access to your application, you need to explicitly validate the token returned in the redirect_uri. You validate the token by specifying the token as the value of the access_token parameter in a web service request to https://www.googleapis.com/oauth2/v1/tokeninfo. That URL accepts an access token and returns information about that token, including the application that the token was issued to, the user associated with the token, the scopes that the user granted access to, and the remaining life of the token.

   The sample URL below demonstrates where you would send a token validation request:

   https://www.googleapis.com/oauth2/v1/tokeninfo?access_token=1/fFBGRNJru1FQd44AzqT3Zg

5. In response to a token validation request, the Google authorization server will return either a JSON object that describes the token or an error message.

   • If the token is still valid, the JSON object will include the following values:

     Field	Description
     audience	The application that is the intended user of the access token. Important: Before using the token, you need to verify that this field's value exactly matches your client_id in the Google APIs console. This verification ensures that your application will not be vulnerable to the confused deputy problem.
     expires_in	The number of seconds left before the token will become invalid.
     scope	A space-delimited list of scopes that the user granted access to. The list should match the scopes you specified in your authorization request in step 1.
     userid	This value lets you correlate profile information from multiple Google APIs. It is only present in the response if you included the https://www.googleapis.com/auth/userinfo.profile scope in your request in step 1. The field value is an immutable identifier for the logged-in user that can be used to create and manage user sessions in your application.

     A sample response is shown below:

     {
       "audience":"8819981768.apps.googleusercontent.com",
       "user_id":"123456789",
       "scope":"https://gdata.youtube.com",
       "expires_in":436
     }
     

   • If the token has expired, been tampered with, or had its permissions revoked, Google's authorization server will return an error message in the JSON object. The error surfaces as a 400 error, and a JSON body in the format shown below:

     {"error":"invalid_token"}

     By design, no additional information is given as to the reason for the failure.

Installed applications

This flow is designed for applications that are installed on a device, such as a mobile phone or computer. These applications could access the YouTube Data API while the user is interacting with the application or when the application is running in the background for an extended period of time without direct user interaction.

This flow assumes that the application cannot securely store tokens that would enable a user to interact with YouTube Data API. It also requires that the application has access to the system browser or has the ability to embed a browser control. If the application does not meet either of these conditions, please refer to the OAuth 2.0 instructions for devices instead.

The following steps explain this flow:

1. When registering your application, make sure that you specify that it is an installed application. This results in a different default value for the redirect_uri parameter.

2. Getting an access token

   When a user first tries to perform an action that requires API authentication, direct the user to Google's authorization server at https://accounts.google.com/o/oauth2/auth. The authorization server will refuse HTTP connections because it is only accessible over SSL (HTTPs). It supports the following URL parameters:

   Parameter	Description
   client_id	Required. The OAuth 2.0 client ID for your application.
   redirect_uri	Required. A registered redirect_uri for that client ID. For installed applications, you can choose between an http://localhost:port or urn:ietf:wg:oauth:2.0:oob as described below: http://localhost:port – This value indicates that Google's authorization server should return the authorization code as a query string parameter to the client device's web server. You may specify a port number without changing the configuration in the Google APIs console. To receive the authorization code on this URL, your application must be listening on the local web server. If your platform supports it, this is the recommended mechanism for obtaining the authorization code. However, note that not all platforms support this approach and that even if a platform does support it, other software (e.g. Windows firewall) may prevent delivery of the message. urn:ietf:wg:oauth:2.0:oob – This value indicates that Google's authorization server should return the authorization code in the browser's title bar. This option is useful if the client cannot listen on an HTTP port without significant modifications to the client. Windows applications possess this characteristic. If your application uses this value, it will need to determine when the browser has loaded a response from the authorization server. It will then need to extract the authorization code from the title of the page served in the browser. Your application should also close the browser window if you want to prevent the user from seeing the page with the authorization code. The mechanism for closing that window varies from platform to platform.
   response_type	Required. Set this parameter's value to code.
   scope	Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf.
   access_type	Recommended. Set this parameter value to offline. At the moment, this is the only supported parameter value (and also the default value). It indicates that your application can refresh access tokens using the method described later in this document. In the future, Google's authorization server will support an additional value, online, that will provide an alternate, JavaScript-based method of refreshing an access token as long as the user is actively using the browser. We recommend that you explicitly set the access_type parameter to offline because we anticipate that when the online value is introduced, it will be as the default behavior. This could cause unexpected changes in your application since it would affect the way that your application is allowed to refresh access tokens. By explicitly setting the parameter value to offline, you can avoid any changes in your application's functionality. Note: OAuth 2.0 is still marked as an experimental feature to indicate that such unexpected changes might occur.
   state	Any string that your application would use to maintain state between the request and redirect response. Your application will receive the same value that it sends for this parameter. For example, you could use this parameter to redirect the user to a particular resource in your application.

   The sample URL below shows a redirect to Google's authorization server for an application requesting permission to submit YouTube Data API requests on the user's behalf:

   https://accounts.google.com/o/oauth2/auth?
     client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
     redirect_uri=http://localhost/oauth2callback&
     scope=https://gdata.youtube.com&
     response_type=code&
     access_type=offline
   

3. Google's authorization server will display the name of your application and the Google services that it is requesting permission to access on the user's behalf. The user can then consent or refuse to grant access to your application.

   You can test this flow by clicking on the sample URL in step 1. If you also place a file on your server at http://localhost/oauth2callback, you will also be able to see how the user's response appears in the redirect URI. (See step 4 for more details.)

4. After the user consents or refuses to grant access to your application, Google will either redirect the user to the redirect_uri that you specified in step 2 or return a page to the user's browser.

   • If you set the redirect_uri to http://localhost (or some path on the local web server), then one of the following two scenarios will apply:

     • If the user granted access to your application, Google will have appended a code parameter to the redirect_uri. This value is a temporary authorization code that you can exchange for an access token as discussed in step 5.

       http://localhost/oauth2callback?code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf

     • If the user refused to grant access to your application, Google will have included the access_denied error message in the hash fragment of the redirect_uri:

       http://localhost/oauth2callback#error=access_denied

   • If you set the redirect_uri to urn:ietf:wg:oauth:2.0:oob, Google's authorization server will return a page to the browser like the one shown below. Your application can then extract the authorization code from the page title.

     

5. Assuming the user has granted access to your application, exchange the authorization code obtained in step 3 for a refresh token and access token. To do so, send a POST request to https://accounts.google.com/o/oauth2/token that includes the following key-value pairs in the request body:

   Key	Value
   code	The authorization code that Google returned to your redirect_uri in step 3.
   client_id	The OAuth 2.0 client ID for your application.
   client_secret	The client secret associated with your client ID. This value is displayed in the Google APIs console.
   redirect_uri	A registered redirect_uri for your client ID.
   grant_type	Set this value to authorization_code.

   A sample request is displayed below:

   POST /o/oauth2/token HTTP/1.1
   Host: accounts.google.com
   Content-Type: application/x-www-form-urlencoded
   
   code=4/ux5gNj-_mIu4DOD_gNZdjX9EtOFf&
   client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
   client_secret=hDBmMRhz7eJRsM9Z2q1oFBSe&
   redirect_uri=http://localhost/oauth2callback&
   grant_type=authorization_code
   

6. Google will respond to your POST request by returning a JSON object that contains a short-lived access token and a refresh token.

   {
     "access_token" : "ya29.AHES6ZTtm7SuokEB-RGtbBty9IIlNiP9-eNMMQKtXdMP3sfjL1Fc",
     "token_type" : "Bearer",
     "expires_in" : 3600,
     "refresh_token" : "1/HKSmLFXzqP0leUihZp2xUt3-5wkU7Gmu2Os_eBnzw74"
   }
   

   Your application should store both values.

   • The Calling the YouTube Data API section explains how to submit an authorized request using the access token.

   • The Refreshing an access token section explains how to use the refresh token to obtain a new access token if the one that you have expires.

Devices

This flow is designed for applications that run on devices with limited input capabilities, such as game consoles or video cameras. In this flow, the user interacts with an application on the device to obtain a URL and a device code. The user then switches to another device, such as a computer or smartphone, that has richer input capabilities to authorize the device code.

The following steps explain this flow:

1. You need to register your application with Google and embed the client_id and client_secret created during the registration process into your application.

2. Your device sends a POST request to Google's authorization server at https://accounts.google.com/o/oauth2/device/code. The request specifies the following parameters:

   Parameter	Description
   client_id	Required. The OAuth 2.0 client ID for your application.
   scope	Required. A space-delimited list of scopes that identify the resources that your application could access on the user's behalf.

   The following sample request shows how to retrieve a device code:

   POST /o/oauth2/device/code HTTP/1.1
   Host: accounts.google.com
   Content-Type: application/x-www-form-urlencoded
   
   client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
   scope=https://gdata.youtube.com
   

3. Google will respond to your request by returning a JSON object to your device. A sample response is shown below:

   {
     "device_code" : "4/L9fTtLrhY96442SEuf1Rl3KLFg3y",
     "user_code" : "a9xfwk9c",
     "verification_url" : "http://www.google.com/device",
     "expires_in" : "1800"
     "interval" : 5,
   }
   

   The application on your device should display the user_code and verification_url to the user. It should store the device_code, expires_in, and interval values for use in step 4.

4. Your application can begin polling Google's authorization server using the device_code returned in the JSON response in step 3. To do so, your application sends a POST request to https://accounts.google.com/o/oauth2/token that specifies the following key-value pairs:

   Key	Value
   client_id	The OAuth 2.0 client ID for your application.
   client_secret	The client secret associated with your client ID. This value is displayed in the Google APIs console.
   code	The device code obtained in step 3.
   grant_type	Set this value to http://oauth.net/grant_type/device/1.0.

   A sample polling request is shown below. The interval returned in the JSON response in step 3 specifies the minimum amount of time, in seconds, that your application should wait between polling requests.

   POST /o/oauth2/token HTTP/1.1
   Host: accounts.google.com
   Content-Type: application/x-www-form-urlencoded
   
   client_id=1084945748469-eg34imk572gdhu83gj5p0an9fut6urp5.apps.googleusercontent.com&
   client_secret=hDBmMRhz7eJRsM9Z2q1oFBSem&
   code=4/YMSlR3fSCC1NtUh073DuZKTJJ3ss&
   grant_type=http://oauth.net/grant_type/device/1.0
   

   Until the user completes steps 5 through 7, your application will receive one of the following responses to each polling request:

   • The following response indicates that the user has not yet completed the steps to grant API access to the device:

     {
       "error" : "authorization_pending"
     }
     

   • The following response indicates that your application is sending polling requests too frequently:

     {
       "error" : "slow_down"
     }
     

5. The user launches a browser on another device, such as a computer or mobile phone, and navigates to the verification_url. That URL will display a page where the user can enter the user_code obtained in the previous step.

   

   Note: The user_code is case-sensitive, so the user will need to enter it exactly as it appears in the response.

6. After entering the user_code, the user will be asked to log in to the Google Account that will be used to authenticate YouTube Data API requests from your device. (If the user is already logged in, she will proceed directly to the next step.)

7. After the user logs in, Google's authorization server will display a page that shows the name of your application and the Google services that it is requesting permission to access on the user's behalf. The user can then consent or refuse to grant access to your application.

8. If the user grants access to your application, the next polling request that your device sends will return a JSON object that contains an access token and a refresh token.

   {
     "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
     "expires_in":3920,
     "token_type":"Bearer",
     "refresh_token":"1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ"
   }
   

   Your application should store both values.

   • The Calling the YouTube Data API section explains how to submit an authorized request using the access token.

   • The Refreshing an access token section explains how to use the refresh token to obtain a new access token if the one that you have expires.

Calling the YouTube Data API

After obtaining an access token for a user, your application can use that token to submit authorized API requests on that user's behalf. The API supports two ways to specify an access token:

1. Specify the access token as the value of the access_token query parameter:

   https://gdata.youtube.com/feeds/api/users/default/uploads?access_token=ACCESS_TOKEN

   You can test this using cURL with the following command:

   curl gdata.youtube.com/feeds/api/users/default/uploads?access_token=YOUR_ACCESS_TOKEN
   

2. Specify the access token as the value of the Authorization: Bearer HTTP request header:

   POST /feeds/api/users/default/uploads HTTP/1.1
   Host: gdata.youtube.com
   Authorization: Bearer ACCESS_TOKEN
   ...
   

   You can test this using cURL with the following command:

   curl -H "Authorization: Bearer ACCESS_TOKEN" gdata.youtube.com/feeds/api/users/default/uploads
   

The API will return an HTTP 401 response code (Unauthorized) if you submit a request to access a protected resource with an expired access token. The following section explains how to refresh an access token.

Refreshing an access token

If your application obtains a refresh token during the authorization process, then you will need to periodically use that token to obtain a new, valid access token. Server-side web applications, installed applications, and devices all obtain refresh tokens.

At any time, your application can send a POST request to Google's authorization server that specifies your client ID, your client secret, and the refresh token for the user. The request should also set the grant_type parameter value to refresh_token. The following example demonstrates this request:

POST /o/oauth2/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=21302922996.apps.googleusercontent.com&
client_secret=XTHhXh1SlUNgvyWGwDk1EjXB&
refresh_token=1/6BMfW9j53gdGImsixUH6kU5RsR4zwI9lUVX-tqf8JXQ&
grant_type=refresh_token

The authorization server will return a JSON object that contains a new access token:

{
  "access_token":"1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":3920,
  "token_type":"Bearer"
}

Client libraries

The Google Data client libraries that support the YouTube Data API do not currently support OAuth 2.0. However, a newer set of Google API client libraries, which do not support the YouTube Data API, do provide OAuth 2.0 support.

As such, it is an option to use these newer libraries, which are listed below, for their OAuth 2.0 capabilities and then force the Google Data client library to use the OAuth 2.0 token(s) that you have obtained.

• Google APIs Client Library for Java
• Google APIs Client Library for Python
• Google APIs Client Library for .NET
• Google APIs Client Library for Ruby
• Google APIs Client Library for PHP
• OAuth 2.0 Library for Google Web Toolkit
• Google Toolbox for Mac OAuth 2.0 Controllers

You can also follow the instructions in the Calling the YouTube Data API section to modify your code to properly set the OAuth 2.0 token values.

OAuth 1.0

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

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.

Parameter	Description
oauth_consumer_key	This value specifies the domain associated with your application and must be the same as the domain that you registered with Google.
oauth_signature_method	This value specifies the signature algorithm used to sign the request. Supported values for this parameter are RSA-SHA1 and HMAC-SHA1.
oauth_signature	This value specifies the string (signature) generated using the referenced signature method. See the Signing requests that use OAuth authentication section for more information.
oauth_timestamp	This value specifies the time that the request was sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
oauth_nonce	This value is a random, 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks.
oauth_version	This value specifies the OAuth version that Google should use to handle your request. The default value is 1.0. If your request includes this parameter, the parameter's value must be 1.0.
scope	This value identifies the service that you are trying to access to make authenticated requests. This parameter is Google-specific and is not defined in the OAuth standards. Set the parameter value to http://gdata.youtube.com.

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 response code 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 response code (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:

Parameter	Description
oauth_token	This required parameter specifies the request token obtained from Google.
oauth_callback	This optional parameter specifies the URL to which the user will be redirected after granting your application access to the user's YouTube account. The URL can include query parameters. If you do not specify a callback URL, Google displays a page confirming that the user's token has been authorized. Note that providing a callback URL may create a more seamless user experience by automatically redirecting the user back to your application after the user completes the login process.

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

Parameter	Description
oauth_consumer_key	This value specifies the domain associated with your application and must be the same as the domain that you registered with Google. This value must be the same as the one provided in the request to obtain the request token.
oauth_token	This value specifies the authorized request token.
oauth_signature_method	This value specifies the signature algorithm used to sign the request. Supported values for this parameter are RSA-SHA1 and HMAC-SHA1.
oauth_signature	This value specifies the string (signature) generated using the referenced signature method.
oauth_timestamp	This value specifies the time that the request was sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
oauth_nonce	This value is a random, 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique to prevent replay attacks.
oauth_version	This value specifies the OAuth version that Google should use to handle your request. The default value is 1.0. If your request includes this parameter, the parameter's value must be 1.0.

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 response code 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 1.0 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 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).

AuthSub

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, send a 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>

ClientLogin

ClientLogin is not recommended for new development; please consider using AuthSub or OAuth instead. If you are already using ClientLogin and are encountering authentication failures with certain accounts, refer to the ClientLogin #FAIL blog post for recommendations.

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, send a 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 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 GET, POST, PUT, PATCH, or DELETE requests. However, Flash applications must send a POST request in order to set an Authorization header.

To send an authenticated GET, PUT, PATCH, or DELETE request from a Flash application, set the X-HTTP-Method-Override header in that request. If your application is sending 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='https://www.youtube.com/browse?s=tr'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/standardfeeds/top_rated?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/standardfeeds/top_rated/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/standardfeeds/top_rated?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/standardfeeds/top_rated?...'/>
  <link rel='next' type='application/atom+xml'
    href='https://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='https://www.youtube.com/watch?v=ZTUVgYoeN_b'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.responses'
      type='application/atom+xml'
      href='https://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='https://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='https://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='https://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#mobile'
      type='text/html' href='https://m.youtube.com/details?v=ZTUVgYoeN_b'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/standardfeeds/top_rated/v/ZTUVgYoeN_b?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</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='https://www.youtube.com/watch?v=ZTUVgYoeN_b'/>
      <media:credit role='uploader' scheme='urn:youtube'>GoogleDevelopers</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='90' width='120' time='00:00:03.500'/>
      <media:thumbnail url='http://img.youtube.com/vi/ZTUVgYoeN_b/1.jpg'
        height='90' width='120' time='00:00:01.750'/>
      <media:thumbnail url='http://img.youtube.com/vi/ZTUVgYoeN_b/3.jpg'
        height='90' width='120' time='00:00:05.250'/>
      <media:thumbnail url='http://img.youtube.com/vi/ZTUVgYoeN_b/0.jpg'
        height='360' width='480' 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='https://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 send a GET 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 send a 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 a GET request to a URL to retrieve comments for that video and a 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='https://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/responses'/>
  <link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/ratings'/>
  <link rel='http://gdata.youtube.com/schemas/2007#video.complaints'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/complaints'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/dmH0bHeiRN/uploads'/>
  <link rel='edit' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/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 a 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 a 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 periodically, with the update frequency varying from feed to feed. Many feeds are updated every 30 to 40 minutes but other feeds – such as those that capture daily, weekly or monthly results – may only be updated hourly or even daily.

To retrieve a standard feed, send a 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 a GET request to the following URL:

https://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 a GET request to the following URL:

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

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:

https://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 a GET request to the following URL:

https://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:
  https://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 a GET request to the following URL. Note: For this request, you must provide an authentication token, which enables YouTube to identify the user.

  https://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 a 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 a 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 a GET request to the following URL. Note that this request does not require authentication.

  https://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>GoogleDevelopers</name>
    <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</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="https://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.

Watch history feed

A user's watch history feed lists videos that the user has watched on the YouTube website. If the user had a YouTube login cookie and watched embedded videos on other websites, those videos will be listed in the feed as well. (It does not include videos that were viewed on mobile devices.) The feed's entries are ordered by the time that the user watched the video, beginning with the most recently watched video. If a user watched a video multiple times, the feed will contain a separate entry for each occurrence.

To retrieve a user's watch history feed, send an authenticated GET request to the following URL:

https://gdata.youtube.com/feeds/api/users/default/watch_history?v=2

Note: A user can only retrieve her own watch history feed, so an API request to retrieve a user's watch history feed must be authenticated by the user whose watch history feed is being requested. In addition, the watch history feed is only supported in API version 2 (and above).

A watch history feed entry differs from a standard video feed entry in the following ways:

• A watch history feed entry tag contains a <category> tag that has a scheme attribute value of http://schemas.google.com/g/2005#kind and a term attribute value of http://gdata.youtube.com/schemas/2007#watchHistory. This tag identifies the entry as a watch history feed entry. In a standard video feed entry, this tag has a term attribute value of http://gdata.youtube.com/schemas/2007#video.

• The <id> tag in the watch history feed entry contains a value that refers to the instance of the user watching the video. You can use the <yt:videoid> tag to retrieve the value that YouTube uses to uniquely identify the video.

• In a watch history feed entry, the <published> and <updated> tags specify the time when the user watched the video. You can use the <yt:uploaded> tag to retrieve the time when the video was actually uploaded.

• In a watch history feed entry, the <author> tag identifies the user who watched the video rather than the video uploader. You can use the <media:credit> tag to identify the video owner.

• A watch history feed entry contains a <link> tag that points to the video.

Movies and trailers

Videos must meet special metadata requirements to be included in YouTube's Movies and Trailers categories. Feed entries for those videos accordingly contain several extra tags to reflect the enhanced metadata available for movies and trailers. Note, however, that movie and trailer entries are both types of video feed entries and could be returned in any feed that contains video entries, including search result feeds.

In addition, the YouTube API lets you retrieve several movie and trailer charts, which are standard feeds that only contain videos that appear in YouTube's Movies or Trailers category, respectively.

The following subsections explain the special metadata fields included in movie and trailer entries as well as the movie and trailer charts that the API supports.

Special metadata fields in movie and trailer entries

Video and chart entries might contain several extra tags to reflect the enhanced metadata available for movies and trailers. These enhanced metadata fields are listed below:

• The <yt:availability> tag specifies the date range when the movie or trailer will be available on YouTube.

• The <yt:firstReleased> tag specifies the movie's original release date.

• The entry may contain one or more additional <media:category> tags in addition to the standard one that indicates that the video is in the Movies or Trailers category:

  • A tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/mediatypes.cat indicates whether a video is a feature film, a short film, or a trailer. The following values are valid for this scheme:
    • 1 – Feature-length film
    • 2 – Short film
    • 3 – Full episode
    • 4 – Show clip
    • 5 – Trailer

  • A tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/moviegenres.cat specifies a genre (e.g. "Action & Adventure" or "Comedy") that describes the movie. A movie may be associated with multiple genres. The following values are valid for this scheme:
    • 1 – Action & Adventure
    • 2 – Animation & Cartoons
    • 3 – Classics
    • 4 – Comedy
    • 5 – Crime
    • 6 – Drama
    • 7 – Documentary & Biography
    • 8 – Family
    • 9 – Foreign
    • 10 – Horror
    • 11 – Mystery & Suspense
    • 12 – Romance
    • 13 – Science Fiction
    • 15 – Sports
    • 18 – Indian Cinema
    • 19 – Nigerian Cinema

  • A tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/releasemediums.cat specifies the original release medium for the movie. For example, a movie may have been originally released in theaters or on a premium cable channel. The following values are valid for this scheme:
    • 1 – Theatrical or festival film releases
    • 2 – Premium cable or satellite subscription channels, such as HBO
    • 3 – Basic cable and satellite channels, such as Comedy Central or MTV
    • 4 – Broadcast TV networks and local TV stations
    • 5 – Promotional clips and trailers
    • 6 – Original web content
    • 7 – Direct-to-video release

• The <media:credit> tag can identify a contributor (actor, director, producer, or writer) to the movie, and an entry can include multiple <media:credit> tags.

• The <media:rating> tag can specify an MPAA (Motion Picture Association of America) or V-Chip rating for a movie. The tag's scheme attribute identifies the type of rating, and the tag's value specifies the movie's rating under that scheme.

• A <media:thumbnail> tag with a yt:name attribute value of poster specifies the URL for an image of the movie's poster art.

• A trailer entry may contain a <link> tag that specifies a link to the YouTube Data API feed for the movie featured in the trailer. The tag will have a rel attribute value of http://gdata.youtube.com/schemas/2007#video.trailer-for:
  

  <link rel='http://gdata.youtube.com/schemas/2007#video.trailer-for'
      type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/videos/lJD3ABBCSrc?v=2'/>

  
  

Retrieving a movie chart

To retrieve a movie chart, send a GET request to the URL associated with that chart. Note that you must be using version 2 of the YouTube API to retrieve any of these charts. You can specify the API version using either the v parameter or the GData-Version HTTP request header.

The following table identifies the URL associated with each chart:

API requests to retrieve movie charts can specify any of the following parameters:

• The movie-genre parameter filters a chart to only include movies that are in a particular genre.
• The paid-content parameter filters a chart to only include either paid content or free content. If the parameter is not set, a chart can include both paid and free content.
• The region parameter filters a chart to only include movies that are viewable in a particular territory. The parameter value is an ISO 3166-1 alpha-2 code that identifies the country where videos must be viewable to be included in search results.

Retrieving a trailer chart

Note: As with movie charts, you must be using version 2 of the YouTube API to retrieve any of these charts.

API requests to retrieve trailer charts can also specify a value for the region parameter described in the previous section.

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.

  https://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:

  https://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:

  https://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:
  https://gdata.youtube.com/feeds/api/videos/-/bass/fishing?v=2
  
  category parameter:
  https://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:
  https://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing?v=2
  
  category parameter:
  https://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:
  https://gdata.youtube.com/feeds/api/videos/-/jesse/ventura/News%7CSports?v=2
  
  category parameter:
  https://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:
  https://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy?v=2
  
  category parameter:
  https://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:
    https://gdata.youtube.com/feeds/api/videos/-/
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fcategories.cat%7DNews?v=2
  
    category parameter:
    https://gdata.youtube.com/feeds/api/videos?category=
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fcategories.cat%7DNews&v=2
  
  Keywords:
    URL notation:
    https://gdata.youtube.com/feeds/api/videos/-/
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fkeywords.cat%7Ddog?v=2
  
    category parameter:
    https://gdata.youtube.com/feeds/api/videos?category=
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fkeywords.cat%7Ddog&v=2
  
  Developer tags:
    URL notation:
    https://gdata.youtube.com/feeds/api/videos/-/
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fdevelopertags.cat%7Dexample.com?v=2
  
    category parameter:
    https://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, send a GET request to the following URL, appending the appropriate query parameters to your request:

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

https://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.

Name	Definition
alt	The alt parameter specifies the format of the feed to be returned. Valid values for this parameter are atom, rss, json, json-in-script, and jsonc. The default value is atom and this document only explains the format of Atom responses. For more information about using API responses in JavaScript, please see Using JSON with Google Data APIs. If you set the parameter value to json-in-script, then you must also set the callback parameter value to identify the callback function to which the API response will be sent.
author	In a search request, the author parameter restricts the search to videos uploaded by a particular YouTube user. Note that if you use this parameter when requesting a standard feed, then YouTube will retrieve the standard feed and then filter the response to only include videos uploaded by the specified author. For example, if you request the "Top Rated" feed for user GoogleDevelopers, the API will retrieve the top-rated feed and return a response containing videos in that feed uploaded by user GoogleDevelopers. The API will not return a list of that user's videos ordered by rating. In a request for a user activity feed, the author parameter contains a comma-separated list of up to 20 YouTube usernames. The API response will contain activities performed by any of those users.
callback	The callback parameter identifies the callback function to which the API response will be sent. If the value of the alt parameter is jsonc or json-in-script, and you specify a value for the callback parameter, then the API response will be wrapped in a call to the specified function. This parameter is required if the value of the alt parameter is json-in-script.
fields	The fields parameter serves one or both of the following purposes: It identifies the data fields that should be included in a partial API response. It specifies conditions that should be used to filter the result set. The parameter value is formatted using a syntax inspired by XPath as described in the Formatting the fields parameter value section. That section also explains how conditions specified in the parameter value are applied since 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 fields parameter is currently used for experimental features only.
fields-language	The fields-language parameter is being used temporarily to force the API server to apply new syntax rules affecting requests to retrieve partial API responses. The rules determine whether a tag's text content is returned in a partial response. They also let you filter results based on the presence of an element that does not contain text content. For example, you could retrieve all entries containing the <app:control> tag, which has subtags but does not contain text content. The new rules are explained in detail in the release notes for August 31, 2010. To use the new syntax rules for partial API responses, or to filter results based on the presence of an element that does not contain text content, set the fields-language parameter value to r2. (This is the only valid value for this parameter.) Note: Following a testing period, the new syntax rules will apply to all requests for partial API responses, and the API server will ignore the fields-language parameter.
max-results	The max-results parameter specifies the maximum number of results that should be included in the result set. This parameter works in conjunction with the start-index parameter to determine which results to return. For example, to request the second set of 10 results – i.e. results 11-20 – set the max-results parameter to 10 and the start-index parameter to 11. The default value of this parameter is 25, and the maximum value is 50. However, for displaying lists of videos, we recommend that you set the max-results parameter to 10.
prettyprint	The prettyprint parameter lets you request an XML response formatted with indentations and line breaks. Set the parameter's value to true to have the response formatted as such. The default parameter value is false.
start-index	The start-index parameter specifies the index of the first matching result that should be included in the result set. This parameter uses a one-based index, meaning the first result is 1, the second result is 2 and so forth. This parameter works in conjunction with the max-results parameter to determine which results to return. For example, to request the second set of 10 results – i.e. results 11-20 – set the start-index parameter to 11 and the max-results parameter to 10.
strict	The strict parameter can be used to instruct YouTube to reject an API request if the request contains invalid request parameters. The default API behavior is to ignore invalid request parameters. If you want YouTube to reject API requests that contain invalid parameters, set the strict parameter value to true. For example, YouTube would reject the following request because "foo" is not a valid request parameter. https://gdata.youtube.com/feeds/api/videos?foo=nonono&strict=true
v	The v parameter specifies the version of the API that YouTube should use to handle the API request. Your request can specify the desired API version using either the v parameter or the GData-Version HTTP request header. All Google-provided client libraries always select a major API version. If your request does not specify an API version, YouTube will handle your request using API version 1. Please see the API versioning section for more information about specifying an API version. The current API version is 2. Setting the v parameter value (or the GData-Version HTTP request header value) to 2 allows your application to access features that may not be available in previous API versions. For example, captions are only supported in API version 2, and the API supports some different parameters in version 2 than it did in version 1.

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:

Parameters for all API requests: key Search parameters: 3d caption category duration format hd license location location-radius lr orderby q safeSearch time uploader Additional parameters for all video feeds: restriction

Additional parameters for caption track feeds: fmt lang Additional parameters for user activity feeds: inline Additional parameters for movie charts: movie-genre paid-content region Additional parameters for live event feeds: ends-after ends-before inline starts-after starts-before status time Additional parameters for username suggestion feeds: hint

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:

Name	Definition
3d	The 3d parameter lets you restrict a search to only retrieve 3D videos. This parameter is supported for video search requests, related videos feeds, and standard feeds. It is also only supported in API version 2. To only retrieve 3D videos, set the 3d parameter value to true or include the parameter in your request but do not specify a parameter value. Note that false is not a valid parameter value, and you cannot restrict search results to exclude 3D videos. The API's default behavior is to include both 3D and non-3D videos in returned results. In a video feed entry, the <yt:threed> tag indicates that a video contains 3D content. Note: The API will return an HTTP 400 response if you specify any parameter value other than true.
caption	The caption parameter enables you to restrict a search to videos that have or do not have caption tracks: To only request videos that have captions, set the caption parameter value to true. For example, the URL below would retrieve videos that have captions and that match the search term "surfing": https://gdata.youtube.com/feeds/api/videos?q=surfing&caption&v=2 Note: For backward-compatibility reasons, the API will also only return videos that have captions if you include the caption parameter but do not specify a parameter value. To only request videos that do not have captions, set the caption parameter value to false. For example, the URL below would retrieve videos that do not have captions and that match the search term "surfing": https://gdata.youtube.com/feeds/api/videos?q=surfing&caption=false&v=2 Note: The API will return an HTTP 400 response if you specify the parameter with any value other than true or false.
category	The category parameter enables you to retrieve videos that are in a particular category or are tagged with a particular keyword or developer tag. You can also insert category names, keywords and developer tags into the request URL as described in the Browsing with categories and keywords section. That section provides instructions for formatting the category parameter value for a variety of different types of queries. YouTube supports this parameter for video search requests.
client	Deprecated on March 22, 2010. API requests no longer need to specify a client ID. The client parameter specifies an alphanumeric string that identifies the developer or distributor of an application. The client parameter is an alternate way of specifying your client ID. You can also use the X-GData-Client request header to specify your client ID.
duration	The duration parameter lets you filter search results based on video length. The following parameter values are valid: short – Only include videos that are less than four minutes long. medium – Only include videos that are between four and 20 minutes long (inclusive). long – Only include videos longer than 20 minutes. In a video feed entry, the <yt:duration> tag specifies a video's length.
ends-after	The ends-after parameter restricts a live events feed to only include events that ended or are scheduled to end at or after the specified date and time. The parameter value must be a date or a date and time in ISO 8601 format. If you specify a date, but not a time, the API response will include events that ended on or after the specified date. For example, if you set the parameter value to 2011-06-15, the API will include events that ended on June 15, 2011, in the response. If you specify a date and a time, the API response will include events that ended at or after the specified time. Note: The ends-after parameter is currently used for experimental features only.
ends-before	The ends-before parameter restricts a live events feed to only include events that ended or are scheduled to end at or before the specified date and time. The parameter value must be a date or a date and time in ISO 8601 format. If you specify a date, but not a time, the API response will include events that ended before the specified date. For example, if you set the parameter value to 2011-06-15, the API will return events that ended on June 14, 2011, but not events that ended on June 15, 2011. If you specify a date and a time, the API response will include events that ended at or before the specified time. Note: The ends-before parameter is currently used for experimental features only.
fmt	The fmt parameter specifies the return format for a caption track that you are retrieving via the API. Set the parameter value to one of the following values: sbv – Subviewer-compatible srt – Subrip-compatible If you are retrieving a caption track generated using automatic speech recognition and you do not set a value for this parameter, the API will automatically return the track in Subviewer-compatible (sbv) format. The API will return an HTTP 400 response code if YouTube cannot convert the original caption track to the requested format.
format	The format parameter, which is supported for video search requests, specifies that videos must be available in at least one of the video formats listed in the parameter value. Your request can specify one or more of the following formats: Value Video Format 1 RTSP streaming URL for mobile video playback. H.263 video (up to 176x144) and AMR audio. 5 HTTP URL to the embeddable player (SWF) for this video. This format is not available for a video that is not embeddable. Developers commonly add &format=5 to their queries to restrict results to videos that can be embedded on their sites. 6 RTSP streaming URL for mobile video playback. MPEG-4 SP video (up to 176x144) and AAC audio. To specify multiple formats, separate format values with a comma. For example, format=1,5 indicates that the API should return videos that are available in at least one of those two formats.
hd	The hd parameter lets you restrict a search to only include HD videos, meaning videos that are available for playback in at least 720p. Higher resolutions, like 1080p, might be available for HD videos as well. This parameter is supported for video search requests, related videos feeds, and standard feeds. It is also only supported in API version 2. To only retrieve HD videos, set the hd parameter value to true or include the parameter in your request but do not specify a parameter value. Note that false is not a valid parameter value, and you cannot restrict search results to exclude HD videos. The API's default behavior is to return all videos, regardless of their resolution. In a video feed entry, the <yt:hd> tag indicates that a video contains HD content. Note: The API will return an HTTP 400 response if you specify any parameter value other than true.
hint	The hint parameter is specified in a request to retrieve a list of unused YouTube usernames that are similar to that hint.
inline	The inline parameter is only supported for activity feeds and live event feeds. In a request to retrieve an activity feed, this parameter indicates whether events in the feed that involve videos – 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. If the video entry is included, it will be encapsulated inside the <link> element that has a rel attribute value of http://gdata.youtube.com/schemas/2007#video. Set the parameter's value to true to specify that video entries should be embedded inside the activity feed. In a request to retrieve a live events feed, this parameter indicates whether events in the feed will include a live video entry or a playlist entry that contains information about the event's video stream or streams, respectively. If an entry is inlined, it will be encapsulated inside the event entry's <content> element. Set the parameter value to true to specify that video (or playlist) entries should be embedded in the event entries. Note: Live event feeds are an experimental API feature (). The default parameter value is false.
key	The key parameter specifies your developer key, an alphanumeric string that uniquely identifies the application making an API request. You can also use the X-GData-Key request header to specify your developer key. Your application does not need to specify your developer key twice by using both the key parameter and the X-GData-Key request header, but it should provide your developer key using at least one of those two methods.
lang	The lang parameter specifies the language into which you want a caption track to be translated. Set the parameter value to the ISO 639-1 two-letter language code that identifies the desired caption language. YouTube supports this parameter for requests to retrieve a caption track. The API will return an HTTP 400 response code if YouTube cannot translate the caption track to the requested language or if the language code that you specified is not valid.
license	The license parameter lets you filter search results to only include videos with a particular license. YouTube lets video uploaders choose to attach either the Creative Commons license or the standard YouTube license to each of their videos, and the license parameter supports the following values: cc – Only return videos that have a Creative Commons license. Users can reuse videos with this license in other videos that they create. Learn more. youtube – Only return videos that have the standard YouTube license. The API's default behavior is to return all videos, regardless of which license they have. In a video feed entry, the <media:license> tag identifies the license that is associated with a video.
location	The location parameter restricts the search to videos that have a geographical location specified in their metadata. The parameter can be used in either of the following contexts: The parameter value can specify geographic coordinates (latitude,longitude) that identify a particular location. In this context, the location parameter operates in conjunction with the location-radius parameter to define a geographic area. The API response will then contain videos that are associated with a geographical location within that area. Note that when a user uploads a video to YouTube, the user can associate a location with the video by either specifying geographic coordinates (-122.08427,37.42307) or by providing a descriptive address (Munich, Germany). As such, some videos may be associated with a location within the area specified in a search query even though those videos are not associated with specific coordinates that can be plotted on a map. To exclude videos from the API response if those videos are associated with a descriptive address but not with specific geographic coordinates, append an exclamation point ("!") to the end of the parameter value. This practice effectively ensures that all videos in the API response can be plotted on a map. The following examples show sample uses of this parameter: location=37.42307,-122.08427&location-radius=100km location=37.42307,-122.08427!&location-radius=100km In an API response, feed entries that are associated with specific coordinates will contain the <georss:where> tag and may also contain the <yt:location> tag. Feed entries that are associated with a descriptive address but not with specific geographic cooordinates specify the address using the <yt:location> tag. The parameter value can be empty or a single exclamation point. In this context, the parameter does not require a value and its presence serves to restrict the search results to videos that have a geographical location, but it does not enable you to find videos with a specific geographical location. This parameter can be used with all video feeds. A video that has a geographical location will have a <georss:where> tag in its metadata. YouTube supports this parameter for video search requests.
location-radius	The location-radius parameter, in conjunction with the location parameter, defines a geographic area. If the geographic coordinates associated with a video fall within that area, then the video may be included in search results. The location-radius parameter value must be a floating point number followed by a measurement unit. Valid measurement units are m, km, ft and mi. For example, valid parameter values include "1500m", "5km", "10000ft" and "0.75mi". The API will return an error if the radius is greater than 1000 kilometers. YouTube supports this parameter for video search requests.
lr	In a video search request, the lr parameter restricts the search to videos that have a title, description or keywords in a specific language. This parameter can be used when requesting any video feeds other than standard feeds. In a request to retrieve a list of the caption tracks available for a video, the lr parameter filters the list of caption tracks to only include the specified language. Valid values for the lr parameter are ISO 639-1 two-letter language codes. You can also use the values zh-Hans for simplified Chinese and zh-Hant for traditional Chinese.
movie-genre	The movie-genre parameter restricts a movie chart to only include movies in a particular genre. The parameter value is an integer that corresponds to a particular genre. The following values are valid: 1 – Action & Adventure 2 – Animation & Cartoons 3 – Classics 4 – Comedy 5 – Crime 6 – Drama 7 – Documentary & Biography 8 – Family 9 – Foreign 10 – Horror 11 – Mystery & Suspense 12 – Romance 13 – Science Fiction 15 – Sports 18 – Indian Cinema 19 – Nigerian Cinema
orderby	The orderby parameter, which is supported for video feeds and playlist feeds, specifies the method that will be used to order entries in the API response. The parameter is used differently for video and playlist feeds: In a request for a video feed, the following values are valid for this parameter: relevance – Entries are ordered by their relevance to a search query. This is the default setting for video search results feeds. published – Entries are returned in reverse chronological order. This is the default value for video feeds other than search results feeds. viewCount – Entries are ordered from most views to least views. rating – Entries are ordered from highest rating to lowest rating. When searching for videos, you can also request results that are most relevant to a specific language by setting the parameter value to relevance_lang_languageCode, where languageCode is an ISO 639-1 two-letter language code. (Use the values zh-Hans for simplified Chinese and zh-Hant for traditional Chinese.) Please note that results in other languages will still be returned if they are highly relevant to the search query term. In a request for a playlist feed, the following values are valid for this parameter: position – Entries are ordered by their position in the playlist. This is the default setting. commentCount – Entries are ordered by number of comments from most comments to least comments. duration – Entries are ordered by length of each playlist video from longest video to shortest video. published – Entries are returned in reverse chronological order. title – Entries are ordered alphabetically by title. viewCount – Entries are ordered from most views to least views. Note: A user's playlists feed is ordered by publication time beginning with the newest playlist. For a user's subscriptions feed, the default ordering is arbitrary.
paid-content	The paid-content parameter can be used to restrict a search or a movie chart to only include either paid content or free content. By default, search results and movie charts include both paid and free content. To restrict a result set to only include paid content, set the paid-content parameter value to true or include the parameter in your request but do not specify a parameter value. To restrict a result set to exclude paid content, set the paid-content parameter value to false. Using the paid_content parameter for movie charts For paid content, the video uploader will define offers that specify the country where a video can be rented. For example, a movie may be available for rental in the United States before it can be rented in other countries. As such, you must also specify a value for the region parameter if you want any paid content to be included in the API results.
q	The q parameter specifies a search query term. YouTube will search all video metadata for videos matching the term. Video metadata includes titles, keywords, descriptions, authors' usernames, and categories. Note that any spaces, quotes or other punctuation in the parameter value must be URL-escaped. To search for an exact phrase, enclose the phrase in quotation marks. For example, to search for videos matching the phrase "spy plane", set the q parameter to %22spy+plane%22. Your request can also use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several search terms. For example, to search for videos matching either "boating" or "sailing", set the q parameter to boating%7Csailing. (Note that the pipe character must be URL-escaped.) Similarly, to search for videos matching either "boating" or "sailing" but not "fishing", set the q parameter to boating&7Csailing+-fishing.
region	The region parameter restricts a movie chart to only list content that is viewable in a specified region. If set, the parameter value must be an ISO 3166-1 alpha-2 country code. The default behavior is to return content that is viewable worldwide. Important: You must specify a region parameter value if you want a movie chart to include rental (paid-content) videos. If you do not specify a value for this parameter, the chart will only contain movies that are viewable worldwide. Since each video rental offer specifies the country where the offer is valid, YouTube can only determine whether a user could potentially view a rental video if an API request specifies the country where the user is located. Since there are no rental videos that are accessible worldwide, a chart will be empty if you set the paid-content parameter to true for a movie chart and do not also specify a region parameter value.
restriction	The restriction parameter identifies the IP address that should be used to filter videos that can only be played in specific countries. We recommend that you always use this parameter to specify the end user's IP address. (By default, the API filters out videos that cannot be played in the country from which you send API requests. This restriction is based on your client application's IP address.) To request videos playable from a specific computer, include the restriction parameter in your request and set the parameter value to the IP address of the computer where the videos will be played – e.g. restriction=255.255.255.255. To request videos that are playable in a specific country, include the restriction parameter in your request and set the parameter value to the ISO 3166 two-letter country code of the country where the videos will be played – e.g. restriction=DE. You should include this parameter in any request to retrieve a list of videos, including search results, playlists, favorite videos, video responses and so forth. If a video in the API response is not playable in the location that you're using to restrict availability of the content, the <entry> for that tag will not contain a <media:content> tag. However, it will contain a <yt:state> tag that indicates that the video is restricted.
safeSearch	The safeSearch parameter indicates whether the search results should include restricted content as well as standard content. YouTube will determine whether content is restricted based on the user's IP address or location, which you specify in your API request using the restriction parameter. If you do request restricted content, then feed entries for videos that contain restricted content will contain the <media:rating> element. The following values are valid for this parameter: Value Description none YouTube will not perform any filtering on the search result set. moderate YouTube will filter some content from search results and, at the least, will filter content that is restricted in your locale. Based on their content, search results could be removed from search results or demoted in search results. Note: The default value for the safeSearch parameter is moderate. strict YouTube will try to exclude all restricted content from the search result set. Based on their content, search results could be removed from search results or demoted in search results. SafeSearch filtering for the YouTube Data API is designed to function similarly to SafeSearch Filtering for Google WebSearch results. Please note that YouTube makes every effort to remove restricted content from search results in accordance with the SafeSearch setting that you specify. However, filters may not be 100% accurate and restricted videos may occasionally appear in search results even if you have specified strict SafeSearch filtering. If this happens, please flag the video by filing a complaint, which will help us to better identify restricted content. Note: The safeSearch parameter was introduced in version 2 of the YouTube Data API and replaced the racy parameter, which was used in version 1. YouTube supports this parameter for video search requests.
starts-after	The starts-after parameter restricts a live events feed to only include events that began or are scheduled to begin at or after the specified date and time. The parameter value must be a date or a date and time in ISO 8601 format. If you specify a date, but not a time, the API response will include events that started on or after the specified date. For example, if you set the parameter value to 2011-06-15, the API will include events that started on June 15, 2011, in the response. If you specify a date and a time, the API response will include events that started at or after the specified time. Note: The starts-after parameter is currently used for experimental features only.
starts-before	The starts-before parameter restricts a live events feed to only include events that began or are scheduled to begin at or before the specified date and time. The parameter value must be a date or a date and time in ISO 8601 format. If you specify a date, but not a time, the API response will include events that started before the specified date. For example, if you set the parameter value to 2011-06-15, the API will return events that started on June 14, 2011, but not events that started on June 15, 2011. If you specify a date and a time, the API response will include events that started at or before the specified time. Note: The starts-before parameter is currently used for experimental features only.
status	The status parameter restricts a live event feed to only list events with the specified status. The following values are valid: pending – The event has not started yet. active – The event has already started but has not yet ended. completed – The event has already ended. delayed – The event has not yet started and will start later than its originally scheduled time. cancelled – The event, though scheduled, will not happen. rejected – YouTube will not stream the event. Note: The status parameter is currently used for experimental features only.
time	The time parameter is supported for search feeds and for a number of standard feeds and live event charts as well. Valid values for this parameter are today (1 day), this_week (7 days), this_month (1 month) and all_time. The default value for this parameter is all_time. In a request to retrieve search results, the time parameter restricts the search to videos uploaded within the specified time. In a request to retrieve a standard feed or live event chart, the time parameter restricts the API response to only contain results relevant to the specified time frame. For example, if the time parameter value is set to this_week in a request for the most_viewed standard video feed, the feed will contain the videos that were viewed most often over the previous one-week period. This parameter is supported for the following feeds and charts: Standard video feeds top_rated top_favorites most_viewed most_popular most_discussed most_responded Standard channel feeds most_subscribed – This feed only supports the parameter values this_week, this_month, and all_time. most_viewed Live event charts ( experimental feature) upcoming – This feed only supports the parameter values today and this_week.
uploader	The uploader parameter, which is only supported for search requests, lets you restrict a query to YouTube partner videos. A YouTube partner is a person or organization that has been accepted into and participates in the YouTube Partner Program. The uploader parameter's value must be partner. In an API response, a feed entry contains a partner video if the entry contains a <media:credit> tag for which the value of the yt:type attribute is partner. <media:credit role="uploader" scheme="urn:youtube yt:type="partner">partner_name</media:credit> YouTube supports this parameter for video search requests.

Retrieving information about a single video

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

https://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 send an authenticated GET request to the following URL:

https://gdata.youtube.com/feeds/api/users/USERNAME/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.

https://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 sending a 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.

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

https://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='https://gdata.youtube.com/feeds/api/channels?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/channels/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/channels?q=soccer&start-index=11&max-results=10&v=2'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/channels?alt=atom-service&v=2'/>
  <link rel='next' type='application/atom+xml'
    href='https://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='https://gdata.youtube.com/feeds/api/videos/bYKugypF8HA?v=2'/>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/profile?user=ussoccerdotcom'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/channels/dXNzb2NjZXJkb3Rjb20?v=2'/>
    <author>
      <name>ussoccerdotcom</name>
      <uri>https://gdata.youtube.com/feeds/api/users/ussoccerdotcom</uri>
    </author>
    <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#channel.content'
      href='https://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 a 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>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#channelstandard'/>
  <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='https://gdata.youtube.com/feeds/api/channelstandardfeeds/most_viewed/c/expertvillage?v=2'/>
  <author>
    <name>expertvillage</name>
    <uri>https://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 a GET request to the following URL:

https://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:

https://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 a GET request to the following URL:

https://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 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:

https://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.

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, send a GET request to the following URL:

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

https://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='https://gdata.youtube.com/feeds/api/playlists/snippets?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml' href='https://gdata.youtube.com/feeds/api/playlists/snippets?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml' href='https://gdata.youtube.com/feeds/api/playlists/snippets/batch?v=2'/>
  <link rel='self' type='application/atom+xml' href='https://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='https://gdata.youtube.com/feeds/api/playlists/snippets?alt=atom-service&v=2'/>
  <link rel='next' type='application/atom+xml' href='https://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='https://gdata.youtube.com/feeds/api/playlists/E6DE6EC9A373AF57?v=2'/>
    <link rel='related' type='application/atom+xml' href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers?v=2'/>
    <link rel='alternate' type='text/html' href='https://www.youtube.com/view_play_list?p=E6DE6EC9A373AF57'/>
    <link rel='self' type='application/atom+xml' href='https://gdata.youtube.com/feeds/api/playlists/snippets/E6DE6EC9A373AF57?v=2'/>
    <link rel='edit' type='application/atom+xml' href='https://gdata.youtube.com/feeds/api/playlists/snippets/E6DE6EC9A373AF57?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://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.

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 a 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 a 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 64 GB or smaller. All users can upload videos up to 15 minutes long, and many users with a history of complying with the YouTube Community Guidelines can upload videos longer than that. You may compress API requests using gzip transfer-encoding. However, please note that the 64 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.

Control	Permissions	Definition
rate	allowed* denied	This control indicates whether users can rate the video.
comment	allowed* moderated denied	This control indicates whether users can add comments about the video. If you moderate comments, then you must approve new comments before they will be visible to other users.
commentVote	allowed* denied	This setting indicates whether rate comments about the video.
videoRespond	allowed moderated* denied	This setting indicates whether users can add video responses to the video. If you moderate video responses, then you must approve new responses before they will be visible to other users.
list	allowed* denied	This setting indicates whether a video can be listed in YouTube search results or displayed in any other way unless the user has a URL that links directly to the video. The permission for this setting will be denied if the video is either unlisted or private. If you set the value to denied for a public video, then that video will become an unlisted video.
embed	allowed* denied	This setting indicates whether users can embed the video on third-party websites.
syndicate	allowed* denied	This setting indicates whether YouTube can show the video on non-web platforms, such as mobile phones and televisions.

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.

Note: If a user has uploaded content, such as a music video, that is owned by another user, then the actual content owner may override the access control settings that the uploader provided. See the <yt:accessControl> tag definition for a list of exceptions.

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:
https://gdata.youtube.com/feeds/api/videos/

Retrieving videos associated with a developer tag:
https://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 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 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 a 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 a 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 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 POST request.

• content_length - This value contains the length, in bytes, of the entire body of the 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 a 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, send a 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 a 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 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 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 a 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 response will contain 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 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 PUT request.

• Binary File Data – This value contains the binary code for the video file that you are uploading.

The following example shows a 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 a 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 send a new 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 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 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, send a GET request to the URL identified in this <link> tag.

  <link rel='self' type='application/atom+xml'
      href='https://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, retrieve the video entry from the video owner's uploaded videos feed and send a PUT request to the entry's edit URL:

<link rel='edit' type='application/atom+xml'
   href='https://gdata.youtube.com/feeds/api/users/USERNAME/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/USERNAME/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 a DELETE request to the edit URL for that video as shown in the following example:

DELETE /feeds/api/users/USERNAME/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 request 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="https://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 sending a 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='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4?v=2'/>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
     href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions?...'/>
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions?v=2'/>
  <link rel='service' type='application/atomsvc+xml' 
    href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions?alt=...'/>
  <author>
    <name>GoogleDevelopers</name>
    <uri>https://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='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captiondata/ChkLEO...'
      xml:lang='en'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/ChkLEO...'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/ChkLEO...'/>
    <link rel='edit-media' type='application/vnd.youtube.timedtext'
      href='https://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='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captiondata/CiMLEO...'
      xml:lang='en'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/CiMLEO...'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captions/CiMLEO...'/>
    <link rel='edit-media' type='application/vnd.youtube.timedtext'
      href='https://gdata.youtube.com/feeds/api/videos/EdDc7sWjCL4/captiondata/CiMLEO...'/>
  </entry>
</feed>

Creating a caption track

To create a caption track, post a caption file or transcript to the http://schemas.google.com/g/2005#post link for the captions track feed. The following guidelines explain how to format your API request:

• 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. The header value should be URL-escaped. In addition, to specify non-ASCII characters in a track title, you need to ensure that the title is a UTF-8 string and then URL-escape it. For example, the string El mejor día (the best day) would be specified in a Slug header as El%20mejor%20d%C3%ADa.

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

Uploading a video transcript without caption timecodes

If YouTube's Text-to-Speech (TTS) server does not recognize your caption file format, YouTube will try to automatically sync the caption track to the audio track in your video. This functionality enables you to upload a video transcript without any caption timecodes at all and have YouTube generate a caption track from the transcript. The transcript does not have to be formatted in any particular way and could just be paragraphs of text.

Sample API response for uploaded caption track

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: https://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='https://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captiondata/CiULE...'
    xml:lang='en'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions/CiULE...'/>
  <link rel='edit' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captions/CiULE...'/>
  <link rel='edit-media' type='application/vnd.youtube.timedtext'
    href='https://gdata.youtube.com/feeds/api/videos/PjLv88-zqkI/captiondata/CiULE...'/>
</entry>

If your 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 a 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="https://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 or the instructions for retrieving a caption track in an alternate format.

In addition, the following rules apply to generated caption tracks:

• If you are retrieving a track that YouTube generated using automatic speech recognition (ASR), then you can also use the fmt parameter to specify that the track should be returned in Subviewer-compatible (sbv) or Subrip-compatible (srt) format. (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 automatically return the track in Subviewer-compatible format.

• If you are retrieving a track that YouTube automatically synchronized to your video, you can use the fmt parameter to specify the format in which which the track should be returned. If you do not specify a fmt parameter value, then the API will return the original transcript that you uploaded. Thus, you must specify a fmt parameter value to retrieve the track's timecodes.

The API supports two other 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 a PUT request to the edit-media link in the caption track entry:

<link rel="edit-media" type="application/atml+xml"
  href="https:/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 a 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

Live events ( Experimental)

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

A live-streaming event is an event that is broadcast on YouTube as it occurs. The API uses the following feeds and entries to return information about live-streaming events:

• An event feed contains a list of live-streaming events created by a specific user. An event feed comprises a series of event entries.

• An event entry contains metadata about a single live-streaming event, such as the event's name, description, start time, and status. An event entry is currently associated with a single live video entry; however, a single event may eventually be associated with multiple live video entries.

• A live video entry contains information about a live video stream of an event. A live video entry is an extension of the video entry, which is used in other types of video feeds, including search feeds, uploads, and so forth. A live video entry may also contain additional tags that would be used to convey information about a live video stream but that would not be relevant to other videos, such as information about the content delivery network used to stream the content.

  If a video entry refers to a live video, the entry will contain a <category> tag with a scheme attribute value of http://schemas.google.com/g/2005#kind and a term attribute value of http://gdata.youtube.com/schemas/2007#liveVideo.

Retrieving live events

The following sections explain different options for retrieving live-streaming events:

Live event charts

You can retrieve several different standard feeds, or charts, listing live events on YouTube.

To retrieve a live event chart, send a GET request to the URL associated with that chart. Note that you must be using version 2 of the YouTube API to retrieve any of these charts. You can specify the API version using either the v parameter or the GData-Version HTTP request header.

The following table describes the charts that you can retrieve and identifies the URL associated with each chart:

API requests to retrieve live event charts can specify any of the following parameters:

• The region parameter filters a chart to only include live events that are featured within the specified region.

Retrieving a user's events feed

This section explains how to retrieve a feed listing a specific user's live-streaming events. Note that YouTube has not enabled all user accounts to create and stream live events. If a user has not created any live-streaming events or is not allowed to create live-streaming events, that user's events feed will not contain any entries.

• To request a feed of the currently logged-in user's live-streaming events, 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.

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

• To request a feed of another user's live-streaming events, send an HTTP GET request to the following URL. Note that this request does not require authentication.

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

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

Determining whether a user can create live events

If a user can create live events, then the user's profile entry will contain a <gd:feedLink> that points to the user's events feed. The tag will have the following attributes:

• The rel attribute value will be http://gdata.youtube.com/schemas/2007#user.live.
• The href attribute value will specify the URL of the user's events feed.
• The countHint attribute value will specify the number of events in the feed.

The XML below shows a sample <gd:feedLink> tag:

<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.live'
    href='https://gdata.youtube.com/feeds/api/users/username/live/events?v=2'
    countHint='11'/>

Special query parameters for retrieving live events

YouTube supports the following API query parameters specifically for requests to retrieve live event feeds:

• status – The API response will only include events that are either pending (not yet started), active (in progress), completed, cancelled, or rejected.
• starts-before – The API response will only include events that started before (or will start before) the given date and time.
• starts-after – The API response will only include events that started after (or will start after) the given date and time.
• ends-before – The API response will only include events that ended before (or will end before) the given date and time.
• ends-after – The API response will only include events that ended after (or will end after) the given date and time.

In addition, you can use the inline parameter to indicate that each entry in a live events feed should, in turn, contain an entry that points to the actual video content associated with the event. For example, the live event entry could contain a video entry if there is a single video stream associated with the event, or it could contain a playlist entry if there are multiple videos associated with the event.

• If you set the inline parameter to true, the <content> tag in each event feed entry will encapsulate a video or playlist entry containing details about the video(s) associated with the event.

• If you do not set the inline parameter or you set the parameter's value to false, the <content> tag in each event feed entry will contain a src attribute that points to the URL you would use to retrieve information about the video.

  If you do set the inline parameter to true, you may find it helpful to use the partial response feature to limit the size of the API response.

Sample live events feed

The following API request retrieves the live events for the YouTube user ytatestuser. Since the inline parameter is set to true, each entry's <content> tag will encapsulate the video entry associated with the event.

https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events?v=2&inline=true

The following XML shows the API response for this request. The feed contains a series of <entry> tags, with each entry describing a live event. Each entry contains the title, description, author, date, and status of an event, among other fields. (Note that only the first entry is displayed below.)

<?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:gd='http://schemas.google.com/g/2005'
    gd:etag='W/&quot;CEMDSHwyeCp7ImA9WhZWF0s.&quot;'>
  <id>tag:youtube.com,2008:user:ytatestuser:live:events</id>
  <updated>2011-05-18T23:47:59.290Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#liveEvent'/>
  <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='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events'/>
  <link rel='http://schemas.google.com/g/2005#post' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events/batch'/>
  <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events?start-index=1&max-results=25'/>
  <link rel='service' type='application/atomsvc+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events?alt=atom-service'/>
  <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>4</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>

  <entry
      gd:etag='W/&quot;C08MR347eCp7ImA9WhZWGUk.&quot;'>
    <id>tag:youtube.com,2008:live:event:ABF128AfLamNfZYVMiky</id>
    <published>2011-05-03T17:44:47.000Z</published>
    <updated>2011-05-21T01:38:06.000Z</updated>
    <app:edited>2011-05-21T01:38:06.000Z</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#liveEvent'/>
    <title>Test Event</title>
    <summary>Testing live streaming.</summary>
    <content type='application/atom+xml'>

      <entry
          gd:etag='W/&quot;DkEMRn47eCp7ImA9WhZXFEk.&quot;'>
        <id>tag:youtube.com,2008:video:BM7FWtADD0s</id>
        <published>2011-05-03T17:44:47.000Z</published>
        <updated>2011-05-03T17:44:47.000Z</updated>
        <app:edited>2011-05-03T17:44:47.000Z</app:edited>
        <app:control>
          <app:draft>yes</app:draft>
          <yt:state name='processing'/>
        </app:control>
        <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='Entertainment' label='Entertainment'/>
        <category scheme='http://gdata.youtube.com/schemas/2007/keywords.cat'
            term='match'/>
        <title>Test Event</title>
        <link rel='alternate' type='text/html'
            href='https://www.youtube.com/watch?v=BM7FWtADD0s&feature=youtube_gdata'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.responses' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/responses?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.ratings' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/ratings?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.complaints' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/complaints?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.related' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/related?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#video.captionTracks' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/captions?v=2'/>
        <link rel='http://gdata.youtube.com/schemas/2007#insight.views'
            type='text/html'
            href='http://insight.youtube.com/video-analytics/csvreports?query=...'/>
        <author>
          <name>ytatestuser</name>
          <uri>https://gdata.youtube.com/feeds/api/users/ytatestuser</uri>
        </author>
        <yt:accessControl action='comment' permission='allowed'/>
        <yt:accessControl action='commentVote' permission='allowed'/>
        <yt:accessControl action='videoRespond' permission='moderated'/>
        <yt:accessControl action='rate' permission='allowed'/>
        <yt:accessControl action='embed' permission='allowed'/>
        <yt:accessControl action='list' permission='allowed'/>
        <yt:accessControl action='syndicate' permission='allowed'/>
        <gd:comments>
          <gd:feedLink href='https://gdata.youtube.com/feeds/api/videos/BM7FWtADD0s/comments?v=2'
              countHint='0'/>
        </gd:comments>
        <media:group>
          <media:category label='Entertainment'
            scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>Entertainment</media:category>
          <media:content url='http://www.youtube.com/v/BM7FWtADD0s?f=videos&app=youtube_gdata'
              type='application/x-shockwave-flash' medium='video' isDefault='true'
              expression='full' duration='0' yt:format='5'/>
          <media:credit role='uploader' scheme='urn:youtube'>ytatestuser</media:credit>
          <media:description type='plain'>Testing live streaming.</media:description>
          <media:keywords>testing</media:keywords>
          <media:player url='https://www.youtube.com/watch?v=BM7FWtADD0s&feature=youtube_gdata_player'/>
          <media:restriction type='country'
              relationship='deny'>FR DE SE</media:restriction>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/default.jpg'
              height='90' width='120' time='00:00:00' yt:name='default'/>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/hqdefault.jpg'
              height='360' width='480' yt:name='hqdefault'/>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/1.jpg'
              height='90' width='120' time='00:00:00' yt:name='start'/>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/2.jpg'
              height='90' width='120' time='00:00:00' yt:name='middle'/>
          <media:thumbnail url='http://i.ytimg.com/vi/BM7FWtADD0s/3.jpg'
              height='90' width='120' time='00:00:00' yt:name='end'/>
          <media:title type='plain'>Test Event</media:title>
          <yt:duration seconds='0'/>
          <yt:uploaded>2011-05-03T17:44:47.000Z</yt:uploaded>
          <yt:videoid>BM7FWtADD0s</yt:videoid>
        </media:group>
      </entry>

    </content>
    <link rel='http://gdata.youtube.com/schemas/2007#video'
        type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/videos/values%3A+%22$2BM7FWtADD0s?v=2'/>
    <link rel='self' type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events/ABF128AfLamNfZYVMiky'/>
    <link rel='edit' type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events/ABF128AfLamNfZYVMiky'/>
    <author>
      <name>ytatestuser</name>
      <uri>https://gdata.youtube.com/feeds/api/users/ytatestuser</uri>
    </author>
    <media:group>
      <media:description type='plain'>Testing live streaming.</media:description>
      <media:title type='plain'>Test Event</media:title>
    </media:group>
    <yt:status>pending</yt:status>
    <yt:when start='2011-06-24T00:00:00.000Z'/>
  </entry>

</feed>

Retrieving a single live event

There are two ways to obtain the API URL from which you would request information about a single live event:

• In an event feed entry, the <link> tag that has a rel attribute value of self specifies the URL from which you would retrieve that same entry via the API. When retrieving a live event entry, you can use the inline parameter in the same way that you would use it when requesting a live events feed.

• If a video entry contains a <link> tag for which the rel attribute value is http://gdata.youtube.com/schemas/2007#live.event, then the video is associated with a live event. The tag's href attribute value will specify the API URL that you would use to retrieve information about the event itself.

Managing live events

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

This section describes the stages in the life of a live YouTube event and identifies the types of API requests that you will need to make as you manage the event from the time of its creation through its completion. It then explains the specific API calls that you will use to create, modify, and delete live events as well as the video metadata for those events.

All of the operations described in this section require you to send authenticated API requests and to specify the developer key assigned to your application. API requests can specify your developer key using either the X-GData-Key HTTP request header or the key query parameter. Please see http://code.google.com/apis/youtube/dashboard for instructions on how to register a YouTube API client application and obtain a developer key.

Prerequisites

Please note the following prerequisites for using the API functionality described in this section:

1. Developers need to sign an API Testing Agreement before their applications can successfully issue requests to manage live events. Please contact the YouTube developer relations team via a post to the YouTube APIs Developer Forum if you are interested in incorporating this functionality into your application.

2. The ability to create, update, and delete live events is only available to some YouTube users. The Determining whether a user can create live events section explains how to check a user's profile entry to see whether a user has access to these features.

Understanding the YouTube event lifecycle

The following steps explain the steps in the life of a YouTube event and identify the API operations associated with each step. In addition, please refer to YouTube's recommended encoding specifications for live video streams before planning your broadcasts.

1. You create the event by sending the event name, description, and approximate time in a POST request to add an event. If you know the CDN configuration details, you can specify them when adding the event. Otherwise, YouTube will return an ingestion (stream) URL in the default streaming format. The event is created with a status of pending.

2. You process the API response to capture the RTMP stream name and the RTMP stream URL for your event. If you are also broadcasting a backup video stream, capture the RTMP stream name and URL for the backup stream as well.

3. Prior to the event, you update the event as necessary to address any changes in the event details. For example, you might update the event's description or its expected start time.

4. Before you are ready to begin broadcasting, capture the RTMP stream URL and stream name for the event if you have not done so already. You can retrieve that information from the live video entry. The <media:content> tag, which is a child of the <yt:cdn> tag, specifies both values. Also make sure you have the backup RTMP stream information if you are broadcasting a backup stream.

5. You have the option of previewing your broadcast without making your live video stream visible to other users. Note that you do not need to send an API request to begin previewing your content.

   The following steps explain how to preview your content:

   1. Start streaming video to the RTMP URL for your event without updating the event to indicate that it has started.

   2. Log in to your YouTube account.

   3. Go to the Live tab on your channel page, click the name of the event in the list of upcoming events, and then click the Broadcast Now button in the video player area. You should see your stream appear on your channel within a few seconds.

      

   4. You can stop the video stream and restart it when you are ready or proceed directly to step 7.

6. Start streaming video to the RTMP URL for your event. If you are also broadcasting to a backup URL, begin streaming to that URL as well. If you were previewing your stream and did not stop the stream, you will have already completed this action.

7. Start the event by sending an API request that updates the event and sets the <yt:when> tag's start attribute to now. This request will change the event's status from pending to active.

   At this time, your video stream will be visible to other users who are tuned in and waiting for the event to be broadcast on your channel page.

8. End the event by sending an API request that updates the event and sets the <yt:when> tag's end attribute to now. This request will change the event's status from active to completed.

   At this time, your video stream will stop being visible to users tuned in to watch your event.

Adding a live event

To create a live event, you must at least specify a minimal amount of information about the event itself, namely the event's title, description, and start time. You can also specify the CDN configuration for the event's video stream, other metadata about the video stream, or both. If you do not specify CDN details for the live video stream, YouTube will still create a live video with default CDN parameters and associate it with your event.

• If you do not specify CDN configuration details for the event's video, YouTube will return an ingestion URL that expects to receive a 360p Flash video (FLV) stream.

• If you do not specify video metadata for the event, YouTube will use the following default values:

  • The video title (<media:title>) and the video description (<media:description>) will be the same as the event title and event description, respectively. (Currently, any title or description that you specify in the video metadata will be ignored, and the video title and description will be set to match the event title and description.)

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

When you create a live event, the API will return the live event entry. If you also set the inline parameter to true, then the entry's <content> tag will contain the live video entry for the video associated with the event.

The following sample requests demonstrate how to use the API to create new events:

Adding a live event with minimal details

The following example shows how to add a live event by only providing the minimum required amount of information about the event itself. The following event details are required in this request (and in any API request to add an event):

• The <title> tag specifies the event's title.
• The <summary> tag contains a description of the event.
• The <yt:when> tag specifies the event's scheduled start time. You have the option of also specifying an (approximate) end time.

Sample XML

POST /feeds/api/users/USERNAME/live/events 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'>
  <title>Monster truck rally - Sunday June 26!</title>
  <summary>Sunday! Sunday! Sunday! Monster trucks at the county fairgrounds!</summary>
  <yt:when start='2011-06-26T20:00:00.000Z'/>
</entry>

Adding a live event with CDN configuration

The example below shows how to add a live event and also specify the formats in which the live video will be streamed. The sample request specifies primary and secondary CDN information, though the secondary streaming is optional. YouTube will return one RTMP URL for each specified format. The client application that streams the video to YouTube will then send the video content to the appropriate URL for each format in which the video is streamed.

This example indicates that the video will be streamed in formats 18 (360p FLV) and 19 (480p FLV). It also indicates that secondary streams will be available for both formats. See the definition of the <media:content> tag's yt:format parameter for a list of valid parameter values.

Note: If you specify primary and secondary CDN information, then you should stream your content to the primary and secondary ingestion URLs simultaneously. YouTube will use the data from the primary ingestion stream but will switch to the secondary stream if the connection to the primary stream is disrupted.

Sample XML

POST /feeds/api/users/USERNAME/live/events 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'>
  <title>Monster truck rally - Sunday June 26!</title>
  <summary>Sunday! Sunday! Sunday! Monster trucks at the county fairgrounds!</summary>
  <content type='application/atom+xml'>
    <entry>
      <yt:cdn name='primary'>
        <media:content yt:format='18'/>
        <media:content yt:format='19'/>
      </yt:cdn>
      <yt:cdn name='secondary'>
        <media:content yt:format='18'/>
        <media:content yt:format='19'/>
      </yt:cdn>
    </entry>
  </content>
  <yt:when start='2011-06-26T20:00:00.000Z'/>
</entry>

Updating a live event

You can update metadata for a live event or the live video stream associated with that event by submitting a PATCH request to the edit URL for the event. (In the event entry, this URL can be found in the <link> tag for which the rel attribute value is edit.)

https://gdata.youtube.com/feeds/api/users/USERNAME/live/events/EVENT_ID

You can update the title, description, and start time for an event. You can also update the CDN information for a video, by adding or removing streaming formats, for example. In addition, you can also update many of the video fields listed in the Updating a video entry section of the Developer's Guide.

The following sample request illustrates the XML format for modifying an event and its video.

PATCH /feeds/api/users/USERNAME/live/events/EVENT_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

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/' 
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    gd:fields='title,summary,yt:when,content/entry/yt:cdn'>
  <title>Monster Truck Rally - Monday, June 27</title>
  <summary>Moved to Monday! Monster trucks smash cars and burst into flame.</summary>
  <yt:when start='2011-06-27T20:00:00.000Z'/>
  <content type='application/atom+xml'>
    <entry>
      <yt:cdn name='primary'>
        <media:content yt:format='18'/>
      </yt:cdn>
    </entry>
  </content>
</entry>

Starting a live event

To indicate that a live event is starting, update the event and set the <yt:when> tag's start attribute to now as shown in the example below:

PATCH /feeds/api/users/USERNAME/live/events/EVENT_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

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/' 
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    gd:fields='yt:when'>
  <yt:when start='now'/>
</entry>

This update will also cause the event's status to change from pending to active.

Ending a live event

To indicate that a live event is ending, update the event and set the <yt:when> tag's end attribute to now as shown in the example below:

PATCH /feeds/api/users/USERNAME/live/events/EVENT_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

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:media='http://search.yahoo.com/mrss/' 
    xmlns:yt='http://gdata.youtube.com/schemas/2007'
    gd:fields='yt:when'>
  <yt:when end='now'/>
</entry>

This update will also cause the event's status to change from active to completed.

Deleting a live event

Deleting a live event removes the event altogether. The following sample API request demonstrates how to delete a live event:

DELETE /feeds/api/users/USERNAME/live/events/EVENT_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

Sample API response for adding or updating events

The sample XML entry below shows the format of an API response to a request to add or update a live event. The entry's <content> tag contains the live video entry, which indicates that the inline parameter would have been set to true in the corresponding API request.

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
       xmlns:app='http://www.w3.org/2007/app'
       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/"C0ICRn47eCp7ImA9WhZbEEU."'>
  <id>tag:youtube.com,2008:live:event:ABF128AfLanN-eatqP5dJAnnu0Xed0D_</id>
  <published>2011-06-14T19:59:27.000Z</published>
  <updated>2011-06-14T19:59:27.000Z</updated>
  <app:edited>2011-06-14T19:59:27.000Z</app:edited>
  <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#liveEvent'/>
  <title>Big Truck Rally - Sunday, August 2</title>
  <summary>Monster trucks are made out of metal. </summary>
  <content type='application/atom+xml'>
    <entry gd:etag='W/"C0ICRn47eCp7ImA9WhZbEEU."'>
      <id>SpQXZYILnN0</id>
      <published>2011-06-14T19:59:27.000Z</published>
      <updated>2011-06-14T19:59:27.000Z</updated>
      <app:edited>2011-06-14T19:59:27.000Z</app:edited>
      <app:control>
        <app:draft>yes</app:draft>
        <yt:state name='processing'/>
      </app:control>
      <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='Entertainment' label='Entertainment'/>
      <title>Big Truck Rally - Sunday, August 2</title>
      <link rel='alternate' type='text/html'
          href='http://www.youtube.com/watch?v=SpQXZYILnN0&feature=youtube_gdata'/>
      <link rel='http://gdata.youtube.com/schemas/2007#video.responses'
          type='application/atom+xml'
          href='https://gdata.youtube.com/feeds/api/videos/SpQXZYILnN0/responses?v=2'/>
      <link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
          type='application/atom+xml'
          href='https://gdata.youtube.com/feeds/api/videos/SpQXZYILnN0/ratings?v=2'/>
      <link rel='http://gdata.youtube.com/schemas/2007#video.complaints'
          type='application/atom+xml'
          href='https://gdata.youtube.com/feeds/api/videos/SpQXZYILnN0/complaints?v=2'/>
      <link rel='http://gdata.youtube.com/schemas/2007#video.related'
          type='application/atom+xml'
          href='https://gdata.youtube.com/feeds/api/videos/SpQXZYILnN0/related?v=2'/>
      <link rel='http://gdata.youtube.com/schemas/2007#video.captionTracks'
          type='application/atom+xml'
          href='https://gdata.youtube.com/feeds/api/videos/SpQXZYILnN0/captions?v=2' yt:hasEntries='false'/>
      <link rel='http://gdata.youtube.com/schemas/2007#insight.views'
          type='text/html' href='http://insight.youtube.com/video-analytics/...'/>
      <author>
        <name>ytatestuser</name>
        <uri>https://gdata.youtube.com/feeds/api/users/ytatestuser</uri>
      </author>
      <yt:accessControl action='comment' permission='allowed'/>
      <yt:accessControl action='commentVote' permission='allowed'/>
      <yt:accessControl action='videoRespond' permission='moderated'/>
      <yt:accessControl action='rate' permission='allowed'/>
      <yt:accessControl action='embed' permission='allowed'/>
      <yt:accessControl action='list' permission='allowed'/>
      <yt:accessControl action='syndicate' permission='allowed'/>
      <gd:comments>
        <gd:feedLink
            href='https://gdata.youtube.com/feeds/api/videos/SpQXZYILnN0/comments?v=2'
            countHint='0'/>
      </gd:comments>
      <media:group>
        <media:category label='Entertainment'
            scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>Entertainment</media:category>
        <media:content
            url='http://www.youtube.com/v/SpQXZYILnN0?f=videos&d=AYCLu96ijk1vhQNRODkbS5kO88HsQjpE1a8d1GxQnGDm&app=youtube_gdata'
            type='application/x-shockwave-flash' medium='video' isDefault='true'
            expression='full' duration='0' yt:format='5'/>
        <media:credit role='uploader'
            scheme='urn:youtube'>ytatestuser</media:credit>
        <media:description
            type='plain'>Monster trucks are made out of metal.</media:description>
        <media:keywords/>
        <media:player
            url='http://www.youtube.com/watch?v=SpQXZYILnN0&feature=youtube_gdata_player'/>
        <media:restriction type='country'
            relationship='deny'>FR DE SE</media:restriction>
        <media:thumbnail url='http://i.ytimg.com/vi/SpQXZYILnN0/default.jpg'
            height='90' width='120' time='00:00:00' yt:name='default'/>
        <media:thumbnail url='http://i.ytimg.com/vi/SpQXZYILnN0/hqdefault.jpg'
            height='360' width='480' yt:name='hqdefault'/>
        <media:thumbnail url='http://i.ytimg.com/vi/SpQXZYILnN0/1.jpg'
            height='90' width='120' time='00:00:00' yt:name='start'/>
        <media:thumbnail url='http://i.ytimg.com/vi/SpQXZYILnN0/2.jpg'
            height='90' width='120' time='00:00:00' yt:name='middle'/>
        <media:thumbnail url='http://i.ytimg.com/vi/SpQXZYILnN0/3.jpg'
            height='90' width='120' time='00:00:00' yt:name='end'/>
        <media:title type='plain'>Big Truck Rally - Sunday, August 2</media:title>
        <yt:duration seconds='0'/>
        <yt:uploaded>2011-06-1419:59:27.000Z</yt:uploaded>
        <yt:videoid>SpQXZYILnN0</yt:videoid>
      </media:group>
      <yt:cdn name='primary'>
        <media:content yt:format='19' yt:name='yt-live_SpQXZYILnN0_35'
            url='rtmp://rtmp1.youtube.com/videolive?...'/>
      </yt:cdn>
    </entry>
  </content>
  <link rel='http://gdata.youtube.com/schemas/2007#video'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/value%3A+%22SpQXZYILnN0%22%0A?v=2'/>
  <link rel='self'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events/ABF128AfLanN-eatqP5dJAnnu0Xed0D_?v=2'/>
  <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/ytatestuser/live/events/ABF128AfLanN-eatqP5dJAnnu0Xed0D_?v=2'/>
  <author>
    <name>ytatestuser</name>
    <uri>https://gdata.youtube.com/feeds/api/users/ytatestuser</uri>
  </author>
  <media:group>
    <media:description
        type='plain'>Monster trucks are made out of metal.</media:description>
    <media:title type='plain'>Big Truck Rally - Sunday, August 2</media:title>
  </media:group>
  <yt:status>pending</yt:status>
  <yt:when start='2011-08-02T20:00:00.000Z'/>
</entry>

Note that YouTube may use the <media:restriction> tag to identify countries where we do not support live video streams. As such, an API response might indicate that your live video cannot be viewed in certain countries even though you did not specify those restrictions when creating or updating your event.

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.

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='https://gdata.youtube.com/feeds/api/videos/VIDEO_ID/ratings'/>
  </entry>
</feed>

To add a rating to a video, send an authenticated 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 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 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='https://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='https://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b?v=2'/>
  <link rel='alternate' type='text/html'
    href='https://www.youtube.com/watch?v=ZTUVgYoeN_b'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://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='https://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='https://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?alt=atom-service&v=2'/>
  <link rel='next' type='application/atom+xml'
    href='https://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='https://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b?v=2'/>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/watch?v=ZTUVgYoeN_b'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments/F53EAC190E4EA5C9?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</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="https://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 a 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="https://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.

If a video was uploaded as a video response, then its video entry will contain a <link> tag that points to the video being responded to. The <link> tag's rel attribute will have a value of in-response-to as shown in the following example:

<link rel='http://gdata.youtube.com/schemas/2007#video.in-response-to'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/videos/HsQIoPyfQzM?v=2'/>

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="https://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 send a 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 a 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 a 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, send a 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 send a 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 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 a GET request to the following URL. Note: For this request, you must provide an authentication token, which enables YouTube to identify the user.

  https://gdata.youtube.com/feeds/api/users/default/favorites

• To request a feed of another user's favorite videos, send a GET request to the following URL. Note that this request does not require authentication.

  https://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 a POST request to https://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 a POST request to add each selected video as a favorite. Your application sends each request to https://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 a DELETE request to the edit URL for the video entry:

<link rel='edit' type='application/atom+xml'
   href='https://gdata.youtube.com/feeds/api/users/USERNAME/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 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/USERNAME/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 a 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 a GET request to the following URL. Note: For this request, you must provide an authentication token, which enables YouTube to identify the user.

  https://gdata.youtube.com/feeds/api/users/default/playlists?v=2

• To request a feed of another user's playlists, send a GET request to the following URL. Note that this request does not require authentication.

  https://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:GoogleDevelopers: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 GoogleDevelopers</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='related' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers?v=2'/>
  <link rel='alternate' type='text/html'
    href='https://www.youtube.com/profile_play_list?user=GoogleDevelopers'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists?alt=...'/>
  <author>
    <name>GoogleDevelopers</name>
    <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</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:GoogleDevelopers: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='https://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers?v=2'/>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/view_play_list?p=8BCDD04DE8F771B2'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists/8BCDD04DE8F771B2?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/playlists/8BCDD04DE8F771B2?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</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='https://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 a POST request to https://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 a POST request to https://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 a PUT request and the API URL must specify the ID of the playlist being updated.

PUT /feeds/api/users/USERNAME/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 a 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, include the <yt:position> tag in your request and set its value to the position where the video should appear in the playlist.

The following request provides the URL and illustrates the XML format for adding a video to the beginning of 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>
  <yt:position>1</yt:position>
</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 PUT request to the following URL, replacing PLAYLIST_ID and PLAYLIST_ENTRY_ID with the appropriate values:

https://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 a 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 a 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 a 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/USERNAME/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.

Retrieving and updating a user's 'Watch Later' playlist

YouTube's 'Watch Later' feature lets users save videos to watch at a later time. The 'Watch Later' list is stored as a playlist. However, that list is not included in a user's playlist feed.

You will be able to retrieve a user's watch_later playlist if either of the following conditions is true:

• You are submitting an authenticated request to retrieve the logged-in user's watch_later playlist. For this request, send a GET request to the following URL.

  https://gdata.youtube.com/feeds/api/users/default/watch_later?v=2

• The watch_later playlist that you are retrieving is publicly available. In this case, send a GET request to the following URL (after replacing the string username with the user's YouTube username):

  https://gdata.youtube.com/feeds/api/users/username/watch_later?v=2

Note: The watch_later playlist is only accessible through API version 2 or greater.

By default, the watch_later playlist is an empty, private playlist. To determine whether a user's watch_later playlist is accessible or if it has entries, retrieve the user's profile and check for the presence of a <gd:feedLink> tag with a rel attribute value of http://gdata.youtube.com/schemas/2007#user.watchlater.

If the tag is present, then you can access the user's watch_later playlist via the API using the same authentication credentials as you used to retrieve the user's playlist. The tag's href attribute will specify the feed URL for the user's watch_later playlist, and its countHint attribute specifies the number of videos in that list. A sample tag is shown below:

<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.watchlater'
    href='https://gdata.youtube.com/feeds/api/users/username/watch_later?v=2'
    countHint='17'/>

Again, the link will only be present in a profile entry if either of the following conditions is true:

• You submit an authenticated request to retrieve the logged-in user's own profile.

• The watch_later playlist is publicly available for the user whose profile you are retrieving.

The API server will return a 40x HTTP response code if you try to retrieve a watch_later playlist and neither of the above conditions is true.

The API supports the same operations for adding, updating, and deleting videos in the watch_later playlist as for any other playlist, and the list below shows the API URLs to use for those operations. These requests are only supported for authenticated users who are updating their own watch_later playlist.

• Adding a video to the playlist:
  https://gdata.youtube.com/feeds/api/users/default/watch_later.

• Updating the position of a playlist entry:
  https://gdata.youtube.com/feeds/api/users/default/watch_later/<VIDEO_ID>.

• Deleting a video from the playlist:
  https://gdata.youtube.com/feeds/api/users/default/watch_later/<VIDEO_ID>.

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 a GET request to the following URL. Note: For this request, you must provide an authentication token, which enables YouTube to identify the user.

  https://gdata.youtube.com/feeds/api/users/default/subscriptions?v=2

• To request a feed of another user's subscriptions, send a GET request to the following URL. Note that this request does not require authentication.

  https://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='