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

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 is divided into 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. The YouTube Data API defines several types of standard feeds, such as top-rated or most-viewed videos. This section also explains how also to retrieve a list of videos uploaded by a specific user or a list of related videos, which are videos that YouTube has determined are similar to a particular video. Finally, this section explains how to use the API to let users search through YouTube's video library for videos matching specific search terms or categories.

• The Uploading videos section briefly explains two ways that you can allow users to upload videos to YouTube from your application. This section also presents process flow diagrams for each upload method and explains how those methods work in conjunction with the authorization scheme that you are using.

  You may need to let users upload videos to use certain other API functions. For example, the API provides a function for adding a video response to a video. However, if the user is uploading a new video as a video response, then your client will need to follow the video uploading instructions to add the video to YouTube before identifying the new video as a response to an existing video.

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

• The Using Community Features section describes API functions that allow your users to interact with YouTube videos. These functions explain requests for posting a rating, comment, video response or complaint to an existing video. You can also use the API to retrieve lists of video comments or video responses or to delete a video response.

• The Saving and Collecting Videos section explains how to use the API to access, create and update favorite videos, video playlists and subscriptions to YouTube channels.

• The Enabling User Interaction section explains how to use the API to retrieve and update user profiles. This section also explains how to retrieve, add, update and delete user contacts.

Supported API feeds

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

• Video feeds contain a list of videos.

  • Video search feeds list videos that match parameter values, such as a query term or video duration.
  • Standard video feeds list videos that either reflect YouTube user behavior or that were selected by YouTube staff. Examples include top-rated, most viewed, and recently featured videos. Movie 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 video responses feed identifies videos that have been explicitly designated as responses to a specified video.
  • A new subscription videos feed identifies videos that were recently uploaded by users that a specified user subscribes to.

• Channel feeds contain a list of channels.

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

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

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

• Event feeds contain a list of events.

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

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

• Subscription and activity feeds

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

• Inbox and contact feeds

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

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

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

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:

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

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

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

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

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

Last updated May 10, 2013.