YouTube

YouTube API v2.0

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.

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, upload videos to YouTube, and update existing videos. Your application can also retrieve playlists, subscriptions, favorite videos, and more. Finally, your application can submit authorized requests to enable users to create playlists and subscriptions, rate videos, add favorite videos, and perform other account-specific actions.

Contents

  1. Audience
    1. About this documentation
    2. Supported API feeds
    3. Handling usernames and display names in your application
    4. API versioning
      1. Comparing API versions 2 and 2.1
  2. Authentication and authorization
    1. Using a developer key
    2. OAuth 2.0
      1. Register your application with Google
      2. OAuth 2.0 flows
        1. Server-side web applications
        2. Client-side web applications
        3. Installed applications
        4. Devices
      3. Calling the YouTube Data API
        1. Refreshing an access token
      4. Client libraries
    3. Authorizing requests from Flash applications
  3. Understanding video feeds and entries
    1. Displaying a list of videos
    2. Identifying feeds related to a feed entry
    3. Displaying information about a video
  4. Retrieving and searching for videos
    1. Standard video feeds
      1. Retrieving region-specific standard video feeds
      2. Retrieving category-specific standard video feeds
    2. Videos uploaded by a specific user
    3. Related videos
    4. Browsing with categories and keywords
    5. Searching for videos
      1. Standard Google Data API query parameters
      2. Custom query parameters for the YouTube Data API
    6. Retrieving information about a single video
  5. Retrieving and searching for channels
    1. Searching for channels
    2. Standard feeds for channels
  6. Searching for playlists
  7. Uploading videos
    1. Technical requirements for uploaded videos
    2. Setting access controls for a video
    3. Assigning developer tags
    4. Browser-based uploading
      1. Step 1 - Uploading video metadata
        1. Variables in the upload request
      2. Step 2 - Extracting values from the API response
      3. Step 3 - Uploading the video file
      4. Process Flow Diagram
    5. Direct uploading
      1. Sending an Upload API Request
        1. Variables in the upload request
      2. Handling the Upload API Response
      3. Process Flow Diagram
    6. Resumable uploads
      1. Step 1 - Uploading video metadata
        1. Variables in the upload request
      2. Step 2 - Extracting the upload URL from the API response
      3. Step 3 - Uploading the video file
        1. Variables in the upload request
      4. Step 4 - Completing the upload process
        1. Checking the status of a resumable upload
        2. Resuming an upload
    7. Checking the status of an uploaded video
  8. Updating and deleting videos
    1. Updating a video entry
      1. Updating a video with incomplete metadata
    2. Deleting a video
    3. Providing captions for a video
      1. Requirements for caption operations
      2. Supported formats for caption files
      3. Retrieving a list of available caption tracks
      4. Creating a caption track
      5. Retrieving a caption track
      6. Updating a caption track
      7. Deleting a caption track
  9. Movies, trailers, and shows
    1. Movies and trailers
    2. Shows, seasons, and episodes
  10. YouTube EDU
    1. Categories
    2. Courses
    3. Lectures
  1. Using community features
    1. Ratings
    2. Comments
      1. Retrieving comments for a video
      2. Adding a comment in response to a video
      3. Adding a comment in reply to another comment
      4. Deleting a comment
    3. Adding a complaint
  2. Saving and collecting videos
    1. Favorite videos
      1. Retrieving a user's favorite videos
      2. Adding a favorite video
      3. Deleting a favorite video
    2. Playlists
      1. Retrieving a user's playlists
      2. Retrieving a single playlist
      3. Adding a playlist
      4. Updating a playlist
        1. Adding a video to a playlist
        2. Editing video information in a playlist
        3. Removing a video from a playlist
      5. Deleting a playlist
      6. Retrieving and updating a user's 'Watch Later' playlist
    3. Subscriptions
      1. Retrieving a user's subscriptions
      2. Retrieving new subscription videos
      3. Adding a subscription
      4. Deleting a subscription
    4. Channel suggestions
    5. Video recommendations
    6. Watch history feed
      1. Deleting videos from the watch history feed
  3. Enabling user interaction
    1. User profiles
      1. Retrieving a user's profile
      2. Associating an unlinked Google Account with a YouTube channel
    2. Contacts
      1. Retrieving a user's contacts
      2. Adding a contact
      3. Updating a contact
      4. Deleting a contact
    3. Messages and video sharing
      1. Retrieving messages from a user's inbox
      2. Sending a video message
      3. Deleting a message
    4. Activity feeds
      1. Retrieving an activity feed
      2. Sample activity feed
      3. Subscription activity (subtivity) feeds
      4. User activity feeds
      5. Retrieving additional metadata for activity feed entries
  4. Monitoring activity feeds with SUP
    1. Understanding the SUP feed format
    2. Retrieving YouTube's SUP feed
    3. Discovering hash keys for activity feeds
    4. SUP in action
  5. Using batch processing with the YouTube Data API
    1. Submitting a batch processing request
      1. Batch processing guidelines
      2. Sample batch processing request
    2. Handling the API response for a batch processing request
      1. Tracking operations in a batch processing request
      2. Identifying interrupted batch processing
  6. Retrieving a partial response
    1. Submitting a request for a partial feed response
    2. Handling a partial feed response
  7. Submitting partial update (PATCH) requests
    1. Submitting a partial update request
      1. Formatting a partial update request
        1. Changing access controls with partial updates
      2. Alternate notation for applications that do not handle PATCH method
    2. Handling the response to a partial feed update
      1. Error handling for partial update (PATCH) requests
  8. Testing and troubleshooting
    1. Using the Interactive API Demo
    2. Using the staging server
    3. Troubleshooting common API challenges
      1. Filtering API responses
      2. Calculating the content-length for direct upload requests
      3. Identifying a video for a particular operation
      4. Uploading private videos
      5. Caching video metadata to avoid quota issues
      6. Uploading a large batch of videos
  9. Retrieving Insight data
  10. Understanding API error responses
    1. Validation errors
    2. Quota errors
    3. Authentication and authorization errors
    4. Service errors
  11. Revision History

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 and authorization section describes the different ways you can associate an API operation with a specific user account. Throughout this documentation, explanations of specific API functions will clearly indicate whether the function requires user authorization.

  • 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, such as a list of videos uploaded by a specific user or a list of YouTube's most popular videos. This section also 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 authorization scheme that you are using.

  • 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, or complaint to an existing video. You can also use the API to retrieve lists of video comments.

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

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.
    • The feed of YouTube's most popular videos is a standard feed that can be filtered to only include popular videos for a region or category. Movie charts are standard feeds that only contain videos that appear in YouTube's Movies category.
    • 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 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.

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

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

Handling usernames and display names in your application

The API uses several different elements to identify users. With that in mind, the following rules explain how to properly handle usernames and display names in your application:

  • 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. For example, the URL https://gdata.youtube.com/feeds/api/users/default?v=2 will retrieve the currently authenticated user's profile.

  • If you need to manually generate a feed URL that is not for the currently authenticated user, we recommend that you use the value of the <yt:userId> tag as the username in the feed URL. For backward compatibility purposes, you can also use the <yt:username> tag's value as the username in the feed URL. However, going forward, you should use the <yt:userId> value to uniquely identify a user.

    The <yt:userId> tag always contains a globally unique identifier that is not intended for display. The <yt:username> tag, on the other hand, could contain either the same globally unique identifier or a traditional YouTube username, which also serves as a channel name. Both elements are included in user profile entries, subscription feed entries, and numerous other feeds.

  • If your code displays a username, use the value of the <yt:username> tag's display attribute as the display value. That value will always be a meaningful value that is suitable for display.

    • For a YouTube account that is connected to a Google+ profile, the display attribute value will be set to the user's full public display name.
    • For accounts that are not connected to Google+, the display value will be set to the YouTube account name.

    The <name> tag, which appears inside the <author> tag, also contains the correct value to display for a user in a user interface. Like the <yt:username> tag value, the <name> tag value is not intended to uniquely identify the user.

  • In cases where the <media:credit> tag identifies the YouTube user that uploaded a video, that tag will also have a yt:display attribute that specifies the appropriate name to display for that user, while the tag's value will uniquely identify the user.

    When the <media:credit> tag communicates other information, such as the name of an actor or director associated with a video, the tag will specify a value for display.

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

    • 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 authorization. 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 authorized Google Accounts and should return an HTTP 200 response code for API requests related to these features:

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

Authentication and authorization protocols allow a user to access YouTube features that link content or information to a particular YouTube account.

  • Authentication pertains to the idea of user identity. So, for example, a user authenticates when entering an account username and password.

  • Authorization refers to the ability to retrieve, insert, update, and delete data. An authenticated user can authorize a third-party application to perform API operations on that user's behalf.

The API supports numerous functions that require user authorization, including all of the API functions for creating, updating or deleting content. For example, suppose an application allows users to capture videos and upload them to YouTube. To upload a video through the application, a user would need to authenticate by logging into a Google Account and then authorize the application to upload videos to the user's account.

Note: If you implement any functionality that requires user authorization, we recommend that you include the proper authorization headers in all of your API requests even if those requests do not explicitly require user authorization.

A request must include the following information to be properly authorized:

  • An Authorization header that specifies a token that you obtain for each user.

  • The X-GData-Key header or the key parameter, which specifies your developer key, a value that uniquely identifies your application(s). Using the X-GData-Key header is the preferred approach since it is more secure than the URL parameter.

We recommend that you use OAuth 2.0 authorization for your application, and the sample API requests throughout this documentation use the OAuth 2.0 syntax for their Authorization HTTP header values. The OAuth 2.0 protocol provides a standard way to access protected data on different websites and it is the recommended authorization mechanism for Google APIs. OAuth is an open protocol that may be implemented for many APIs, including Google APIs. All Google APIs, including the YouTube API, support the OAuth 2.0 authorization protocol. OAuth 2.0 relies on SSL for security instead of requiring your application to do cryptographic signing directly.

The OAuth 1.0, AuthSub, and ClientLogin authorization schemes also still work with the YouTube API. The APIs for those schemes have all been officially deprecated as of April 20, 2012. They will continue to work as per our deprecation policy, but we encourage you to migrate to OAuth 2.0 authorization as soon as possible. Similarly, if you are building a new application, you should use OAuth 2.0 authorization.

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. The first option provides greater security and is the recommended approach.

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

Obtain authorization credentials

Your application must have authorization credentials to be able to use the YouTube Data API. You can obtain credentials through the Google Developers Console by following the instructions for the instructions for the most recent YouTube Data API version (v3).

The Developers Console associates your credentials with the APIs that you indicate that your application will use. Note that the Developers Console does not allow you to select the YouTube Data API (v2). However, authorization credentials for the v3 API will also work for the v2 API.

If possible, you should actually use YouTube Data API (v3) rather than the v2 API in your application. The YouTube API blog explains some of the benefits that the newer API offers, and we have added a year's worth of additional functionality to the API since that blog post!

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. Obtain an access token

    Note: Requests to Google's authorization server must use https instead of http because the server is only accessible over SSL (HTTPs) and will refuse HTTP connections.

    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. 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 Optional. This parameter indicates whether the user should be prompted to grant account access to your application each time she 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 she tried to access a protected resource.

    Set the parameter value to force to direct the user to a consent page even if she has already granted access to your application for a particular set of scopes.
    access_type Recommended. This parameter indicates whether your application can refresh access tokens when the user is not present at the browser. Valid parameter values are online and offline. Set this parameter value to offline to allow the application to refresh access tokens when the user is not present. (This is the method of refreshing access tokens described later in this document.)
    state Optional. 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. User decides whether to grant access to your application

    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. Google redirects user to your application

    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. Exchange authorization code for refresh and access tokens

    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 Developers 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. Process response and store tokens

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

    Important: Your application should store both values.

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. Obtain an access token

    Note: Requests to Google's authorization server must use https instead of http because the server is only accessible over SSL (HTTPs) and will refuse HTTP connections.

    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. 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 Optional. This parameter indicates whether the user should be prompted to grant account access to your application each time she 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 she tried to access a protected resource.

    Set the parameter value to force to direct the user to a consent page even if she 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. User decides whether to grant access to your application

    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. Google redirects user to your application

    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, the 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. Validate the user's token

    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. Process the token validation response

    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 Developers 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, refer to the OAuth 2.0 instructions for devices by clicking the Devices tab above.

The following steps explain this flow:

  1. Register your application as an installed application

    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. Obtain an access token

    Note: Requests to Google's authorization server must use https instead of http because the server is only accessible over SSL (HTTPs) and will refuse HTTP connections.

    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. 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 Developers 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 needs 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. See step 4 for specific instructions for parsing the token from the page title.

    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.
    state Optional. 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. User decides whether to grant access to your application

    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 2. 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. Google redirects user to your application

    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.

      To extract the token, your application should assume that everything that follows the last space character in the page title is a parameter string in the format x=a&y=b. Your code should parse the parameters from that substring, looking for a code= or error= assignment to indicate that the page contains the final title string and the sign-in flow is complete. If the page title assigns a value to the code parameter, then that value is the token. However, your application should not make assumptions about the token length or the number of parameters in the parameter string.

      For example, the screenshot below shows a page with the following attributes:

      • Page title: Success code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • Parameter string: code=4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu
      • Authorization token: 4/v6xr77ewYqhvHSyW6UJ1w7jKwAzu

  5. Exchange authorization code for refresh and access tokens

    Assuming the user has granted access to your application, exchange the authorization code obtained in step 4 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 4.
    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 Developers 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. Process response and store tokens

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

    Important:Your application should store both values.

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. Embed your client_id and client_secret in your application

    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. Request a device code

    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. Handle the response

    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. Begin polling Google's authorization server

    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 Developers 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. User enters user_code in separate browser

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

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

  6. User logs in to Google Account that will be used on your device

    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. User decides whether to grant access to your application

    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. Process response from polling server to obtain tokens

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

    Important: Your application should store both values.

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. The first option provides greater security and is the recommended approach.

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

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.

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.

Authorizing 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 authorized 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: Bearer ACCESS_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.com,2008:standardfeed:global:most_popular</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>Most Popular</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/most_popular?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/standardfeeds/most_popular/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/standardfeeds/most_popular?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/standardfeeds/most_popular?...'/>
  <link rel='next' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/standardfeeds/most_popular?...'/>
  <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='http://gdata.youtube.com/schemas/2007#uploader'
      type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw?v=2'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/standardfeeds/most_popular/v/ZTUVgYoeN_b?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
      <yt:userId>_x5XG1OV2P6uZZ5FSM9Ttw<</yt:userId>
    </author>
    <yt:accessControl action='comment' permission='allowed'/>
    <yt:accessControl action='commentVote' permission='allowed'/>
    <yt:accessControl action='rate' permission='allowed'/>
    <yt:accessControl action='embed' permission='allowed'/>
    <yt:accessControl action='list' permission='allowed'/>
    <yt:accessControl action='autoPlay' permission='allowed'/>
    <yt:accessControl action='syndicate' permission='allowed'/>
    <gd:comments>
      <gd:feedLink href='https://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments'
        countHint='9416'/>
    </gd:comments>
    <georss:where>
      <gml:Point>
        <gml:pos>21.37124437061831 -157.87353515625</gml:pos>
      </gml:Point>
    </georss:where>
    <yt:hd/>
    <media:group>
      <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:credit role='uploader' scheme='urn:youtube'
          yt:display='GoogleDevelopers'>GoogleDevelopers</media:credit>
      <media:description type='plain'>
        What could make for more exciting video?
      </media:description>
      <media:keywords>Shopping, parkas</media:keywords>
      <media:license type='text/html' href='http://www.youtube.com/t/terms'>youtube</media:license>
      <media:player url='https://www.youtube.com/watch?v=ZTUVgYoeN_b'/>
      <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:title type='plain'>Shopping for Coats</media:title>
      <yt:aspectRatio>widescreen</yt:aspectRatio>
      <yt:duration seconds='79'/>
      <yt:uploaded>2008-07-05T19:56:35.000-07:00</yt:uploaded>
      <yt:uploaderId>UC_x5XG1OV2P6uZZ5FSM9Ttw</yt:uploaderId>
      <yt:videoid>ZTUVgYoeN_b</yt:videoid>
    </media:group>
    <gd:rating min='1' max='5' numRaters='14763' average='4.93'/>
    <yt:recorded>2008-07-04</yt:recorded>
    <yt:statistics viewCount='383290' favoriteCount='7022'/>
    <yt:rating numDislikes='19257' numLikes='106000'/>
  </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 could select other text appropriate to the requested feed or search result set.

  2. In this text, the number 15 would be taken from 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.

    If you wanted to also identify which items from the feed were being displayed – e.g. items 1 to 10 – you would also use the values of the <openSearch:startIndex> and <openSearch:itemsPerPage> tags.

  3. The Sort by menu lets the user select a value for the orderby query parameter. A pulldown menu showing how results are sorted also appears on the right side of the image, below the result count.

    The Filter options let the user set values for a number of other search parameters, including the time, 3d, caption, duration, hd, license, paid-content, and uploader parameters. It also displays options to display either channel or playlist search results.

    The API Query Parameters section 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 sorting menu also lets the user select a value for the orderby query parameter.

  5. 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. The video duration also displays in the bottom right corner of the thumbnail image. The <yt:duration> specifies this value.

    On the YouTube website, the thumbnail image links to the watch page for the video. That page displays more information about the video as well as comments and rating information. 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. You could also use the video's <yt:videoid> to construct the URL or to play the video using an embedded (or chromeless) YouTube player.

  6. The title next to the thumbnail image is the value of the <media:title> tag for that video.

  7. The snippet below the title shows parts of the video description, which is the value of the <media:description> tag.

  8. The text and buttons below the video description show values from a number of tags:

    • The byline, which identifies the video uploader, shows the value of the <name> tag.
    • The time indicated in each result is calculated based on the value of the <published> tag for the video.
    • The view count is taken from the <yt:statistics> tag's viewCount attribute.
    • In the third result, the HD text indicates that the <yt:hd> is in the video entry.

