Developer's Guide: Data API Protocol – Audience

Note: This page may discuss features that aren't among those that you selected in the documentation adviser. Even though you don't want to implement those features now, we still don't want you to forget about them.

To bookmark these settings or send a link to this customized version of these documents, copy (right-click) the link labeled "link" below the Customized! header in the left navigation menu.

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

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 section describes the two different authentication methods available for associating API operations with a specific user account. This section also outlines the differences between authentication for the YouTube Data API and other Google Data APIs. Throughout this documentation, explanations of specific API functions will clearly indicate whether the function requires user authentication.

• The Understanding video feeds and entries section provides a sample API response and explains how to extract information about a single video from a list of videos or a set of search results. This section also illustrates how the XML elements in a YouTube Data API response correspond to the video information typically displayed on YouTube's website. This section also explains the API request format for updating an individual video entry.

• The Retrieving and Searching for Videos section explains how to fetch a list of videos. The YouTube Data API defines several types of standard feeds, such as top-rated or most-viewed videos. This section also explains how also to retrieve a list of videos uploaded by a specific user or a list of related videos, which are videos that YouTube has determined are similar to a particular video. Finally, this section explains how to use the API to let users search through YouTube's video library for videos matching specific search terms or categories.

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

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

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

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

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

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

API versioning

An API request can specify the version of the API that YouTube should use to handle the request. Your request can specify an API version using either the v parameter or the GData-Version HTTP request header.

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

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

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

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

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

Note: Unless otherwise noted, all of the sample requests in this documentation use the GData-Version request header and demonstrate how to use version 2 of the API. Using the most current version of the API may allow your application to access API features that are not available in older versions of the API. For example, captions, partial responses, and partial updates are all supported in version 2 of the API but are not supported in the now-deprecated version 1.

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

Please note the following characteristics of API version numbers:

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

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

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

Comparing API versions 2 and 2.1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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