To retrieve a feed entry for a single video in the result set, send a GET request to the edit URL for that entry, as explained in the following section. For example, you might issue this request if the user links from a set of search results to a video watch page that only displays information about the selected video.

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 or add ratings of the video. Some URLs may be used for more than one function. 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.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 in a <link> or <gd:feedLink> 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 related videos for a video, you send a GET request to the URL associated with the <link> tag with the rel attribute value http://gdata.youtube.com/schemas/2007#video.related. To add a rating to a video, you 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. And to retrieve or post comments to a video, you send a request to the URL specified by the <gd:feedLink> tag that the <gd:comments> tag contains.

Displaying information about a video

The annotated screenshot below shows a YouTube video watch page, which primarily displays information about a single video. The list following the screenshot explains how to use the YouTube API to retrieve the information. Note that you would need to synthesize content from several API responses to reproduce this page using the API.

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. As shown above, this page also includes information from the video's comments feed and related videos feed. In addition, the pulldown menu below the video title shows information from the video owner's uploaded videos feed.

The screenshot displays the following information:

  1. This item shows the title of the video. In a video entry, the <media:title> tag contains the video's title.

  2. The Subscribe button next to the video owner's name (or channel icon) allows a user to subscribe to the video owner's activity feed.

    The pulldown menu next to the button shows information from the video owner's uploaded videos feed. The pulldown shows the number of videos that the video owner has uploaded. This value is specified in the <openSearch:totalResults> tag.

    When a user clicks on the pulldown, the pane shown below appears, displaying other videos uploaded by the video owner. Each video corresponds to an entry in the uploaded videos feed. For each video, the pane shows a thumbnail image (<media:thumbnail>), the video duration (<yt:duration>), the video title (<media:title>, the video owner (<name>), and the video's view count (<yt:statistics>).

  3. This item shows a video player. The Embedded player parameters document explains how to customize a YouTube embedded player in your own application. In addition, the <iframe> Player API Reference, the ActionScript 3.0 Player API Reference, and the JavaScript Player API Reference all explain how to build a chromeless player that uses your own custom controls.

  4. This section displays the video's upload date (<published>), description (<media:description>), view count (<yt:statistics>), and rating (<gd:rating>).

    This section also displays buttons for the user to rate the video, add the video to a playlist or "watch later" list, mark the video as a favorite, or flag the video for inappropriate content.

  5. This section displays a list of comments for the video. In the video entry, the <gd:feedLink> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007#comments specifies the number of comments on the video as well as the URL for the video's comments feed. You would need to retrieve that feed to actually display the comments.

  6. This section 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

Note: All standard video feeds except the most_popular feed have been deprecated. In response to requests for other feeds, the API will return the most_popular feed with a default time parameter value of today. In addition, if your request for another feed specifies a region or category, the API will return the most_popular feed for that region or category.

A standard feed contains a list of videos that either reflect YouTube user behavior. The only standard feed that the API still supports is the most_popular feed, which contains the most popular YouTube videos, selected using an algorithm that combines many different signals to determine overall popularity.

The most_popular feed supports the time query parameter, which can be set to either today or all_time. The feeds are updated periodically, but the feed that captures daily results may be updated more frequently. If you request a deprecated feed, and your request sets the time parameter value to all_time, the API will return a feed of YouTube's most popular videos of all time. Otherwise, the API will return the feed of the most popular videos for the past day.

To retrieve the most_popular feed, send a GET request to the following URL:

https://gdata.youtube.com/feeds/api/standardfeeds/most_popular

Note: The top_rated, top_favorites, most_shared, most_recent, most_discussed, most_responded, recently_featured, on_the_web, and most_viewed feeds have all been deprecated. The most_viewed feed was deprecated on July 23, 2012, and the remaining feeds were deprecated on September 12, 2013.

Retrieving region-specific standard video feeds

You can retrieve a region-specific version of the most_popular standard feed by inserting a region ID in the feed URL as shown below:

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

Note: If you request a deprecated standard feed, but your request specifies a region, the API will return the most_popular feed for that region.

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

Country Region ID
Argentina AR
Australia AU
Austria AT
Belgium BE
Brazil BR
Canada CA
Chile CL
Colombia CO
Czech Republic CZ
Egypt EG
France FR
Germany DE
Great Britain GB
Hong Kong HK
Hungary HU
India IN
Ireland IE
Israel IL
Italy IT
Japan JP
Country Region ID
Jordan JO
Malaysia MY
Mexico MX
Morocco MA
Netherlands NL
New Zealand NZ
Peru PE
Philippines PH
Poland PL
Russia RU
Saudi Arabia SA
Singapore SG
South Africa ZA
South Korea KR
Spain ES
Sweden SE
Switzerland CH
Taiwan TW
United Arab Emirates AE
United States US

Retrieving category-specific standard video feeds

You can retrieve a category-specific version of the most_popular standard feed by appending an underscore and a category name to the feed URL as shown below:

https://gdata.youtube.com/feeds/api/standardfeeds/regionID/most_popular_CATEGORY_NAME?v=2

If you request a deprecated standard feed, but your request specifies a category, the API will return the most_popular feed for that category.

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 most popular entertainment videos in France:
    https://gdata.youtube.com/feeds/api/standardfeeds/FR/most_popular_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 most_popular 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 most popular nonprofit videos in the United States because "Nonprofit" is a browsable category in the United States. However, you cannot request the most popular 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. You should not include search parameters in requests to retrieve an uploaded videos feed. The parameters will generate a feed from YouTube's search index, effectively restricting the result set to indexed, public videos, rather than returning a complete list of the user's uploaded videos.

  • To request a feed of all videos uploaded by the currently logged-in user, send a GET request to the following URL. This request requires 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 URL, the value default 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 is also used to identify the currently logged-in user in other API commands.

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

    https://gdata.youtube.com/feeds/api/users/userId/uploads

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead. You can extract the user ID from the <yt:userId> tag and the username from either the <name> or the <yt:username> tag in an API response. The XML excerpt below shows both values:

    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
      <yt:userId>_x5XG1OV2P6uZZ5FSM9Ttw<</yt:userId>
    </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.

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.

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 "Most Popular" 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, and if the specified author does not have any of YouTube's most popular videos, the feed will be empty.

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.
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:
hl
movie-genre
paid-content
region

Additional parameters for show charts:
genre
region

Additional parameters for YouTube EDU feeds:
category
course

Additional parameters for live event feeds: (deprecated)
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, though there are several exceptions listed above. The API also supports the time parameter for the most_popular standard video feed, 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.

In particular, you should not include search parameters in requests to retrieve an uploaded videos feed. By doing so, you are instructing the API to generate a feed from YouTube's search index, effectively restricting the result set to indexed, public videos rather than retrieving a complete list of the user's uploaded videos.

The following table defines the API's custom search 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 has two uses:
  • In video search requests, it 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.

  • In requests to retrieve YouTube EDU content, it specifies the YouTube EDU category that courses or lectures must be associated with to be included in the API response.

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.
course The course parameter lets you retrieve a list of lectures (videos) associated with the specified course. The parameter's value is a YouTube playlist ID that uniquely identifies a course that is accessible via YouTube EDU.
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
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

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.
ends-before
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

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.
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.
genre The genre parameter restricts a show chart to only include shows 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 – Classic TV
  • 4 – Comedy
  • 5 – Drama
  • 6 – Home & Garden
  • 7 – News
  • 8 – Reality & Game Shows
  • 9 – Science & Tech
  • 10 – Science Fiction
  • 11 – Soaps
  • 13 – Sports
  • 14 – Travel
  • 16 – Entertainment
  • 17 – Documentary
  • 20 – Nature
  • 21 – Beauty & Fashion
  • 23 – Food
  • 24 – Gaming
  • 25 – Health & Fitness
  • 26 – Learning & Education
  • 27 – Foreign Language

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 Deprecated. The hint parameter, which is now deprecated, was specified in a request to retrieve a list of unused YouTube channel names similar to that hint.
hl The hl parameter specifies the primary language of the movies in a movie chart. The parameter value is an ISO 639-1 two-letter language code.
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.
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 Not working. This API parameter is temporarily disabled. See the API issue tracker for more information.

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 Not working. This API parameter is temporarily disabled. See the API issue tracker for more information.

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.
    • reversedPosition – Entries are ordered in reverse of their position in the playlist.
    • 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.
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 or show 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 lets the API server apply country restrictions that are based on the end user's location for videos that can only be played in specific countries. The parameter value identifies the end user's IP address to the API server. We recommend that you always use this parameter to specify the end user's IP address. However, it is particularly important to set this parameter when a server or middle layer in your application stack uses the API on the end user's behalf and also sends all of the API requests on the user's behalf. This case usually applies to website applications that use the API.

If you do not set the restriction parameter value, then the API server might apply country restrictions incorrectly. For example, it might base restrictions on your middle-layer server's location rather than on the end user's actual location. Note that the API's Terms of Service prohibit lying about an end user's location to circumvent these restrictions.

There are two ways to use this parameter:
  • To request videos playable from a specific IP address, 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, 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
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

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.
starts-before
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

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.
status
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

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.
time The time parameter is supported for search feeds and the most_popular standard video feed. 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, 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 all_time in a request for the most_popular standard video feed, the feed will contain the most popular videos on YouTube based on a number of different popularity signals.

    This parameter is supported for the following feeds and charts:
    • most_popular standard video feed – This feed only supports the parameter values today and all_time.
    • Standard channel feeds
      • most_subscribed – This feed only supports the parameter values this_week, this_month, and all_time.
      • most_viewed
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:display='partner_name'
  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 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, send an authenticated GET request to 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/videoid?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:

  1. Searching for channels
  2. Standard feeds 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:

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>
      <yt:userId>k1pcWQ5E19g0Cgp4c1eI1w</yt:userId>
    </author>
    <yt:channelId>UCk1pcWQ5E19g0Cgp4c1eI1w</yt:userId>
    <yt:channelStatistics subscriberCount='29317' viewCount='1737927'/>
    <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'/>
    <media:thumbnail url='http://i.ytimg.com/i/k1pcWQ5E19g0Cgp4c1eI1w/1.jpg'/>
  </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:

Name Feed Id URL and Description
Most viewed most_viewed URL: https://gdata.youtube.com/feeds/api/channelstandardfeeds/most_viewed?v=2
Description: This feed lists the most frequently watched YouTube channels. This metric accounts for all views of videos uploaded to a channel.
Most subscribed most_subscribed URL: https://gdata.youtube.com/feeds/api/channelstandardfeeds/most_subscribed?v=2
Description: This feed lists the channels with the most subscribers or the most new subscribers during a given time period.

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>
    <yt:userId>QlGBspQdj17WOPBQMT1k9A</yt:userId>
  </author>
  <yt:channelId>UCQlGBspQdj17WOPBQMT1k9A</yt:channelId>
  <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:

Note: The q parameter value can contain multiple words, and it 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 "GoogleDevelopers":

https://gdata.youtube.com/feeds/api/playlists/snippets?
    q=GoogleDevelopers
    &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: GoogleDevelopers</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#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=GoogleDevelopers&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=GoogleDevelopers&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>5590</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/"D0ANRn47eCp7ImA9WxVUF04."'>
    <id>tag:youtube.com,2008:playlist:snippet: PL5D286BD1D14EAF40</id>
    <published>2008-05-26T23:39:53.000Z</published>
    <updated>2009-03-21T12:45:57.000Z</updated>
    <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/>
    <content type='application/atom+xml;type=feed' src='https://gdata.youtube.com/feeds/api/playlists/PL5D286BD1D14EAF40?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= PL5D286BD1D14EAF40'/>
    <link rel='self' type='application/atom+xml' href='https://gdata.youtube.com/feeds/api/playlists/snippets/PL5D286BD1D14EAF40?v=2'/>
    <link rel='edit' type='application/atom+xml' href='https://gdata.youtube.com/feeds/api/playlists/snippets/PL5D286BD1D14EAF40?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
    </author>
    <yt:countHint>4</yt:countHint>
    <media:group>
      <media:thumbnail url="http://i.ytimg.com/vi/OOE9l23P7jg/default.jpg" height="90" width="120" yt:name="default"/>
      <media:thumbnail url="http://i.ytimg.com/vi/OOE9l23P7jg/mqdefault.jpg" height="180" width="320" yt:name="mqdefault"/>
      <media:thumbnail url="http://i.ytimg.com/vi/OOE9l23P7jg/hqdefault.jpg" height="360" width="480" yt:name="hqdefault"/>
    </media:group>
    <yt:playlistId> PL5D286BD1D14EAF40</yt:playlistId>
  </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:

  1. Technical requirements for uploaded videos
  2. Setting access controls for a video
  3. Assigning developer tags
  4. Browser-based uploading
  5. Direct uploading
  6. Resumable uploads
  7. Checking the status of an uploaded video

Technical requirements for uploaded videos

You must be either the copyright holder or the authorized representative of the copyright owner for all video files that you deliver to YouTube. Similarly, users who upload videos to YouTube from your site must be either the copyright holder or the authorized representative of the copyright owner for all videos that they upload.

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: Bearer ACCESS_TOKEN
    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 users can rate comments about the video.
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='rate' 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.

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. When choosing values to use for developer tags, remember that developer tag searches are not case-sensitive. In addition, 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. Developer tag searches are not case-sensitive. 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 OAuth 2.0 authentication scheme for browser-based uploading:

POST /action/GetUploadToken HTTP/1.1
Host: gdata.youtube.com
Authorization: Bearer ACCESS_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:

  • ACCESS_TOKEN - This value contains the authentication token for your request. The token will either be an OAuth 2.0 access token, an OAuth 1.0 access token, a ClientLogin token, an AuthSub single-use token, or an AuthSub session 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 with the exception of the access (authentication) token:

POST /action/GetUploadToken HTTP/1.1
Host: gdata.youtube.com
Authorization: Bearer ACCESS_TOKEN
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.

Process Flow Diagram

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 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/default/uploads. Your request will upload the 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: Bearer ACCESS_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--

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.

  • ACCESS_TOKEN - This value contains the authentication token for your request. The token will either be an OAuth 2.0 access token, an OAuth 1.0 access token, a ClientLogin token, an AuthSub single-use token, or an AuthSub session 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 access (authentication) token and the binary file data:

POST /feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: Bearer ACCESS_TOKEN
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.

Process Flow Diagram

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.

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. The authentication token that you submit with the request needs to identify the currently logged-in user. 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

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

POST /resumable/feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: Bearer ACCESS_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:

  • ACCESS_TOKEN - This value contains the authentication token for your request. The token will either be an OAuth 2.0 access token, an OAuth 1.0 access token, a ClientLogin token, an AuthSub single-use token, or an AuthSub session 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 with the exception of the access (authentication) token:

POST /resumable/feeds/api/users/default/uploads HTTP/1.1
Host: uploads.gdata.youtube.com
Authorization: Bearer ACCESS_TOKEN
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: Bearer ACCESS_TOKEN
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_length>

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

    1. Checking the current status of an upload
    2. 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/default/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/default/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 (*).

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/default/uploads/VIDEO_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_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="rate" permission="allowed"/>
  <yt:accessControl action="list" permission="allowed"/>
  <yt:accessControl action="embed" permission="allowed"/>
  <yt:accessControl action="syndicate" permission="allowed"/>
</entry>

Note: You can also submit a partial update using a PATCH request to only update specific metadata fields for an 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/default/uploads/VIDEO_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_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:

  1. Requirements for caption operations
  2. Supported formats for caption files
  3. Retrieving a list of available caption tracks
  4. Creating a caption track
  5. Retrieving a caption track
  6. Updating a caption track
  7. Deleting a caption track

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: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

<Caption File Data>

Uploading a video transcript without caption timecodes

If YouTube's Timed Text Service (TTS) 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: Bearer ACCESS_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:

  1. Retrieving a translation of a caption track
  2. Retrieving a caption track in an alternate format

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: Bearer ACCESS_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: Bearer ACCESS_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: Bearer ACCESS_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: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

Movies, trailers, and shows

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 charts, which are standard feeds that only contain videos that appear in YouTube's Movies category.

The following subsections explain the special metadata fields included in movie and trailer entries as well as the movie 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:

Chart name Feed ID URL and Description
Featured movies featured URL: https://gdata.youtube.com/feeds/api/charts/movies/featured?region=US
Description: This feed lists movies that are featured on the YouTube Movies category home page or in the Google Play Store. This feed will be empty if you do not specify a value for the region parameter. In addition, this feed does not support the movie-genre parameter.
Most popular movies most_popular URL: https://gdata.youtube.com/feeds/api/charts/movies/most_popular?region=US
Description: This feed lists the most popular videos in YouTube's Movies category.
Most recent movies most_recent URL: https://gdata.youtube.com/feeds/api/charts/movies/most_recent?region=US
Description: This feed lists videos that were recently added to YouTube's Movies category.
Trending movies trending URL: https://gdata.youtube.com/feeds/api/charts/movies/trending?region=US
Description: This feed lists videos that have recently experienced the greatest increases in popularity. You must specify a value for the region parameter to retrieve this feed.

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

  • The hl parameter specifies the movie's primary language.
  • The movie-genre parameter filters a chart to only include movies that are in a particular genre. The featured movie chart does not support this parameter.
  • 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. The featured movie chart returns an empty feed if you do not specify a value for this parameter.

You can use the following URL to retrieve the top selling or top free movies listed on http://www.youtube.com/movies. Set the paid-content parameter to true for movie rentals and to false for free movies. Note that you also need to provide the appropriate parameter values for the hl (e.g. en) and region (e.g. US) parameters.

http://gdata.youtube.com/feeds/api/charts/movies/trending?v=2
    &max-results=10
    &paid-content=(true|false)
    &hl=<LANGUAGE>
    &region=<REGION_CODE>

Shows, seasons, and episodes

As for movies, videos must meet special metadata requirements to be included in YouTube's Shows category. Feed entries for those videos accordingly contain several extra tags to reflect the enhanced metadata available for shows content. However, these entries are still video feed entries and could be returned in any feed that contains video entries, including search result feeds.

Videos for shows can be either full episodes or clips from an episode. Each video is associated with a particular season of a particular show, and the API provides feeds for retrieving shows, seasons of a show, and episodes (and clips) associated with a season of a show. The API also lets you retrieve show-related charts, which are standard feeds that only contain lists of shows.

In addition, videos in YouTube's Shows category are each associated with a particular season of a specific show. The API provides feeds for retrieving shows, seasons of a show, and episodes (and clips) associated with a specific season of a show. While only the episode/clip feed is a video feed, the other feeds are also explained below.

The following subsections explain these topics in more detail:

  1. Show feeds and entries
  2. Season entries
  3. Special metadata fields in episode (and clip) video entries
  4. Show charts

Show feeds and entries

A show feed contains a list of show entries, in which each entry contains information about one show. Each show is associated with one or more seasons.

A feed entry that represents a show 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#show.

<category scheme='http://schemas.google.com/g/2005#kind'
    term='https://gdata.youtube.com/schemas/2007#show'/>

You can retrieve shows owned by a particular user account by sending a GET request to the following URL:

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

The sample shows feed below demonstrates the feed format. Only one feed entry is shown:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
      xmlns:media='http://search.yahoo.com/mrss/'
      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/&quot;A04GQXczeSp7I2A9WhRXFUQ.&quot;'>
  <id>tag:youtube.com,2008:user:CBA:shows</id>
  <updated>2011-12-23T00:25:20.981Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind' term='https://gdata.youtube.com/schemas/2007#show'/>
  <title>Shows of CBA</title>
  <logo>http://www.gstatic.com/youtube/img/logo.png</logo>
  <link rel='alternate' type='text/html' href='http://www.youtube.com'/>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows?start-index=1&max-results=25&v=2'/>
  <link rel='service' type='application/atomsvc+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows?alt=atom-service&v=2'/>
  <link rel='next' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/CBA/shows?start-index=26&max-results=25&v=2'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.1' uri='https://gdata.youtube.com'>YouTube data API</generator>
  <openSearch:totalResults>53</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;CkUMQH47eCp7I2A9WhdQFkk.&quot;'>
    <id>tag:youtube.com,2008:show:UzSpI-rPrUY</id>
    <published>2011-08-18T04:04:41.000Z</published>
    <updated>2011-08-18T04:04:41.000Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
        term='http://gdata.youtube.com/schemas/2007#show'/>
    <title>Widespread Hilarity</title>
    <summary>Widespread hilarity features Don and Flo getting laughs.</summary>
    <content type='application/atom+xml;type=feed'
        src='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?v=2'/>
    <link rel='alternate' type='text/html'
        href='http://www.youtube.com/show/widespreadhilarity'/>
    <link rel='self' type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/users/CBA/shows/UzSpI-rPrUY?v=2'/>
    <author>
      <name>CBA</name>
      <uri>https://gdata.youtube.com/feeds/api/users/CBA</uri>
    </author>
    <yt:countHint>2</yt:countHint>
    <media:group>
      <media:category scheme='http://gdata.youtube.com/schemas/2007/showgenres.cat'>4</media:category>
      <media:description>Widespread hilarity features Don and Flo getting laughs.</media:description>
      <media:keywords>widespread hilarity</media:keywords>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/market_thumb.jpg'
          height='72' width='128' yt:name='market'/>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/showposter_thumb.jpg'
          height='150' width='150' yt:name='poster'/>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/market.jpg'
          height='243' width='432' yt:name='hqmarket'/>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/showposter.jpg'
          height='300' width='300' yt:name='hqposter'/>
      <media:thumbnail url='http://i.ytimg.com/vi/XPC-JAbDgRE/showposter_hq.jpg'
          height='600' width='600' yt:name='hqposterlarge'/>
      <media:title>Widespread Hilarity</media:title>
    </media:group>
    <yt:schedule country="US" dayOfWeek="1" hour="22" minute="0" second="0"
        timezone="EST" type="weekly"/>
    <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#video.season'
        href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?v=2'
        countHint='2'/>
  </entry>
</feed>

Note the following tags in the show entry:

  • The <gd:feedLink> tag provides a link to the seasons feed for the show. That tag's countHint attribute specifies the number of seasons in that feed. (The <yt:countHint> tag, which is also included in the entry, specifies the same number.)

  • A <media:category> tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/showgenres.cat specifies a genre (e.g. "Action & Adventure" or "Comedy") that describes the show. A show may be associated with multiple genres. The following values are valid for this scheme:

    • 1 – Action & Adventure
    • 2 – Animation & Cartoons
    • 3 – Classic TV
    • 4 – Comedy
    • 5 – Drama
    • 6 – Home & Garden
    • 7 – News
    • 8 – Reality & Game Shows
    • 9 – Science & Tech
    • 10 – Science Fiction
    • 11 – Soaps
    • 13 – Sports
    • 14 – Travel
    • 16 – Entertainment
    • 17 – Documentary
    • 20 – Nature
    • 21 – Beauty & Fashion
    • 23 – Food
    • 24 – Gaming
    • 25 – Health & Fitness
    • 26 – Learning & Education
    • 27 – Foreign Language

Season entries

A seasons feed lists seasons for a particular show for which the show owner has uploaded episodes (or clips) to YouTube. Each season is associated with either full episodes of the show, video clips from the show, or a combination of episodes and clips.

A feed entry that represents a season will contain 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#season.

<category scheme='http://schemas.google.com/g/2005#kind'
    term='https://gdata.youtube.com/schemas/2007#season'/>

To retrieve a feed of seasons for a particular show, first retrieve the entry for that show, and then extract the seasons feed URL from the gd:feedLink tag in the show entry.

The sample seasons feed below demonstrates the feed format. Only one feed entry is shown:

<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
      xmlns:media='http://search.yahoo.com/mrss/'
      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/&quot;CE4BQX0_fip7I2A9WhRWGEw.&quot;'>
  <id>tag:youtube.com,2008:show:UzSpI-rPrUY:content</id>
  <updated>2012-01-06T01:22:30.346Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#season'/>
  <title>Seasons of a show</title>
  <logo>http://www.gstatic.com/youtube/img/logo.png</logo>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?start-index=1&max-results=25&v=2'/>
  <link rel='service' type='application/atomsvc+xml'
      href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content?alt=atom-service&v=2'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.1' uri='http://gdata.youtube.com'>YouTube data API</generator>
  <openSearch:totalResults>2</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;DUEGR347eCp7I2A9WhdbEkQ.&quot;'>
    <id>tag:youtube.com,2008:show:UzSpI-rPrUY:content:GZou3FaPdbw</id>
    <published>2011-07-22T16:59:10.000Z</published>
    <updated>2011-10-11T01:47:06.000Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
        term='http://gdata.youtube.com/schemas/2007#season'/>
    <title>2</title>
    <link rel='http://gdata.youtube.com/schemas/2007#video.show'
        type='application/atom+xml'
        href='http://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY?v=2'/>
    <link rel='self' type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/shows/UzSpI-rPrUY/content/GZou3FaPdbw?v=2'/>
    <author>
      <name>CBA</name>
      <uri>https://gdata.youtube.com/feeds/api/users/CBA</uri>
    </author>
    <media:group>
      <media:title>2</media:title>
    </media:group>
    <yt:season season='2'/>
    <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#season.clips'
        href='https://gdata.youtube.com/feeds/api/seasons/GZou3FaPdbw/clips?v=2'
        countHint='8'/>
    <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#season.episodes'
        href='https://gdata.youtube.com/feeds/api/seasons/GZou3FaPdbw/episodes?v=2'
        countHint='0'/>
  </entry>
</feed>

The feed entry contains two <gd:feedLink> tags. One provides the URL for a feed of full episodes and the other provides the URL for a feed of clips from the specified season of the show. Each tag's countHint attribute specifies the number of videos available in that feed. In addition, the <yt:season> tag specifies the season number.

Special metadata fields in episode (and clip) entries

A video feed entry that represents an episode or clip listed in YouTube's Shows category will contain a <category> tag that has a scheme attribute value of http://gdata.youtube.com/schemas/2007/categories.cat and a term attribute value of Shows.

<category scheme='http://gdata.youtube.com/schemas/2007/categories.cat'
            term='Shows' label='Shows'/>

In addition, feed entries for episodes and clips might also contain the following additional tags, which reflect enhanced metadata that is available for shows content:

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

  • The <yt:episode> tag specifies the episode number for the video.

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

  • Several <media:category> tags, in addition to the standard one that indicates that the video is in the Shows category, can provide the following data:

    • A tag with a scheme attribute value of http://gdata.youtube.com/schemas/2007/mediatypes.cat indicates whether a video is a full episode or a clip from an episode. 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/releasemediums.cat specifies the original release medium for the content. For example, an episode may have been originally aired on a broadcast network 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 episode, and an entry can include multiple <media:credit> tags.

  • The <media:rating> tag can specify a rating, such as a V-Chip rating, for an episode. The tag's scheme attribute identifies the type of rating, and the tag's value specifies the episode'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 show's poster art.

  • Two <link> tags provide the URLs of the show and season entries associated with the video content.

    <link rel='http://gdata.youtube.com/schemas/2007#video.show'
          type='application/atom+xml'
          href='https://gdata.youtube.com/feeds/api/shows/SHOW_ID?v=2'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video.season'
          type='application/atom+xml'
          href='https://gdata.youtube.com/feeds/api/seasons/SEASON_ID?v=2'/>
    

Show charts

To retrieve a show 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:

Chart name Feed ID URL and Description
Most popular shows most_popular URL: https://gdata.youtube.com/feeds/api/charts/shows/most_popular?v=2
Description: This feed, which is updated daily, lists the most popular shows in YouTube's Shows category over the previous seven-day period.
Most recently updated shows latest URL: https://gdata.youtube.com/feeds/api/charts/shows/latest?region=US
Description: This feed, which is updated daily, lists shows that have the latest new content.

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

  • The genre parameter filters a chart to only include shows that are in a particular genre.
  • The region parameter filters a chart to only include shows that are viewable in a particular territory. The parameter value is an ISO 3166-1 alpha-2 code that identifies the country where shows must be viewable to be included in search results.

YouTube EDU

YouTube EDU provides access to high-quality, educational content, including short lessons, full courses, professional development material, and inspiring speeches, from the world's leading universities, educators, and thought leaders. This documentation explains how to use the YouTube API to retrieve information about the lectures (videos), courses, and subjects accessible through YouTube EDU. (Learn more about YouTube EDU.)

YouTube EDU content is organized using three types of entities:

  • A category identifies a subject or area of study, such as Mathematics or Finance. YouTube EDU categories are organized in a hierarchical taxonomy that is modeled after categorizations that exist in many educational institutions. Each category may have one parent category and one or more child categories.

  • A course is a series of lectures (videos) about a particular topic. A course may be linked to one or more categories. Since a course identifies a set of videos meant to be viewed sequentially, it is a type of YouTube playlist that could contain additional types of metadata specific to YouTube EDU material.

  • A lecture is a single YouTube video that is either part of a course or that is attached directly to one or more YouTube EDU categories.

The diagram below shows the relationships between these entities:

As shown in the diagram:

  • A category (or subcategory) has courses. A course may be linked to multiple categories.
  • A course has lectures.
  • A lecture can also be linked directly to one or more categories.

The following sections explain how to retrieve information about YouTube EDU categories and also define the different types of feeds that the API supports for retrieving course and lecture information:

  1. Categories
  2. Courses
  3. Lectures

Categories

The YouTube EDU category file, an XML document that can be downloaded from http://gdata.youtube.com/schemas/2007/educategories.cat, identifies the subjects that can be used to categorize courses and lectures.

The excerpt below shows the beginning of the file, including the top-level category, which is named Primary & Secondary Education, two second-level categories (History & Social Sciences and Science), and three subcategories of the History & Social Sciences category.

<?xml version='1.0' encoding='UTF-8'?>
<app:categories xmlns:app='http://www.w3.org/2007/app'
                xmlns:atom='http://www.w3.org/2005/Atom'
                xmlns:yt='http://gdata.youtube.com/schemas/2007' fixed='no'
                scheme='http://gdata.youtube.com/schemas/2007/educategories.cat'>
  <atom:category term='1' label='Primary &amp; Secondary Education' xml:lang='en-US'/>
  <atom:category term='2' label='History &amp; Social Sciences' xml:lang='en-US'>
    <yt:parentCategory term='1'/>
  </atom:category>
  <atom:category term='3' label='Economics' xml:lang='en-US'>
    <yt:parentCategory term='2'/>
  </atom:category>
  <atom:category term='52' label='State &amp; Local History' xml:lang='en-US'>
    <yt:parentCategory term='2'/>
  </atom:category>
  <atom:category term='143' label='Geography' xml:lang='en-US'>
    <yt:parentCategory term='2'/>
  </atom:category>
  <atom:category term='4' label='Science' xml:lang='en-US'>
    <yt:parentCategory term='1'/>
  </atom:category>

As shown, an <atom:category> tag identifies each category.

  • The tag's term attribute specifies an integer that uniquely identifies the category.
  • The tag's label attribute specifies a display name for the category.
  • The tag's xml:lang attribute identifies the language (and locale) of the display name.
  • The tag's child <yt:parentCategory> element identifies the category's parent in the YouTube EDU category taxonomy.

Courses

A course is a series of lectures (videos) about a particular topic, such as U.S. Historical Documents. A course is associated with one or more YouTube EDU categories.

To retrieve a list of courses in a particular category, send a GET request to the following URL. Replace the string CATEGORY_ID with the category's unique ID from the YouTube EDU category file.

http://gdata.youtube.com/feeds/api/edu/courses?category=CATEGORY_ID

For example, to retrieve a feed of science courses accessible via YouTube EDU, you would retrieve a feed from http://gdata.youtube.com/feeds/api/edu/courses?category=4&v=2 since 4 is the unique identifier for the Science category.

Note: When you retrieve lectures in a particular category, the API will return lectures in that category or any of its child categories.

The XML below shows a sample course entry. Within the entry, the <yt:playlistId> tag specifies a value that YouTube uses to uniquely identify each course. That value can be used to retrieve the list of videos (lectures) that comprise the course.

<entry>
  <id>tag:youtube.com,2008:edu:course:456EDB14CBF90728</id>
  <updated>2012-07-10T08:30:17.322Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
            term='http://gdata.youtube.com/schemas/2007#course'/>
  <title>U.S. Historical Documents</title>
  <summary>Classic Literature VideoBooks with synchronized text ... .</summary>
  <link rel='self' type='application/atom+xml'
        href='http://gdata.youtube.com/feeds/api/edu/courses/456EDB14CBF90728?v=2'/>
  <media:group>
    <media:thumbnail url='http://i.ytimg.com/vi/5oaTVFfUz94/default.jpg'
                     height='90' width='120' yt:name='default'/>
    <media:thumbnail url='http://i.ytimg.com/vi/5oaTVFfUz94/hqdefault.jpg' 
                     height='360' width='480' yt:name='hqdefault'/>
  </media:group>
  <yt:playlistId>456EDB14CBF90728</yt:playlistId>
</entry>

Since a course entry identifies a YouTube playlist, that entry is nearly identical to the playlist entry for the same playlist. However, a course entry also might contain the following additional metadata tags:

  • A <link> tag specifies the feed URL that retrieves a list of the course's lectures. The tag's rel attribute value will be lectures.

    <link rel="lectures" 
          href="https://stage.gdata.youtube.com/feeds/api/edu/lectures?course=E18841CABEA24090"/>
  • For each YouTube EDU category associated with the course, the course entry contains one <category> tag.

    • The tag's scheme attribute value is http://gdata.youtube.com/schemas/2007/educategories.cat.
    • It's term attribute value is the integer that YouTube uses to uniquely identify the category.

  • Similarly, for each YouTube EDU category associated with the course, the course entry's <media:group> tag contains one <media:category> tag.

    • The tag's label attribute contains the display name for the YouTube EDU category.
    • The tag's scheme attribute value is http://gdata.youtube.com/schemas/2007/educategories.cat.
    • The tag's value is the integer that YouTube uses to uniquely identify the category.

  • One or more <media:credit> tags may identify the course's lecturer(s). If present, the tag's role attribute value is lecturer, its scheme attribute value is urn:youtube, and its value is the lecturer's name. An example tag is shown below:

    <media:credit role='lecturer' scheme='urn:youtube'>Professor Ed Copeland</media:credit>
  • One or more <yt:material> tags may be present. Each such tag identifies additional or related course material and a URL where that material can be accessed. For example, <yt:material> tags can identify lecture notes, sample exams, or supplemental reading. An example tag is shown below:

    <yt:material description="This file contains solutions for quiz 1 questions."
                 name="Quiz 1 (solution)" type="exam"
                 url="http://www.example.edu/courses/1234/exams/q1_sol.pdf"/>
      

Lectures

A lecture is a YouTube video that is either part of a course or is connected to one or more YouTube EDU categories. The API supports two ways to retrieve a lecture feed:

  • To retrieve the lectures for a given course, send a GET request to the following URL. Replace the string COURSE_ID with the <yt:playlistId> that uniquely identifies the course.

    http://gdata.youtube.com/feeds/api/edu/lectures?course=COURSE_ID
  • To retrieve a list of lectures in a particular category, send a GET request to the following URL. Replace the string CATEGORY_ID with the category's unique ID from the YouTube EDU category file.

    http://gdata.youtube.com/feeds/api/edu/lectures?category=CATEGORY_ID

    Note: When you retrieve lectures in a particular category, the API will return lectures in that category or any of its child categories.

Since each lecture entry identifies a YouTube video, a lecture entry is nearly identical to the video entry for the same video. However, a lecture entry might also contain the additional metadata tags listed below. A feed listing all of the lectures for a course also might contain these tags.

  • One or more <category> tags identify the YouTube EDU categories associated with either the lecture or the lecture's course.

    • The tag's scheme attribute value is http://gdata.youtube.com/schemas/2007/educategories.cat.
    • It's term attribute value is the integer that YouTube uses to uniquely identify the category.

  • Similarly, one or more <media:category> tags identify the YouTube EDU categories associated with either the lecture or the lecture's course.

    • The tag's label attribute contains the display name for the YouTube EDU category.
    • The tag's scheme attribute value is http://gdata.youtube.com/schemas/2007/educategories.cat.
    • The tag's value is the integer that YouTube uses to uniquely identify the category.

  • One or more <media:credit> tags may identify the lecturer(s). If present, the tag's role attribute value is lecturer, its scheme attribute value is urn:youtube, and its value is the lecturer's name. An example tag is shown below:

    <media:credit role='lecturer' scheme='urn:youtube'>Professor Ed Copeland</media:credit>
  • One or more <yt:material> tags may be present. Each such tag identifies additional or related course material and a URL where that material can be accessed. For example, <yt:material> tags can identify lecture notes, sample exams, or supplemental reading. An example tag is shown below:

    <yt:material description="This file contains solutions for quiz 1 questions."
                 name="Quiz 1 (solution)" type="exam"
                 url="http://www.example.edu/courses/1234/exams/q1_sol.pdf"/>
      

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: Bearer ACCESS_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: Bearer ACCESS_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

IMPORTANT: YouTube is switching to a new commenting system that may require you to modify API calls related to comments. Please review the upcoming changes to comments for a complete explanation of the changes.

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

Note: As part of YouTube's move to a new commenting system, this API feature has been deprecated and is no longer supported. Comments that were replies to other comments now appear as regular comments in API responses.

The new commenting system, which is powered by Google+, supports threading for comments made through that system. With the new system, comment replies are retrieved using the Google+ API's comments:list method. See the article that explains changes to comments in the API for more details.

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: Bearer ACCESS_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

Note: As part of YouTube's move to a new commenting system, this API feature has been deprecated and is no longer supported.

Deleting a comment

You can delete a comment by sending a DELETE request to the comment's edit URL. The following sample API request demonstrates how to delete a comment:

Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

An API request to delete a comment must be authenticated by either the comment's author or the owner of the video associated with the comment. If the request is not properly authenticated, the API will return a 401 (Unauthorized) or 403 (Forbidden) HTTP response code.

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:

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

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: Bearer ACCESS_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/userId/favorites

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

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: Bearer ACCESS_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/default/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/default/favorites/FAVORITE_VIDEO_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_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 authorization token, which enables YouTube to verify that the user authorized access to the resource.

    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. This request does not require user authorization.

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

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

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: Bearer ACCESS_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/default/playlists/PLAYLIST_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_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: Bearer ACCESS_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: Bearer ACCESS_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: Bearer ACCESS_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/default/playlists/PLAYLIST_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_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. You need to replace the string userId with the user's YouTube user ID or YouTube username.

    https://gdata.youtube.com/feeds/api/users/userId/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/userId/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 authorization token, which enables YouTube to verify that the user authorized access to the resource.

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

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

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

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.

The <entry> contains the following tags to identify the channel (or user) associated with the subscription:

  • The <yt:channelId> tag identifies the channel associated with the subscription.

  • The <yt:username> identifies the display name for the user or channel associated with the subscription.

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


<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/&quot;DU4DRX47eCp7ImA9WB9RFEU.&quot;'>
  <id>tag:youtube.com,2008:user:_x5XG1OV2P6uZZ5FSM9Ttw:subscriptions</id>
  <updated>2008-07-21T17:10:32.855Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#subscription'/>
  <title>Subscriptions of 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/_x5XG1OV2P6uZZ5FSM9Ttw?v=2'/>
  <link rel='alternate' type='text/html'
    href='https://www.youtube.com'/>
  <link rel='hub' href='http://pubsubhubbub.appspot.com'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions?alt=...'/>
  <author>
    <name>_x5XG1OV2P6uZZ5FSM9Ttw</name>
    <uri>https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw</uri>
    <yt:userId>_x5XG1OV2P6uZZ5FSM9Ttw</yt:userId>
  </author>
  <generator version='2.1'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>3</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>

  <entry gd:etag='W/"CEAHQX47eCp7ImA9WxBSEUQ."'>
    <id>tag:youtube.com,2008:user:_x5XG1OV2P6uZZ5FSM9Ttw:subscription:ps2fD3tG7-s</id>
    <published>2009-12-18T19:18:50.000-08:00</published>
    <updated>2009-12-18T19:18:50.000-08:00</updated>
    <app:edited>2009-12-18T19:18:50.000-08:00</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='user'/>
    <title>Activity of : GoogleTechTalks</title>
    <content type='application/atom+xml;type=feed'
      src='https://gdata.youtube.com/feeds/api/users/googletechtalks/events?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/googletechtalks/events?v=2'/>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/channel/UCtXKDgv1AVoG88PLl8nGXmw'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/default/subscriptions/ps2fD3tG8-s?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions/MpajmvGNexIkHC?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
      <yt:userId>_x5XG1OV2P6uZZ5FSM9Ttw</yt:userId>
    </author>
    <yt:channelId>UCtXKDgv1AVoG88PLl8nGXmw</yt:channelId>
    <yt:countHint>1688</yt:countHint>
    <media:thumbnail url='https://s.ytimg.com/yt/img/no_videos_140-vfl5AhOQY.png'/>
    <yt:unreadCount>5</yt:unreadCount>
    <yt:username display='GoogleTechTalks'>googletechtalks</yt:username>
  </entry>

  <entry gd:etag='W/&quot;DU4DRX47eCp7ImA9WB9RFEU.&quot;'>
    <id>tag:youtube.com,2008:user:_x5XG1OV2P6uZZ5FSM9Ttw:subscription:MpajmvGNex</id>
    <published>2007-10-15T15:39:34.000-07:00</published>
    <updated>2007-10-15T15:39:34.000-07:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2007-10-15T15:39:34.000-07:00</app:edited>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='channel'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <title>Videos published by : OpenSocialFoundation</title>
    <content type='application/atom+xml;type=feed'
      src='https://gdata.youtube.com/feeds/api/users/opensocialfoundation/uploads?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/opensocialfoundation?v=2'/>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/channel/UCFVAu1vssbJ_M7ydX3JxrEA/videos'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions/MpajmvGNex?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions/MpajmvGNex?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
      <yt:userId>_x5XG1OV2P6uZZ5FSM9Ttw</yt:userId>
    </author>
    <yt:channelId>UCFVAu1vssbJ_M7ydX3JxrEA</yt:channelId>
    <yt:countHint>25</yt:countHint>
    <media:thumbnail url='https://s.ytimg.com/yt/img/no_videos_140-vfl5AhOQY.png'/>
    <yt:unreadCount>5</yt:unreadCount>
    <yt:username display='OpenSocialFoundation'>opensocialfoundation</yt:username>
  </entry>
</feed>

Retrieving new subscription videos

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

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

    https://gdata.youtube.com/feeds/api/users/default/newsubscriptionvideos
  • 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/userId/newsubscriptionvideos

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

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

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

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

Adding a subscription

To create a subscription, you send a POST request that identifies the YouTube user name for the authenticated user who is creating the subscription. The body of the request is an XML entry that contains the following elements:

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

  • The <yt:username> tag identifies the channel or the user whose activity is being subscribed to.

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

Subscribing to a user's activities
POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="user"/>
    <yt:username>GoogleDevelopers</yt:username>
</entry>

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

Subscribing to a channel
POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="channel"/>
    <yt:username>GoogleDevelopers</yt:username>
</entry>

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

The following steps explain a common use case for creating subscriptions, in which a user watches a video and subscribes to the video owner's activity or channel.

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

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

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

Deleting a subscription

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

DELETE /feeds/api/users/default/subscriptions/SUBSCRIPTION_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

The following steps explain a common use case for deleting a subscription, in which a user looks at his list of subscriptions and removes one or more subscriptions from the list.

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

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

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

Channel suggestions

A user's channel suggestions feed identifies channels that may appeal to the user. YouTube recommends channels to a user based on an algorithm that considers signals from a variety of sources that include the user's subscriptions, favorite videos, ratings, and more.

To retrieve a feed containing channel suggestions for a logged-in user, send an authorized GET request to the URL below. The request must specify your developer key.

https://gdata.youtube.com/feeds/api/users/default/suggestion?type=channel&inline=true

Note: This feed is only supported for authorized users who are retrieving their own channel suggestions feed.

If you set the inline parameter value to true when retrieving a channel suggestions feed, then each feed entry will include a channel entry that contains all of the metadata for that channel. The channel entry will be encapsulated inside the <content> element.

The example below shows a channel suggestions feed entry for an API request that set the inline parameter value to true.

<entry>
  <id>tag:youtube.com,2008:suggestion:rWP5WOR8y6_iEQoF2ABrgLcf2ulmIfuI_TvJyayqrPk</id>
  <updated>2012-09-19T20:47:35.421Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
            term='http://gdata.youtube.com/schemas/2007#suggestion'/>
  <content type='application/atom+xml'>
    <entry>
      <id>tag:youtube.com,2008:channel:UC7McHNOsrUL2fRxTB_xvgRQ</id>
      <updated>2012-09-19T20:47:35.421Z</updated>
      <category scheme='http://schemas.google.com/g/2005#kind'
                term='http://gdata.youtube.com/schemas/2007#channel'/>
      <title>johnnycarson</title>
      <summary>Before there was Conan... before there was Jay... there was Johnny.</summary>
      <link rel='self' type='application/atom+xml'
            href='https://gdata.youtube.com/feeds/api/channels/UC7McHNOsrUL2fRxTB_xvgRQ?v=2'/>
      <author>
        <name>johnnycarson</name>
        <uri>https://gdata.youtube.com/feeds/api/users/johnnycarson</uri>
        <yt:userId>7McHNOsrUL2fRxTB_xvgRQ</yt:userId>
      </author>
      <yt:channelStatistics videoCount='241' subscriberCount='13009'/>
      <media:thumbnail url='https://i4.ytimg.com/i/7McHNOsrUL2fRxTB_xvgRQ/1.jpg?v=c8879e'/>
      <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#channel.content'
                   href='https://gdata.youtube.com/feeds/api/users/johnnycarson/uploads?v=2' countHint='241'/>
      <yt:channelId>UC7McHNOsrUL2fRxTB_xvgRQ</yt:channelId>
    </entry>
  </content>
  <link rel='self' type='application/atom+xml'
        href='https://gdata.youtube.com/feeds/api/users/andyland74/suggestion/rWP5WOR8y6_iEQoF2ABrgLcf2ulmIfuI_TvJyayqrPk?v=2'/>
  <yt:contentType>channel</yt:contentType>
</entry>

Video recommendations

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

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

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

Note: An API request to retrieve a user's recommendations feed must specify your developer key. In addition, the request must also specify an authentication token, which enables YouTube to identify the user and ensures that recommendations are tailored to the right user.

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

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

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.

It is also worth noting that in the watch history feed, as in other feeds, the <openSearch:totalResults> tag may overstate the actual number of results. As discussed in the reference guide, we recommend that you use a feed's <link> tags to identify pagination links for the previous and/or next page of entries in a feed.

Deleting videos from the watch history feed

To delete a video from a user's watch history feed, send a DELETE request to the edit URL for the appropriate watch history feed entry. This operation is only supported for authenticated users who are modifying their own watch history feed.

The request below shows the URL and format of an XML request to remove a video from the logged-in user's watch history feed:

DELETE /feeds/api/users/default/watch_history/WATCH_HISTORY_EVENT_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

To delete all videos from a user's watch history feed, send a POST request to https://gdata.youtube.com/feeds/api/users/default/watch_history/actions/clear. The request needs to include an empty <entry> element as shown in the example below:

POST /feeds/api/users/default/watch_history/actions/clear HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_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">
</entry>

Enabling user interaction

User profiles

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

In addition, API version 2.1 supports two additional operations for users who have unlinked Google Accounts. As discussed in the API versioning section, these are users who have a Google Account but who do not have a YouTube username. The username also identifies the YouTube channel associated with the user's uploaded videos. Those two operations are described below:

  • You can upgrade an unlinked Google Account to also be associated with a YouTube username. This operation also creates the YouTube channel for the user.

  • Before actually attempting to associate a user's unlinked Google Account with a new YouTube channel, you can retrieve a feed of unused YouTube usernames that are similar to a hint that you provide.

Retrieving a user's profile

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

  • To request the currently logged-in user's profile, send 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
  • To request another user's profile, send a GET request to the following URL. Note that this request does not require authentication.

    https://gdata.youtube.com/feeds/api/users/userId

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

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

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

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

  • The <yt:statistics> tag contains statistics about the user, including the number of people who have viewed the user's channel, the number of videos the user has watched, the number of people who subscribe to the user's uploaded videos, and the total number of views for all of the user's videos.

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

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


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

Associating an unlinked Google Account with a YouTube channel

You can upgrade an unlinked Google Account so that it is associated with a YouTube username (and channel). This process is explained in the Creating a YouTube channel document, which describes the process of spawning an Android WebView, iOS UIWebView, or similar object, to allow a user to create a YouTube channel and then return control to your application.

Note: The process explained in that document replaces an API call for upgrading an unlinked Google Account that has since been deprecated.

Contacts

We are reworking YouTube's messaging functionality. While the v2 API has already been deprecated, some API functionality related to contacts will begin returning errors as early as March 31, 2014.

At that time, the API will return 403 (Forbidden) HTTP responses to requests to add, update, or delete contacts. The API will continue to support retrieval of a user's contacts for around six months after that date. After that time, the API will return an empty list in response to a request to retrieve a user's contacts.

We're excited to provide a new and better API for messaging and video sharing later this year.

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

Retrieving a user's contacts

To request the currently logged-in user's contact list, send a GET request to the following URL. Your request must provide an authorization token, which enables YouTube to verify that the user authorized access to the resource.

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

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

Note: The API does not allow one user to retrieve another user's contacts.

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

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

  • The <yt:username> tag and <yt:userId> tags both specify values that uniquely identify the contact. In addition, the <yt:username> tag's display attribute specifies a display name for the contact.

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

    • accepted - The feed owner and another user have both added each other as contacts.
    • requested - Another user has added the authenticated user as a contact, but the authenticated user has not also added the other user as a contact.
    • pending - The authenticated user has added another user as a contact, but the other user has not also added the authenticated user as a contact.

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


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

Adding a contact

To add a contact, send an API request that identifies the user who is adding the contact as well as the contact being added. The following example demonstrates the request format:

POST /feeds/api/users/default/contacts HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_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:username>CONTACT_ID</yt:username>
</entry>

Updating a contact

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

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

The API enables a user to update a contact that has a status of requested by either accepting or rejecting the contact. To update the contact, set the value of the <yt:status> tag in your API request to either accepted or rejected.

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

PUT /feeds/api/users/default/contacts/CONTACT_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_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">
  <status>accepted</status>
</entry>

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

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

  2. Your application displays the list of contacts as well as a way to accept or reject contacts that have a status of either pending or requested.

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

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

Deleting a contact

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

DELETE /feeds/api/users/default/contacts/CONTACT_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

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

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

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

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

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

Messages and video sharing

We are reworking YouTube's messaging functionality. While the v2 API has already been deprecated, some API functionality related to messages and video sharing will begin returning errors as early as March 31, 2014.

At that time, the API will return 403 (Forbidden) HTTP responses to requests to send or delete messages. The API will continue to support retrieval of a user's inbox for around six months after that date. After that time, the API will return an empty list in response to a request to retrieve a user's inbox.

We're excited to provide a new and better API for messaging and video sharing later this year.

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

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

Retrieving messages from a user's inbox

To retrieve a feed containing a list of the messages in the currently logged-in user's inbox, send a GET request to the following URL. Note: For this request, you must provide an authentication token. The authentication token enables YouTube to identify the user, and this restriction ensures that a user can only retrieve messages from her own inbox.

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

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

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

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

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

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

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

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

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

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


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

Sending a video message

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

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

POST /feeds/api/users/MESSAGE_RECIPIENT_USERNAME/inbox HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY


<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:yt="http://gdata.youtube.com/schemas/2007">
  <id>Qm6znjThL2Y</id>
  <summary>sending a message from the api</summary>
</entry>

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

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

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

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

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

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

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

Deleting a message

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

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

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

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

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

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

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

Activity feeds

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

  • A subscription activity feed identifies actions associated with the authenticated user's subscriptions.
  • A user activity feed identifies actions taken by one or more users who are specified in the API request.

In addition, the API previously supported a third type of activity feed, the friend activity feed. This feed type has been deprecated, and requests to retrieve a friend activity feed will instead return the authenticated user's subscription activity feed.

User events in activity feeds

Activity feeds list the following events:

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

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

  1. Retrieving an activity feed
  2. Sample activity feed
  3. Subscription activity (subtivity) feeds
  4. User activity feeds
  5. Retrieving additional metadata for activity feed entries

Retrieving an activity feed

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

  • Each entry contains an <author> tag, which encapsulates information about the user associated with the event. Within that tag, the <yt:userId> contains a value that uniquely identifies the user. The <name> tag identifies either the user's YouTube username or, if the user's YouTube account is connected to a Google+ profile, the user's public display name.

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

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

      • The <yt:videoid> tag identifies the rated video.
      • The <yt:rating> tag specifies the rating given to the video. Activity feeds only identify videos that were given positive ('like') ratings.
      • The <gd:rating> tag identifies a numeric rating given to the video.

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

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

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

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

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

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

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

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

    An activity feed entry may contain a <yt:groupId> tag, which, if present, indicates that the event is closely related to another event in the same feed. Generally, events with the same <yt:groupId> value are associated with the same user and video (or other resource). For example, if a user positively rates a video and marks the same video as a favorite, those two events will have the same <yt:groupId> value in activity feeds. Your application can avoid repetition by grouping events with the same <yt:groupId> value as shown in the image below.

    Image showing single UI entry for a video that was marked as a favorite and positively rated by the same user.

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

Sample activity feed

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

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

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

The XML contains one entry, which identifies an instance of a video being uploaded.


<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"D0EGSH47eCp7ImA9WxRVGEg.&quot;'>
  <id>tag:youtube.com,2008:user:GoogleDevelopers:subtivity</id>
  <updated>2012-03-20T09:13:49.000Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#userEvent'/>
  <title>Subtivity for GoogleDevelopers</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/users/GoogleDevelopers/subtivity?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity?start-index=1&max-results=25&v=2'/>
  <link rel='service' type='application/atomsvc+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity?alt=atom-service&v=2'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>12</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/"D0EGSH47eCp7ImA9WxRQQEg."'>
    <id>tag:youtube.com,2008:user:GoogleDevelopers:event:VGF5Wm9uZNzQ5MzM%3D</id>
    <updated>2009-01-16T09:13:49.000Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#userEvent'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
      term='video_uploaded'/>
    <title>GoogleTechTalks has uploaded a video</title>
    <link rel='alternate' type='text/html' href='https://www.youtube.com'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/_gZK0tW8EhQ?v=2'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity/VGF5Wm9uZGF5MzEy%3D%3D?v=2'/>
    <author>
      <name>GoogleTechTalks</name>
      <uri>https://gdata.youtube.com/feeds/api/users/tXKDgv1AVoG88PLl8nGXmw</uri>
      <yt:userId>tXKDgv1AVoG88PLl8nGXmw<</yt:userId>
    </author>
    <yt:videoid>_gZK0tW8EhQ</yt:videoid>
  </entry>
</feed>

Subscription activity (subtivity) feeds

To retrieve a subscription activity feed for the currently logged-in user, send a GET request to the following URL. You must provide an authentication token with this request, which ensures that a user can only retrieve her own subscription activity feed. Your request must also specify your developer key.

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

Subscription activity feeds contain the most recent events associated with the authenticated user's subscriptions. Events must have occurred within the previous 14 days to be included in the feed, and the total number of events included in the feed may be limited.

User activity feeds

User activity feeds list user events that occurred within the last 60 days. You can request a user activity feed for a single user or you can retrieve a single feed that lists actions from multiple users.

The YouTube API provides several ways to retrieve a user activity feed. All requests must specify your developer key.

  • To retrieve the user activity feed for the currently authenticated user, send a GET request to the following URL:

    https://gdata.youtube.com/feeds/api/users/default/events?v=2
  • To retrieve another user's activity feed, send a request to the following URL. Replace the text username with either the user's YouTube user ID or YouTube username.

    https://gdata.youtube.com/feeds/api/users/userId/events?v=2
  • To retrieve a user activity feed that lists the actions of one or more users, send a request to the following URL. In the request, set the author parameter value to a comma-separated list of up to 20 YouTube user IDs or YouTube usernames, and the API response will list actions performed by any of those users.

    https://gdata.youtube.com/feeds/api/events?author=userIds
    

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

Note: If you need to track updates for a large number of user activity feeds, consider using the Simple Update Protocol, which is supported if you use the first of the two retrieval methods described below.

Retrieving additional metadata for activity feed entries

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

  • To retrieve additional metadata about videos associated with particular events, you can either use the inline parameter or you can submit a batch processing request. Both of these options are explained below.
  • To retrieve additional metadata about users associated with particular events, you can submit a batch processing request.

Using the inline parameter

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

The sample feed below shows how an inlined video entry appears in an activity feed. The video entry appears in italics in the sample feed, and the event entry in the XML is the same one that appears in the Sample activity feed section. Several child tags of both the <feed> and the inlined <entry> tags have been omitted in an effort to make the sample more readable.


<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"D0EGSH47eCp7ImA9WxRVGEg.&quot;'>
  <updated>2012-03-20T09:13:49.000Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#userEvent'/>
  <title>Subtivity for GoogleDevelopers</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>12</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/"D0EGSH47eCp7ImA9WxRQQEg."'>
    <updated>2009-01-16T09:13:49.000Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#userEvent'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
      term='video_uploaded'/>
    <title>GoogleTechTalks has uploaded a video</title>
    <link rel='alternate' type='text/html' href='https://www.youtube.com'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/_gZK0tW8EhQ?v=2'/>

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

    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity/VGF5Wm9uZGF5MzEy%3D%3D?v=2'/>
    <author>
      <name>GoogleTechTalks</name>
      <uri>https://gdata.youtube.com/feeds/api/users/tXKDgv1AVoG88PLl8nGXmw</uri>
      <yt:userId>tXKDgv1AVoG88PLl8nGXmw<</yt:userId>
    </author>
    <yt:videoid>_gZK0tW8EhQ</yt:videoid>
  </entry>
</feed>

Submitting a batch processing request

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

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

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

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

    Activity feed:
    
        <entry>
          ...
          <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
            term='video_favorited'/>
          <yt:videoid>5EDAB37EA1823E58</yt:videoid>
        </entry>
    
    Batch processing request:
    
        <entry>
          <id>http://gdata.youtube.com/feeds/api/videos/<yt:videoid></id>
        </entry>
    
  • To retrieve a list of user profiles in a batch processing request, send a POST request to the following URL:

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

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

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

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

Sample batch processing request for additional metadata

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


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

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

Monitoring activity feeds with SUP

Warning: If you are using SUP for monitoring comments, you will be impacted by the change to the new commenting system. Please read this article for details.

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

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

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

  1. Understanding the SUP feed format
  2. Retrieving YouTube's SUP feed
  3. Discovering hash keys for activity feeds
  4. SUP in action

Understanding the SUP feed format

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

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

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

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

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

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

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

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

Retrieving YouTube's SUP feed

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

http://gdata.youtube.com/sup

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

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

Discovering hash keys for activity feeds

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

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

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

You can also retrieve the user activity feed for the currently logged-in user by sending an authenticated GET request to the following URL:

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

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

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

SUP in action

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

The application has two main components:

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

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

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

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

Screenshot of SUP presentation video

Using batch processing with the YouTube Data API

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

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

Please note the following characteristics of batch processing requests:

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

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

  • Submitting requests in a batch process does not reduce the amount of quota that your application uses and, therefore, does not reduce the likelihood that your application will exceed our limits on API calls.

  • Some of the API's client libraries may not support batch processing.

Submitting a batch processing request

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

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

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

Important: Every entry in the batch request must be associated with the same batch URL. As such, you cannot use a single batch processing request to insert videos to a playlist and to flag those videos as a user's favorite videos since the playlist's feed has a different batch URL than the favorite videos feed.

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

Batch processing guidelines

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

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

  • Batch processing requests must be 1MB or smaller.

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

Sample batch processing request

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

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

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

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

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

Handling the API response for a batch processing request

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

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

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

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

Tracking operations in a batch processing request

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

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

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

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

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

Identifying interrupted batch processing

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

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

Retrieving a partial response

Note: This feature is not subject to the Deprecation Policy. Learn more.

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

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

  1. Submitting a request for a partial feed response
  2. Formatting the fields parameter value
  3. Handling a partial feed response

Note: This feature is not supported for API requests that retrieve JSON-C responses.

Submitting a request for a partial feed response

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

  • It can specify the data fields that will be included in the API response. When used in this context, the parameter limits the data fields that are returned for the feed or for specific entries in the feed. However, it does not affect which entries are included in the result set.

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

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

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

      GET https://gdata.youtube.com/feeds/api/videos?q=surfing&max-results=10
      
    • This example uses the fields parameter to filter the results that would have been obtained in the previous example. The query specifies that the API should return videos that match the keyword "surfing" and that have more than 1,000,000 views:

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

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

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

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

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

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

Formatting the fields parameter value

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

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

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

    Example 1: Retrieve number of items in feed, index of
    first item in result set, and all entries in the feed:
    
        fields=openSearch:totalResults,openSearch:startIndex,entry
    
    Example 2: Retrieve the title, player URL, and thumbnail images for a single
    video entry. Note that this example uses parentheses to list the child elements
    of <media:group> that should be included in the API response.
    
        fields=title,media:group(media:player,media:thumbnail)
    
  • You can specify that an API response should only include the text content for a particular element or that it should only include certain attributes for that element. Just as you use parentheses to specify that a response should only contain particular child elements, you also use parentheses to specify whether the response should include the text content and/or attributes for a particular element. If you do not specify otherwise, the response will include the text content and all attributes for any element included in the response.

    Example 1: Retrieve all <entry> tags in feed, including any 
    attributes of the <entry> tag as well as all subtags in those entries,
    but do not retrieve other subtags of <feed>:
    
        fields=entry
    
    Example 2: Retrieve all <entry> tags in feed, but only include the
    <media:group> tag and all of its subtags in each entry. Do not
    retrieve attributes of the <entry> tag or other subtags of <feed>:
    
        fields=entry(media:group)
    
    Example 3: Retrieve all thumbnail URLs for the entries in the feed. The 
    response will be a feed of <entry> tags, each of which contains a
    <media:group> tag. Each <media:group> tag will contain a list of
    <media:thumbnail> tags that provide a value for their url attribute
    but do not include any other attributes:
    
        fields=entry(media:group(media:thumbnail(@url)))
    
    Example 4: Retrieve the <title>, <content> and <media:category>
    tags for videos in the result set. For each <media:category> tag, only
    return the tag's text content and the label attribute. The
    release notes discuss this feature and the evolution of the query syntax
    for partial responses in more detail.
    
        fields=entry(title,content,media:group(media:category(@label,text())))
    
  • By default, if your request specifies an element that occurs more than once, the partial response will include all instances of that element. However, you can also specify that the response should only include elements that have a particular attribute value as shown in the examples below.

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

Retrieving videos for playback on mobile devices

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

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

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

Supported syntax

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

Operator Syntax Example(s)
Filter elements (list elements to be returned in parentheses)
  • Return the <title>, <content> and <media:category> tags for videos in the result set.
        entry(title,content,media:group(media:category))

  • Return the <title>, <content> and <media:category> tags for videos in the result set, but only return the <media:category> tag's text value and do not include its attributes. This sample request differs from the previous one by adding an additional /text() path to the fields parameter value.
        entry(title,content,media:group(media:category/text()))
Existence [put conditions inside square brackets]
  • Filter the result set to only include video entries that contain a <yt:state> tag. For those videos, only return the <title>, <media:thumbnail>, and <yt:state> tags.
        entry[app:control/yt:state](title,media:group(media:thumbnail),app:control(yt:state))

    To filter results based on the presence of an element that does not contain text content, you must set the fields-language parameter value to r2. For example, the following example only returns entries that contain the <app:control> tag, which has subtags but does not contain text content.
        entry[app:control]&fields-language=r2
Equality comparison =
eq
!=
ne
  • Return entire entry if it contains a <link> element that has a rel attribute set to 'self':
        entry[link/@rel='self']

  • Return entire entry if it contains a <yt:aspectRatio> element with the value 'widescreen':
        entry[media:group/yt:aspectRatio = 'widescreen']
Logical comparison and
or
not
  • Return any entry that contains a <category> element that has a term attribute set to either 'ski' or 'snowboard':
        entry[category/@term = 'ski' or category/@term = 'snowboard']

  • Return <title> and <content> elements for each entry as well as any <media:thumbnail> elements that identify 90x120 images:
        entry(title,content,media:group(media:thumbnail[@height='90' and @width='120']))

  • Return <title> and <media:group> elements for entries that do not restrict playback in any way, which is indicated by the presence of the <yt:state> element:
        entry[not(app:control/yt:state)](title,media:group)
Numerical comparison > or gt
>= or ge
< or lt
<= or le
  • Return the <title>, <yt:statistics> and <media:group> elements for videos that have been viewed more than 20 times:
        entry[yt:statistics/@viewCount > 20](title,yt:statistics,media:group)

  • Return entries for videos that are less than two minutes long and have more than 20 views:
        entry[media:group/yt:duration/@seconds <= 120 and yt:statistics/@viewCount > 20]
Date comparison Use numerical operators for date and dateTime fields as shown.
  • Return entries for videos that were updated after 12 p.m. (UTC) on June 1, 2009. This is a dateTime comparison:
        entry[xs:dateTime(updated) > xs:dateTime('2009-06-01T12:00:00.000Z')]

  • Return <media:group> element and all of its child elements for videos that were recorded before June 1, 2009. Note that the <yt:recorded> tag is the only date (as opposed to dateTime) field in YouTube API feeds:
        entry[xs:date(yt:recorded) < xs:date('2009-06-01')](media:group)
Wildcard *
  • Return all elements in the media and yt namespaces.
        entry(media:*, yt:*)

Handling a partial feed response

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

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

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

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

Submitting partial update (PATCH) requests

Note: This feature is not subject to the Deprecation Policy. Learn more.

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

  1. Submitting a partial update request
  2. Formatting a partial update request
  3. Changing access controls with partial updates
  4. Alternate notation for applications that do not handle PATCH method
  5. Handling the response to a partial feed update
  6. Error handling for partial update (PATCH) requests

Note: Please read this documentation thoroughly before implementing partial updates to ensure that your updates do not inadvertently delete optional data fields. We also recommend that you test your partial update implementation on our staging server before launching the feature to production.

Submitting a partial update request

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

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

PATCH /feeds/api/users/default/uploads/VIDEO_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY


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

Formatting a partial update request

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

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

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

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

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

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

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

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

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

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

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

    <entry xmlns='http://www.w3.org/2005/Atom'
        xmlns:media='http://search.yahoo.com/mrss/'
        xmlns:yt='http://gdata.youtube.com/schemas/2007'
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:fields='media:group/yt:private'>
      <media:group>
        <yt:private/>
      </media:group>
    </entry>
    
  3. Elements that appear in the XML request but that are not identified in the <entry> element's gd:fields attribute value are merged into the existing metadata for the resource according to the following rules:

    1. If the resource does not already contain an element that appears in the PATCH request, then the new element – including its content, attributes, and child elements – is added to the resource. For example, if a video is not associated with a set of geographic coordinates, and your PATCH request contains a <gml:pos> tag, the coordinates specified in that tag are associated with the video.

    2. If a non-repeating element in the PATCH request already appears in the resource, and the element does not have child elements, then the new element in the request replaces the existing element in the resource. For example, a video can only be associated with one location. As such, if a video is associated with a location, and your PATCH request contains a <yt:location> tag, the location specified in the request replaces the one already associated with the video. As a result, the following request has the same effect even if you do not include the <entry> tag's gd:fields attribute.

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

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

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

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

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

Changing access controls with partial updates

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

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

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

    <entry xmlns='http://www.w3.org/2005/Atom'
        xmlns:yt='http://gdata.youtube.com/schemas/2007'
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:fields='yt:accessControl'>
      <yt:accessControl action='comment' permission='allowed'/>
      <yt:accessControl action='commentVote' permission='allowed'/>
      <yt:accessControl action='embed' permission='allowed'/>
      <yt:accessControl action='rate' permission='allowed'/>
      <yt:accessControl action='list' permission='allowed'/>
      <yt:accessControl action='syndicate' permission='allowed'/>
    </entry>
    
  • To replace one access control without changing other control settings, use the <entry> tag's gd:fields attribute to identify the setting you want to replace. In this case, you need to define the gd:fields value narrowly to avoid deleting other tag values that you want to keep.

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

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

Alternate notation for applications that do not handle PATCH method

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

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

Handling the response to a partial feed update

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

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

Error handling for partial update (PATCH) requests

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

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

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

    The sample response below shows the format of this error:

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

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

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

    <entry xmlns='http://www.w3.org/2005/Atom'
        xmlns:media='http://search.yahoo.com/mrss/'
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:fields='media:group/media:title'>
      <media:group>
        <media:title type='plain'>New video title</media:title>
        <media:keywords>new,keywords,here</media:keywords>
      </media:group>
    </entry>
    
  • If you try to update the access controls for a video, the API will return a too_many validation error unless you use the gd:fields attribute to identify the controls that you are updating. This error occurs because the <yt:accessControl> tag is a repeating element. As such, if you include the tag in a PATCH request, the API will add any access controls that you specify to the existing set of controls for a video. However, a video cannot specify more than one access control for a specific action ("embed", "rate", etc.).

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

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

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

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

      <?xml version="1.0" encoding="UTF-8"?>
      <entry xmlns="http://www.w3.org/2005/Atom"
                xmlns:yt="http://gdata.youtube.com/schemas/2007"
                xmlns:gd="http://schemas.google.com/g/2005"
                gd:fields="yt:accessControl[@action='comment' or @action='rate']">
        <yt:accessControl action="comment" permission="moderated"/>
        <yt:accessControl action="rate" permission="allowed"/>
      </entry>
      
    • To update all access controls, you would set the gd:fields value to yt:accessControl. Any access controls that are defined in the XML request will be applied to the video, and all other access controls will return to their default settings. For example, the following request sets the access control setting for comments to moderated and reverts all other access controls to their default settings:

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

Testing and troubleshooting

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

Using the Interactive API Demo

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

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

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

  2. Construct the API request.

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

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

Using the staging server

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

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

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

We recommend that you create a test account and only use that account when running queries against the staging server.

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

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

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

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

Troubleshooting common API challenges

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

  1. Filtering API responses
  2. Calculating the content-length for direct upload requests
  3. Identifying a video for a particular operation
  4. Uploading private videos
  5. Caching video metadata to avoid quota issues
  6. Uploading a large batch of videos

Filtering API responses

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

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

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

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

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

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

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

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

Calculating the content-length for direct upload requests

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

Multipart must have Atom and media part

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

Identifying a video for a particular operation

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

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

For example, to add a video to a playlist you send a POST request to the following URL, with the string PLAYLIST_ID identifying the playlist to which you are adding the video:

https://gdata.youtube.com/feeds/api/playlists/PLAYLIST_ID

The request includes the XML below, in which the string VIDEO_ID identifies the video that is being added to the playlist. That value is the <yt:videoid> value for that video.

<entry xmlns="http://www/w3.org/2005/Atom">
  <id>VIDEO_ID</id>
  <yt:position>1</yt:position>
</entry>

Uploading private videos

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

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

Caching video metadata to avoid quota issues

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

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

Uploading a large batch of videos

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

Retrieving Insight data

Important: The API's support for YouTube Insight data has been officially deprecated as of September 30, 2013. This functionality will continue to work as per our deprecation policy, but we encourage you to migrate to the new YouTube Analytics API as soon as possible. If you are building a new application, use the YouTube Analytics API to get the most comprehensive set of API features related to the YouTube Analytics data.

See the explanation of YouTube Insight functionality that the API provides in the documentation for the deprecated API feature.

Understanding API error responses

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

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

Validation errors

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

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

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

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

    <?xml version='1.0' encoding='UTF-8'?>
    <errors>
      <error>
        <domain>yt:validation</domain>
        <code>required</code>
        <location type='xpath'>media:group/media:title/text()</location>
      </error>
    </errors>
    
  • deprecated - This code indicates that an element's value has been deprecated and is no longer valid. For example, a video category name that has been retired may not be associated with newly added or updated videos.

    <?xml version='1.0' encoding='UTF-8'?>
    <errors>
      <error>
        <domain>yt:validation</domain>
        <code>deprecated</code>
        <location type='xpath'>
          media:group/media:category[@scheme='http://gdata/youtube.com/schemas/2007/categories.cat']/text()
        </location>
      </error>
    </errors>
    
  • invalid_format - This code indicates that an XML element's value does not match an expected format. For example, you could receive this error if you specify invalid coordinates in the <gml:pos> tag.

    <?xml version='1.0' encoding='UTF-8'?>
    <errors>
      <error>
        <domain>yt:validation</domain>
        <code>invalid_format</code>
        <location type='xpath'>georss:where/gml:point/gml:pos/text()</location>
      </error>
    </errors>
    
  • invalid_character - This code indicates that an XML field value contains an invalid character. For example, video titles may not contain a less than (<) character.

    <?xml version='1.0' encoding='UTF-8'?>
    <errors>
      <error>
        <domain>yt:validation</domain>
        <code>invalid_character</code>
        <location type='xpath'>media:group/media:title/text()</location>
      </error>
    </errors>
    
  • too_long - This code indicates that an XML element's value exceeds the maximum allowable length. For example, video titles must be 60 characters or less.

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

Quota errors

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

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

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

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

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

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

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

Authentication and authorization errors

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

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

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

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

    <?xml version='1.0' encoding='UTF-8'?>
    <errors>
      <error>
        <domain>yt:authentication</domain>
        <code>InvalidToken</code>
        <location type='header'>Authorization: GoogleLogin</location>
      </error>
    </errors>
    
  • TokenExpired - This code indicates that the token specified in the Authorization header has expired.

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

Service errors

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

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

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

    <?xml version='1.0' encoding='UTF-8'?>
    <errors>
      <error>
        <domain>yt:service</domain>
        <code>disabled_in_maintenance_mode</code>
      </error>
    </errors>
    
  • youtube_signup_required - This code is returned in API version 2.1 when a user with an unlinked Google Account submits an API request that requires the authenticated user to have a YouTube channel. If you receive this 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. That page will let the user associate her Google Account with a YouTube 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.

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

Revision History

March 21, 2014

This update contains the following changes:

  • The documentation that explains the API's contacts and messaging functions has been updated to explain that we are reworking YouTube's messaging functionality. While the v2 API has already been deprecated, some API functionality related to contacts and messaging will begin returning errors as early as March 31, 2014.

    At that time, the API will return 403 (Forbidden) HTTP responses to requests to add, update, or delete contacts. Similarly, it will return 403 HTTP responses to requests to send or delete messages. The API will continue to support retrieval of a user's contacts or inbox for around six months after that date. After that time, the API will return an empty list in response to requests to retrieve those feeds.

March 4, 2014

This update contains the following changes:

  • This API has been officially deprecated. API functionality will continue to work as per our deprecation policy, but we encourage you to migrate to the new YouTube Data API (v3) as soon as possible.

    While the v3 API offers the majority of functionality available in this API (and a lot of other functionality as well), there are still a couple of tasks that can only be completed with this API. Specifically, applications that manage captions or that work with video comments still need to use the v2 API until v3 API equivalents are available.

  • The API's support for retrieving and managing live events has also been deprecated. These features had been explicitly excluded from the list of API features subject to our deprecation policy and are therefore not supported under that policy.

    API requests for retrieving live events are still working at this time. API requests to create, update, or delete live events return a 403 HTTP response code.

    We recommend that you transition your application to use the YouTube Live Streaming API to create and manage live events and the YouTube Data API (v3) to search for live events. In the Data API, the search.list method's eventType parameter lets you restrict a search to only return either active, upcoming, or completed broadcast events. That API supports other features to help you find and feature live broadcast content, which are explained in the API's release notes for October 24, 2013.

November 6, 2013

This update contains the following changes:

  • YouTube is switching to a new commenting system. As part of this change, you may need to modify some API calls related to comments. Please note the following changes:

    • The new commenting system, which is powered by Google+, supports threading for comments made through that system. With the new system, comment replies are retrieved using the Google+ API's comments:list method. See the article that explains changes to comments in the API for more details.

    • The API no longer supports the ability to add a comment as a reply to an existing comment, though it does still support the ability to add a comment to a video.

    • The API no longer identifies comments that were originally submitted as replies to other comments. Comments that were submitted as replies to other comments now appear as regular comments in an API feed.

    Please review the upcoming changes to comments for a complete explanation of the changes.

September 30, 2013

This update contains the following changes:

  • The API's support for YouTube Insight data has been officially deprecated as of September 30, 2013. This functionality will continue to work as per our deprecation policy, but we encourage you to migrate to the new YouTube Analytics API as soon as possible. If you are building a new application, use the YouTube Analytics API to get the most comprehensive set of API features related to the YouTube Analytics data.

September 12, 2013

This update contains the following changes:

  • All standard video feeds except the most_popular feed have been deprecated. In response to requests for other feeds, the API will return the most_popular feed with a default time parameter value of today. The most_popular feed also supports a time parameter value of all_time, so if you try to retrieve a deprecated feed for that time period, the API will return a feed of the most popular videos of all time. In addition, if your request for another feed specifies a region or category, the API will return the most_popular feed for that region or category.

  • YouTube's video responses feature has been retired as explained in this announcement. While existing video responses are still available, YouTube no longer supports the ability to retrieve a list of video responses for a video, to upload new video responses, or to delete video responses, though you can delete the video that was used in a video response. Consequently, these functions are also no longer supported in the API, and API requests for these operations now return the following responses:

    • A request to retrieve video responses for a video returns an empty list.
    • A request to add a video response returns a 403 HTTP response code.
    • A request to delete a video response returns a 403 HTTP response code.

May 10, 2013

This update contains the following changes:

April 15, 2013

This update contains the following changes:

  • The location-radius parameters have both been updated to reflect the fact that they are temporarily disabled. See the API issue tracker for more information about the status of both parameters.

  • The feature that upgrades an unlinked Google Account to associate it with a YouTube channel has been deprecated. The related API feed that retrieves a list of suggested YouTube channel names based on a user-provided hint has also been deprecated along with the hint parameter that specifies the hint.

    As an alternative, applications running on mobile devices and other installed applications can spawn a WebView or similar object where the user can create a YouTube channel. Learn more.

September 20, 2012

This update contains the following changes:

  • The new channel suggestions feed identifies channels that may appeal to the user. YouTube recommends channels to a user based on an algorithm that considers signals from a variety of sources that include the user's subscriptions, favorite videos, ratings, and more.

September 19, 2012

This update contains the following changes:

  • The definition of the time parameter has been updated to note that the only supported parameter values in requests for the most_popular standard feed are today and all_time.

  • The sample show feed entry has been updated to reflect new image sizes that the API may return for shows. The new image sizes include a 243px by 432px (16:9) image for the show as well as 300px by 300px and 600px by 600px versions of the show's square artwork.

September 6, 2012

This update contains the following changes:

  • The most_popular and most_recent trailer charts have been deprecated and will now return empty feeds. Since those were the only two supported feeds for trailers, the Retrieving a trailer chart section has been removed from the documentation.

August 30, 2012

This update contains the following changes:

August 23, 2012

This update contains the following changes:

  • The YouTube EDU feeds are no longer labeled as experimental features.

  • The orderby parameter now supports a value of reversedPosition for playlists, including watch later feeds, which are a type of playlist.

  • The Subscriptions section has been updated to explain that a subscription feed entry contains a <yt:channelId> tag, which identifies the channel associated with the subscription, and a <yt:username> tag, which identifies the display name for the user or channel associated with the subscription.

    In addition, the sample subscription entries have been updated to reflect the presence of the <yt:unreadCount> tag. This new tag shows the amount of activity for the subscribed-to channel since the last time the user was logged in and filtered to that channel via the YouTube channel guide. The guide displays on the YouTube home page.

  • Activity feed entries can now contain a <yt:groupId> tag, which identifies user events in an activity feed that are associated with the same user and resource. For example, if a user rates a video and marks the same video as a favorite, the entries for those events would have the same <yt:groupId> value in the user's activity feed. In your user interface, you can avoid repetition by grouping events with the same <yt:groupId> value.

  • The sample video entry in the Understanding video feeds and entries section has been updated to accurately reflect the elements that appear in a video entry.

August 10, 2012

This update contains the following changes:

  • The standard video feeds section has been updated to reflect the fact that the deprecated most_viewed feed will now return the same content as the most_popular feed. We recommend that you update your code to use the most_popular feed instead of the most_viewed feed.

  • The user activity feeds section now indicates that all requests to retrieve activity feeds must specify a developer key. This update corrects an inaccuracy in the documentation and does not reflect an actual change in API behavior.

  • The list of special metadata fields in episode (and clip) entries has been updated to reflect that those entries now contain a <link> tag that provides the URL of the season entry associated with the video.

August 1, 2012

This update contains the following changes:

  • The API now supports region-specific standard video feeds for Belgium (country code BE), Chile (CL), Colombia (CO), Egypt (EG), Jordan (JO), Malaysia (MY), Morocco (MA), Peru (PE), Philippines (PH), Saudi Arabia (SA), Singapore (SG), and the United Arab Emirates (AE).

July 23, 2012

This update contains the following changes:

  • Channel search result feeds have been updated to include the following additional tags:

    • The new <yt:channelId> tag appears in channel search result entries and contains a value that uniquely identifies the channel.

    • The <yt:channelStatistics> tag specifies the channel's subscriber count and total view count.

    • The <media:thumbnail> tag contains a thumbnail image for the channel.

  • The documentation no longer states that subscription activity feeds will only return up to 25 events as the feed can return more events that that. The total number of events included in the feed may be limited, however.

  • The most_viewed standard video feed has been deprecated. We recommend that you use the most_popular feed instead.

    Queries for the most_viewed feed may return an empty feed, and if the API does return a feed, the entries may not actually represent the most frequently viewed videos.

July 19, 2012

This update contains the following changes:

July 18, 2012

This update contains the following changes:

  • The new YouTube EDU section explains how to use the API to retrieve information about the lectures (videos), courses, and subjects accessible through YouTube EDU.

    In addition, the definition of the category parameter has been updated to explain how to retrieve a list of courses or lectures associated with a particular YouTube EDU category. The API also now supports the course parameter, which can be used to retrieve lectures associated with a particular course that is accessible via YouTube EDU.

July 10, 2012

This update contains the following changes:

  • Documentation for the deprecated OAuth 1.0, AuthSub, and ClientLogin authentication methods has been moved within the guide to a new page that lists deprecated API features. This update does not reflect a change in functionality but just intends to underscore the fact that those authentication methods have been deprecated. Existing applications should use OAuth 2.0 authentication instead, and new applications using the API should also use OAuth 2.0.

June 5, 2012

This update contains the following changes:

  • The definition of the restriction parameter now explains that the parameter enables the API server to identify the end user's location and apply geographic restrictions based on that location. The definition also notes that a failure to set this parameter's value could cause the API server to apply country restrictions incorrectly by, for example, basing restrictions on the location of your server rather than on the end user's actual location. Finally, the definition points out that YouTube API Terms of Service prohibit lying about an end user's location to circumvent these restrictions.

  • The Deleting a comment section has been updated to note that a comment may be deleted by either the comment's author or the owner of the video associated with the comment.

  • The new Deleting videos from the watch history feed section explains how to delete an individual video from a user's watch history feed as well as how to clear the contents of that feed.

May 2, 2012

This update contains the following changes:

  • The documentation for steps 2 and 4 of the OAuth 2.0 authentication for installed applications has been updated to emphasize that if you are using urn:ietf:wg:oauth:2.0:oob as the redirect_uri to retrieve an access token, your application should not make assumptions about the number of parameters in the parameter string or about the length of the token. Instead, your application should extract the token from the page title of the page returned in step 4 of the instructions.

    To parse the token, your application should assume that everything that follows the last space character in the page title is a parameter string in the format x=a&y=b. Your code should parse the parameters from that substring, looking for a code= or error= assignment to indicate that the page contains the final title string and the sign-in flow is complete. If the page title assigns a value to the code parameter, then that value is the token.

April 27, 2012

This update contains the following changes:

  • The Authentication section as well as the sections explaining OAuth 1.0, AuthSub, and ClientLogin authentication have all been updated to note that those three authentication schemes have been officially deprecated as of April 20, 2012.

    OAuth 2.0 is the recommended authentication scheme for applications that use the YouTube API. If you have an application that uses another authentication scheme, we recommend that you update it to use OAuth 2.0

  • Sample requests throughout the documentation have been updated to show the syntax for the OAuth 2.0 authentication scheme. OAuth 2.0 is the recommended authentication scheme for the YouTube API.

  • The API now supports region-specific standard video feeds for Hungary (country code HU).

  • The Adding a complaint section has been updated to reflect the addition of CHILDABUSE as a valid complaint type.

  • The Contacts section has been updated to reflect the fact that a user can only retrieve her own contacts feed and must be logged in to do so.

  • The documentation has been updated to reflect the fact that the YouTube website no longer classifies contacts into subgroups, such as 'friends,' and that, consequently, API functions to support contact subgroups are also now obsolete.

    Specifically, the API no longer supports an access control setting for comments to let a user specify different comment permissions for 'friends' than for other users. In addition, the API no longer includes friend_added events in activity feeds.

April 19, 2012

This update contains the following changes:

  • The new Handling usernames and display names in your application section discusses rules that your application should follow to properly handle usernames and display names. These rules were also explained in the YouTube, Google+, the API, and You post on the YouTube API blog (March 15, 2012).

    To briefly summarize the changes, your application should use the <yt:userId> tag value to uniquely identify a user, and it should use the <yt:username> tag's display attribute value to display a username in a user interface.

  • Sample feeds throughout the document have been updated to reflect the addition of the new <yt:userId> tag as well as the <yt:username> tag's new display attribute and the <media:credit> tag's new yt:display attribute. The new tag and the new attribute both contain values that are crucial to the proper handling of usernames and display names.

  • The activity feeds section has been updated to explain the availability of subscription activity feeds, which identify actions associated with the authenticated user's subscriptions. Subscription activity feeds replace friend activity feeds, which are no longer supported. If you try to retrieve a user's friend activity feed, the API will instead return that user's subscription activity feed.

March 16, 2012

This update contains the following changes:

  • The hl query parameter is now supported for retrieving movie charts. The parameter's value is an ISO 639-1 two-letter language code.

  • In addition to mentioning support for the hl query parameter, the movie charts section also provides the URLs for retrieving the top selling or top free movies listed on http://www.youtube.com/movies.

March 14, 2012

This update contains the following changes:

  • The sections discussing the user uploaded videos feed and the API's supported custom query parameters have both been updated to explain that you should not include search query parameters in requests to retrieve an uploaded videos feed. By doing so, you are instructing the API to generate a feed from YouTube's search index, effectively restricting the result set to indexed, public videos rather than retrieving a complete list of the user's uploaded videos.

  • The new Shows, seasons, and episodes section explains several new API features related to videos in YouTube's Shows category. This category includes content for television shows as well as original Web shows.

    • The API now supports feeds for shows and seasons:

      • A shows feed contains a list of show entries, each of which describes a show. Each show is associated with one or more seasons.
      • A seasons feed lists seasons for a particular show. Each season is then associated with either full episodes of the show, video clips from the show, or a combination of episodes and clips.
    • Video feed entries for shows content, including episodes and clips, will now contain several additional metadata fields. Episode and clip entries are both types of video feed entries and could be returned in any feed that contains video entries, including search results.

    • The Show charts section explains how to retrieve charts, or standard feeds, for the most popular and most recently updated shows. This section also explains how to use the genre and region parameters when retrieving show charts.

  • The query parameter definitions section also now mentions that the region and genre parameters can be used to retrieve show charts. The genre parameter is new and specifies the genre of shows in the feed.

  • The new Deleting a comment section explains how to delete a comment for which the authenticated user is the author.

February 23, 2012

This update contains the following changes:

  • The Displaying a list of videos and Displaying information about a video sections have been updated to reflect more recent versions of the YouTube search results and video watch pages.

  • A best practice for developers working with the API is to use the term default in an API request URL rather than a username when performing an authenticated operation that requests a feed associated with the currently authenticated user. Any examples that did not already reflect this practice have been updated to do so.

  • The 'Developer's Guide adviser,' which had been designed to let you customize the YouTube API documentation to meet the needs of your application, is no longer supported.

February 2, 2012

This update contains the following changes:

  • The watch history feed section has been updated to note that if a user who had a YouTube login cookie watched embedded videos on websites other than YouTube, those videos would also be listed in the watch history feed. (This change does not alter the fact that videos watched on mobile devices are not included in the feed.)

  • The uploading videos section has been updated to no longer indicate that accounts can upload a maximum of 2000 videos.

  • The Understanding the YouTube event lifecycle section has been updated to include a link to YouTube's recommended encoding specifications for live video streams.

  • The Retrieving category-specific standard channel feeds section has been removed from the documentation as the API no longer supports the ability to retrieve those feeds.

January 5, 2012

This update contains the following changes:

  • The new watch history feed lists videos that a specified user has watched on the YouTube website. (It does not include videos watched 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.

December 20, 2011

This update contains the following changes:

  • The About this documentation section has been updated to include a definition of the term experimental feature, which is a feature that is still in development and subject to change without notice. Experimental features are not subject to the API's deprecation policy.

    In addition, the documentation has been updated to more clearly identify experimental features. All experimental features are marked with a blue flask icon (This icon identifies experimental features and is shown in this release note, which discusses the manner in which experimental features are identified in the documentation.).

    The following features are currently labeled as experimental:

  • The Batch processing section has been updated to note that submitting requests in a batch does not affect your API quota usage and, therefore, does not affect the likelihood that your application will exceed YouTube's limits on API calls. In addition, that section also now notes that some of the API's client libraries may not support batch processing.

December 19, 2011

This update contains the following changes:

  • The new supported API feeds section lists the different types of feeds and feed entries that you can retrieve using the YouTube Data API. It also provides a very brief description of each feed. This new section intends to provide developers with a more thorough overview of the functionality available in the API and to help them to more easily locate information about the API features they want to implement.

  • The retrieving a movie chart section has been updated to note that the paid-content parameter is now optional in a request to retrieve the trending movies feed.

December 14, 2011

This update contains the following changes:

  • The video responses section has been updated to explain that if a video was uploaded as a video response, then its video entry will contain a <link> tag that points to the video that it responded to.The <link> tag's rel attribute will have a value of in-response-to.

December 9, 2011

This update contains the following changes:

  • The new Managing live events section explains how to use the API to add, update, and delete live events. Since this functionality is not available to all YouTube users or to all API developers, please read the prerequisites for managing live events before integrating these features into your application.

November 30, 2011

This update contains the following changes:

  • The new OAuth 2.0 section explains how to use the OAuth 2.0 protocol to authorize access to private user data. It includes separate instructions for integrating OAuth 2.0 authentication into server-side web applications, client-side web applications, installed applications, and devices.

  • API version 2.1 now supports two additional operations for users who have unlinked Google Accounts. (These accounts are also discussed in the release notes for October 7, 2011.) Those two operations are described below:

    1. You can upgrade an unlinked Google Account to also be associated with a YouTube username. This operation also provisions a YouTube channel with the same name for that user.

    2. Before actually attempting to associate a user's unlinked Google Account with a new YouTube channel, you can retrieve a feed of unused YouTube usernames that are similar to a hint that you provide.

    In light of these new features, the User profiles section has been renamed User profiles and accounts.

  • The new hint parameter can be used to retrieve a list of available YouTube usernames similar to the parameter value. You would use this parameter if your application enabled a user with an unlinked Google Accounts to upgrade that account so that it would be associated with a YouTube username (and channel).

  • The definition of the <yt:username> tag has been updated to explain that in a request to upgrade an unlinked Google Account to be associated with a YouTube username (and channel), that tag specifies the YouTube username that the user would like to have.

October 28, 2011

This update contains the following changes:

  • The Retrieving Insight data section has been updated to explain that you can adjust the date range for which an Insight report contains data to a period of up to 31 days beginning no earlier than March 1, 2009.

October 17, 2011

This update contains the following changes:

  • The Live events section has been updated to reflect the fact that the API supports live events in production and not just on our staging server. However, please note that this is still an experimental feature.

  • The Troubleshooting common API challenges section has been updated so that it no longer includes the Using "public" and "private" video URLs subsection. That section had indicated that you could only retrieve uncached information for a video by retrieving the video entry from the video owner's uploaded videos feed. However, the API no longer uses different caching rules for uploaded videos feeds.

  • The Updating a video entry section has been updated to emphasize that when updating a video, you need to retrieve the entry from the video owner's uploaded videos feed.

October 7, 2011

This update contains several changes related to API version 2.1, a new minor API release designed to provide support for authenticated users who have a Google Account but who do not have a YouTube channel. 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. In this documentation, these Google Accounts are referred to as unlinked Google Accounts.

In API version 2, requests that require user authentication are only supported for users who have YouTube accounts. (A YouTube account provides a user with a YouTube channel.

However, on YouTube.com and in API version 2.1, some functions that require user authentication are also supported for unlinked Google Accounts. These changes are reflected in the following updates:

  • The API Versioning section has been updated to explain that API versions 2 and 2.1 are now both officially supported. This section now explains the difference between YouTube accounts and unlinked Google Accounts and the fact that API version 2 only supports YouTube accounts while API version 2.1 supports both account types.

  • A new section, Comparing API versions 2 and 2.1, explains the specific differences between the two API versions.

    • It explains the difference in error responses between the two API versions when a user with an unlinked Google Account attempts an operation that requires authentication.

    • It lists the API features that are and are not supported for users with unlinked Google Accounts.

    • It explains how a user profile entry for a user with an unlinked Google Account differs from a user profile entry for a user with a YouTube account.

  • The Error responses section has been updated to explain the youtube_signup_required service error. This error is returned in API version 2.1 when a user with an unlinked Google Account submits an API request that requires the authenticated user to have a YouTube channel.

October 6, 2011

This update contains the following changes:

  • The API query parameters section includes the following new parameters:

    • The duration parameter lets you filter search results based on video length.
    • The hd parameter lets you restrict a search to only include HD videos, meaning videos that are available for playback in at least 720p.
    • The license parameter lets you filter search results to only include videos with a particular license.
  • The 3d parameter's definition has been updated to note that true is the only supported parameter value and that false is not a valid parameter value. The API's default behavior, which occurs when the 3d parameter is omitted from a search request, is to include both 3D and non-3D videos in search results.

  • The format parameter's definition has been updated to explain that the parameter value lets you specify multiple, comma-separated formats. The API will return videos available in at least one of the specified formats. For example, format=1,5 indicates that the API should return videos that are available in at least one of those two formats.

  • The Video recommendations section has been updated to note that a request to retrieve a user's recommendations feed must specify a developer key. The API will return a 403 Forbidden response if no developer key is specified in such a request.

September 30, 2011

This update contains the following changes:

  • The Playlists section has been updated to explain how to retrieve and update a user's Watch Later playlist. It also explains the conditions that determine whether that list can be retrieved or updated. YouTube's 'Watch Later' feature lets users save videos to watch at a later time. Even though the list is stored as a playlist, it is not included in a user's playlist feed.

  • The Adding a video to a playlist section has been updated to note that you can now send a single request to add a video to a playlist and specify the position where the video should appear in that list. Previously, you needed to add the video to the playlist, and then update the playlist entry to specify the desired playlist position.

August 30, 2011

This update contains the following changes:

August 9, 2011

This update contains the following changes:

  • The height and width reported in the <media:thumbnail> tag now reports a width of 480 and a height of 360 for the 0.jpg and hqdefault.jpg images. Other thumbnail images are still 120x90.

  • The Retrieving a single live event section has been updated to note that if a video is associated with a live event, then the video entry will contain a <link> tag that points to the live event entry.

  • The documentation has been updated to reflect the fact that the API now supports HTTPS for all upload requests and all requests to the staging server:

    • Requests to upload videos to the production API servers should be sent to https://uploads.gdata.youtube.com.
    • Requests to upload videos to the staging server should be sent to https://uploads.stage.gdata.youtube.com.
    • All other requests to the staging server should be sent to https://stage.gdata.youtube.com.

July 21, 2011

This update contains the following changes:

  • The new 3d parameter lets you restrict a search to only retrieve 3D videos. You can restrict a search to only retrieve 3D videos by setting the parameter value to true or by including the parameter in a request without specifying a parameter value. The parameter is also supported for related videos feeds and standard feeds.

July 19, 2011

This update contains the following changes:

  • The Contacts section has been updated to reflect the fact that contact groups have been deprecated on the YouTube website. Previously, an API request could contain a <category> element, which could add a contact to a group, such as "Family" or "Friends." Now, if an API request uses a <category> tag to specify a contact group, that tag will be ignored when the request is handled.

June 24, 2011

This update contains the following changes:

  • The new Live events section explains how to retrieve feeds of events that were broadcast, are being broadcast, or will be broadcast on YouTube as they occur. This section explains how to retrieve live event charts, which are standard feeds listing live events that are either featured, upcoming, currently live, or recently broadcast. It also explains how to retrieve a user's live events feed, which lists events created by that user.

    Note: Live event feeds are experimental API features, which mean they may change unexpectedly. Live event feeds are currently only supported on our staging server.

  • The API query parameters section has been updated to list five new parameters that can be used when retrieving live event feeds: starts-before, starts-after, ends-before, ends-after, and status. In addition, the inline and time parameter definitions have been updated to explain how to use those parameters when retrieving live event feeds.

June 17, 2011

This update contains the following changes:

  • The API documentation has been updated to reflect the fact that the API supports HTTPS for nearly all API requests. If you send an API request to https://gdata.youtube.com, then the API response will also specify HTTPS URLs in element values that point to other API feeds.

    However, please note that HTTPS is not supported for the following requests:

    • Requests to upload videos to the production API servers should still be sent to http://uploads.gdata.youtube.com.
    • Requests to upload videos to the staging server should still be sent to http://uploads.stage.gdata.youtube.com.
    • All other API requests to the staging server should still be sent to http://stage.gdata.youtube.com.

    In addition, note that AuthSub and OAuth authentication tokens for the http://gdata.youtube.com and https://gdata.youtube.com scopes are interchangeable. As such, if you have already obtained an AuthSub or OAuth token for the http://gdata.youtube.com scope, you can use that same token to authenticate requests to https://gdata.youtube.com.

June 10, 2011

This update contains the following changes:

  • The new Movies and trailers section explains several new API features related to videos in YouTube's Movies and Trailers categories.

    • Feed entries for movies and trailers will now contain several additional metadata fields. Movie and trailer entries are both types of video feed entries and could be returned in any feed that contains video entries, including search results.
    • The Retrieving a movie chart subsection explains how to retrieve movie charts, or standard feeds, for the most popular movies, the most recently added movies, and the trending (or top) movies on YouTube. This section also explains several new query parameters – movie-genre, paid-content, and region – that the movie charts support.

March 11, 2011

This update contains the following changes:

March 9, 2011

This update contains the following changes:

  • The Retrieving Insight data section has been updated to reflect the fact that a profile entry will now contain a link to an Insight report for a channel if an authenticated user is retrieving her own profile. The section also lists and defines the reports and fields that a channel report contains.

  • The Retrieving Insight data section has also been updated to explain the data included in two additional reports for videos.

    • One report indicates whether video views occurred on YouTube channel pages, YouTube watch pages, YouTube's mobile website, or other websites or applications.
    • The other report explains the referrers for a video's views and the number of views that originated from each referrer. For example, a referrer could be a YouTube search page, a related video link, or another website.

March 3, 2011

This update contains the following changes:

  • The Retrieving Insight data for a video section has been updated to explain how you can adjust the date range for which an Insight report contains data. With this change, you can retrieve Insight data for a video for a period of up to 28 days.

February 28, 2011

This update contains the following changes:

  • The API now lets you retrieve two new standard feeds, both of which are available as experimental features:

    • The most_shared feed lists the YouTube videos most frequently shared on Facebook and Twitter.
    • The on_the_web feed lists trending videos as seen on YouTube Trends, which surfaces popular videos as their popularity is increasing and also analyzes broader trends developing within the YouTube community.
  • The watch_on_mobile feed has been removed from the list of supported standard feeds.

  • The definition of the fmt parameter, which is used to specify the return format for a caption track retrieved via the API, has been updated. Previously, this parameter was required if you were retrieving a caption track generated using automatic speech recognition (ASR). Now, if you retrieve a track generated using ASR and do not set a fmt parameter value, the API will return the track in Subviewer-compatible format.

  • The Providing captions for a video section has been updated to describe several new features and updates:

    • The new Uploading a video transcript without caption timecodes section explains that if YouTube's Timed Text Service (TTS) 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 description of the Slug header, which specifies a caption track's title, has been updated to explain that the value should be URL-escaped and to explain how to specify non-ASCII characters in a track title.

      The description has also been updated to reflect the fact that the API server will no longer automatically assign a caption track title if you do not provide one. This change lets the client application choose how to identify such tracks. Since many user interfaces display track titles and languages, this change prevents tracks from displaying with titles like English: English.

    • The Retrieving a caption track section has been updated to explain the caption file format that YouTube returns when you retrieve a caption track that YouTube synchronized to your video. Specifically, you can use the fmt parameter to specify the format in which the track should be returned, but if you do not specify a format, the API will return the original transcript that you uploaded.

January 31, 2011

This update contains the following changes:

  • The Standard feeds section has been updated to more accurately describe the frequency with which standard feeds are updated.

  • The Technical requirements for uploaded videos section has been updated to reflect the fact that the maximum size for uploaded videos has increased from 2 GB to 64 GB. In addition, many users who have a history of complying with the YouTube Community Guidelines are now allowed to upload videos longer than 15 minutes, though not all users have that capability.

December 14, 2010

This update contains the following changes:

  • The caption parameter's definition has been updated to note that you can restrict a search result set to only include videos that do not have caption tracks by setting the parameter value to false. (To restrict a result set to only include videos that have caption tracks, set the caption parameter value to true or include the caption parameter in your request but do not specify a parameter value.)

  • The Assigning developer tags section has been updated to explain that an individual developer tag must be at least three bytes long and cannot be longer than 25 bytes. In addition, the total length of all developer tags cannot exceed 240 bytes.

  • The Using the staging server section has been updated to explain that the default API version used on the staging server is now version 2. As such, you do not need to use the v parameter or the GData-Version HTTP request header to use version 2 of the API on the staging server. However, you do still need to use the v parameter or the GData-Version HTTP request header to use version 2 of the API on the production API servers.

October 28, 2010

This update contains the following changes:

  • The Retrieving and searching for channels section contains a new subsection, Standard feeds for channels, that explains how to retrieve feeds listing channels with the most viewers or subscribers. The new section also explains how to retrieve region-specific, category-specific, or user-type-specific (musician, comedian, etc.) standard channel feeds. In a standard channel feed entry, the <yt:channelStatistics> tag contains statistics like the number of videos uploaded to the channel and the total number of views for all of the channel's uploaded videos.

    Note: Standard channel feeds are only supported in version 2 of the API.

  • The time parameter's definition has been updated to note that the parameter can be used when retrieving standard channel feeds. (The API does not generate a feed of the most subscribed channels for the previous day, so the only supported time parameter values for that feed are this_week, this_month, and all_time.

October 26, 2010

This update contains the following changes:

  • The ClientLogin for installed applications section has been updated to reflect a change to the URL that you use to request an authentication token. The old URL has been deprecated in accordance with the deprecation policy explained in our Terms of Service. The new URL is:
    https://www.google.com/accounts/ClientLogin
    The changes also reflect the fact 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. For example, the following URL will retrieve a feed of videos uploaded by the currently logged-in user:
    http://gdata.youtube.com/feeds/api/users/default/uploads
  • The Technical requirements for uploaded videos section has been updated to indicate that videos may be up to 15 minutes long.

  • The Retrieving region-specific standard video feeds section has been updated to note that region-specific feeds are now supported for Argentina (AR) and South Africa (ZA).

October 20, 2010

This update contains the following changes:

September 16, 2010

This update contains the following changes:

  • The Providing captions for a video section now indicates that YouTube may use automatic speech recognition (ASR) to generate a caption track for a video. In a caption tracks feed entry, the <yt:derived> tag will be present and have a value of speechRecognition if YouTube generated the caption track using ASR.

    The sample caption tracks feed in the Retrieving a list of available caption tracks section now contains an additional entry that shows how an ASR track would appear in a caption tracks feed.

  • The fmt parameter definition has been updated to note that you must specify a value for that parameter if you are retrieving a caption track generated using ASR.

  • The API versioning section has been updated to note that the current API version is 2 and that using the most current version allows your application to access API features that are not available in older versions. For example, captions, partial responses, and partial updates are all supported in version 2 of the API but are not supported in version 1.

  • The Adding a rating section has been updated to note that if you include a like rating (or a dislike rating) and a numeric rating in a request to add a rating, YouTube will ignore the numeric rating. (If the <gd:rating> tag, which specifies the numeric rating, or one of its attributes specifies an invalid value, the request will generate an error.)

September 2, 2010

This update contains the following changes:

  • The Subscriptions section has been updated to reflect the fact that YouTube no longer supports subscriptions to playlists.

  • The examples for partial updates section have been updated to show the correct value for the Content-Type header in a PATCH request, which is application/xml. Previously the examples showed an incorrect Content-Type header value of application/atom+xml.

August 31, 2010

This update contains the following changes:

  • The Providing captions for a video section has been updated to reflect the following changes:

  • The <yt:statistics> tag's new totalUploadViews attribute specifies the total number of views for all of the user's videos.

  • The examples in the Retrieving a partial response section reflect a change to the query syntax for retrieving partial responses, which is an experimental API feature. The change affects the way that the API handles an element's text content in a partial API response and impacts queries that use parentheses to specify that the API should only return text content for an element or text content and a limited set of attributes for that element.

    Prior to the change, an element's text content would always be included in an API response. Following the change, you must specify that an element's text content should be included in the API response in the same way that you would identify the attributes (or child elements) to be included in the response. The following examples illustrate this change:

    • Under the old syntax rules, the following request returns the <media:category> element's text content and label attribute:
      fields=entry(media:group(media:category(@label)))
      However, under the new syntax rules, the request above only returns the <media:category> element's label attribute. To also retrieve the text content, you must explicitly request it:
      fields=entry(media:group(media:category(@label,text())))
    • Under the old syntax rules, the following request retrieves the <media:category> element's text content:
      fields=entry(media:group(media:category()))
      However, under the new syntax rules, that request returns an empty <media:category> element. Again, you must explicitly specify that the response should include the tag's text content:
      fields=entry(media:group(media:category(text())))

    To prevent existing applications from breaking, we are introducing this change in two phases:

    1. For the time being, text content will continue to be returned in feed responses even if it is not explicitly requested.

      In the meantime, you can determine whether this change will affect your existing applications by adding the fields-language parameter to your API requests with a value of r2. That parameter will force the API server to apply the new syntax rules, enabling you to identify affected areas of your application.

      We encourage you to test your application and fix any issues that arise from this change.
    2. 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.
  • When retrieving a partial response, you can now filter results based on the presence of an element that does not contain text content. This change represents a fix to the partial response feature. For the time being, to use this feature, you must set the fields-language parameter value to r2. For example, the following example only returns entries that contain the <app:control> tag, which has subtags but does not contain text content:

    http://gdata.youtube.com/feeds/api/users/default/uploads?fields=entry[app:control]&fields-language=r2

    Again, following a testing period, the new behavior will apply to all requests for partial API responses, and the API server will ignore the fields-language parameter.
  • The Retrieving Insight data for a video section has been updated to reflect the contents of the Insight reports that can be retrieved for a video. Specifically, the Referrers that had been described in the documentation is no longer returned. Instead, YouTube returns a Demographics report, which provides a demographic breakdown of the viewers who have watched a video. Note that the link to retrieve the Insight reports only appears in a video entry if the authenticated user retrieving the entry owns the video.

July 20, 2010

This update contains the following changes:

  • Examples in the Uploading videos, Updating and deleting videos, and Partial updates sections have been updated to reflect a new access control setting that indicates whether a video is unlisted. Unlisted videos are not included in search results or displayed in any other way, and a user can only reach an unlisted video by entering or linking directly to the video's watch page URL.

  • The Retrieving an activity feed section has been updated to note that activity feeds only contain video_rated entries for videos that were given like ratings. As such, videos that were given negative (dislike) ratings no longer appear in activity feeds.

    This section has also been updated to note that activity feed entries for video_rated events include the <yt:rating> tag in addition to the <gd:rating> tag.

July 7, 2010

This update contains the following changes:

June 28, 2010

This update contains the following changes:

  • In May 2010, we updated the release notes to state that the API changes supporting YouTube's new video rating system had been released to our production API servers. However, the Ratings section still included a note, which should have been removed, indicating that the feature was still not available on production servers. As previously announced, the <yt:rating> element is available in production API responses, and the note stating otherwise has now been removed.

June 24, 2010

This update contains the following changes:

  • The Contacts section has been updated. Previously, this section stated that you do not need to submit an authenticated request to retrieve a user's contact list. While this statement is true, the API will only return the contact list for users who display the Friends module on their channel pages. If you submit an unauthenticated request to retrieve the contacts list for a user who does not display the Friends module on his channel page, the API will return a 403 (Forbidden) HTTP response.

  • The Subscriptions section has been updated to reflect the fact that YouTube no longer supports subscriptions to a user's list of favorite videos or to a keyword search.

May 26, 2010

This update contains the following changes:

  • The ClientLogin section has been updated to explain that when supplying login credentials for a user, you can use any 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.

May 12, 2010

This update contains the following changes:

  • The metadata requirements for newly uploaded videos have changed so that the only required fields for a new video are category and title.

    In addition, you can include the new <yt:incomplete> element in your upload request to instruct YouTube to automatically generate certain metadata values if they are not otherwise specified in the upload request. If your request includes the <yt:incomplete> element, YouTube will automatically generate a title for the video and associate the video with a category even if that information is not included in the video metadata. See the new Metadata requirements section for uploaded videos for more information.

    Finally, you can upload videos using the resumable uploading process and upload videos without any metadata. In such cases, YouTube will handle the request as if it contained an entry that only included a <yt:incomplete> element.

    The new Updating a video with incomplete metadata section explains requirements for updating a video that was originally uploaded with incomplete metadata.

  • The new inline query parameter lets you specify that an activity feed entries for events that involve videos, such as video_rated and video_uploaded events, should include an embedded video entry that contains information about that video. The default parameter value is false. See the Using the inline parameter section for more details.

  • The API changes announced on April 12, 2010, that support YouTube's new video rating system have been released to our production API servers.

April 12, 2010

This update contains the following changes:

  • The ratings section has been updated to explain how the API will support the new video rating system released on YouTube in March 2010. In the new system, users rate a video by indicating whether they like it or dislike it. (In the old rating system, users rated a video on a 1-5 scale.)

    Note: The API changes that support the new rating system are currently released to our staging server but have not yet been released to our production API servers. As such, you should not yet update production applications to either require API responses to contain the <yt:rating> element or to submit ratings using that element. However, you can test the new functionality on the staging server and then update your applications once the feature is released to the API production servers.

March 22, 2010

This update contains the following changes:

  • The new Retrieving a partial response section explains how to submit an API request in which you specify the fields that you want to be included in the API response. By only requesting the information that it will actually display, your application can more efficiently use network, CPU and memory resources. The new section explains how to use the fields parameter to submit requests for partial feeds and also describes the format of the API responses to those requests.

  • The new Submitting partial update (PATCH) requests section explains how to send a PATCH request to only update specific metadata fields for an entry in a YouTube API feed. You can send a single PATCH request to add, replace, and/or delete specific fields for a particular resource.

  • The Using a developer key section has been updated to reflect two changes:

    • The description of a developer key has been updated to correctly reflect that the key should uniquely identify a product submitting an API request.
    • The use of client IDs has been deprecated. As such, the X-GData-Client request header and the client request parameter have been deprecated. Examples throughout the documentation have also been updated to no longer provide client ID information. We will continue to support requests that submit client IDs in accordance with the deprecation policy explained in our Terms of Service.

March 3, 2010

This update contains the following changes:

  • The new Resumable uploads 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.

February 17, 2010

This update contains the following changes:

  • The Setting access controls for a video section explains how to set access controls when uploading a video. Access controls specify whether users are allowed to rate a video, add comments about the video, rate comments about the video, add a video response to the video, or embed the video on third-party websites. Another setting indicates whether YouTube can show the video on Youtube properties other than the YouTube.com website. Access controls are returned in the <yt:accessControl> element in API responses, and a video owner can also update the access control settings for her videos.

January 29, 2010

This update contains the following changes:

  • The YouTube API now supports JSON-C as a response format. The Developer's Guide for JSON-C/JavaScript explains the format of the JSON-C feeds and how to request and process those feeds. The API currently supports JSON-C responses for the following types of feeds:

    • Video feeds . This category includes video search results, related videos, user uploads and video responses.
    • Playlist feeds . This category includes playlist search results, feeds that list all of a user's playlists, and feeds that list the entries in a single playlist.
    • Favorite video feeds . This category includes feeds that list a user's favorite videos.
  • The Subscriptions section has been updated to reflect the API's support for a new type of subscription, user activity subscriptions. A user activity subscription provides updates about a variety of activities that a specific user performs on the YouTube site, including uploading videos, rating videos, adding comments and so forth. The Subscriptions section now explains how user activity subscriptions are identified in subscription feeds as well as how to add user activity subscriptions.

  • The orderby parameter now supports a range of values for playlist feeds, allowing you to order playlist entries by playlist position, number of comments, duration, date added to playlist, title, or number of views.

November 5, 2009

This update contains the following changes:

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

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

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

August 31, 2009

This update contains the following changes:

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

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

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

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

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

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

July 29, 2009

This update contains the following changes:

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

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

July 21, 2009

This update contains the following changes:

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

June 17, 2009

This update contains the following changes:

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

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

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

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

April 8, 2009

This update contains the following changes:

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

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

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

March 27, 2009

This update contains the following changes:

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

March 3, 2009

This update contains the following changes:

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

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

February 24, 2009

This update contains the following changes:

  • The new Activity feeds section introduces user activity feeds, which let you retrieve a feed of actions that a particular user or set of users has taken on YouTube. This section also includes information about friend activity feeds, which were released in December.

    The Activity feeds section explains the different types of events that are listed in activity feeds. It also explains how user activity feeds and friend activity feeds are different. Finally, it provides instructions for submitting requests for each feed type.

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

December 10, 2008

This update contains the following changes:

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

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

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

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

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

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

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

November 13, 2008

This update contains the following changes:

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

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

October 20, 2008

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

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

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

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

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

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

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

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

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

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

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

October 3, 2008

This update contains the following changes:

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

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

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

August 18, 2008

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

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

July 16, 2008

This update contains the following changes:

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

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

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

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

June 12, 2008

This update contains the following changes:

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

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

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

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

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

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

May 6, 2008

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

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

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

May 2, 2008

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

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

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

April 7, 2008

This document contains the following changes:

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

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

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

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

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.