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.
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.
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.
Event feeds contain a list of events.
Comment feeds list comments that users have submitted about a specified video.
Subscription and activity feeds
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.
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
defaultto 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=2will 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.
<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
displayattribute 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
displayattribute value will be set to the user's full public display name.
- For accounts that are not connected to Google+, the
displayvalue will be set to the YouTube account name.
<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.
- For a YouTube account that is connected to a Google+ profile, the
In cases where the
<media:credit>tag identifies the YouTube user that uploaded a video, that tag will also have a
yt:displayattribute that specifies the appropriate name to display for that user, while the tag's value will uniquely identify the user.
<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.
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.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:
2allows 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.
2.1enables 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.1in 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.1for users with unlinked Google Accounts. It also explains how API responses in version
2.1are different from the same responses in version
2for 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
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.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.
2returns an HTTP
401response code and the message
NoLinkedYouTubeAccountif a user with an unlinked Google Account attempts any operation that requires authorization.
2.1returns an HTTP
200response code for a subset of the requests that cause a
401 NoLinkedYouTubeAccountresponse in API version
This version also returns an HTTP
403 Forbiddenresponse with a
youtube_signup_requirederror 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_requirederror, 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.
2.1lets 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.1supports the features listed below for users with authorized Google Accounts and should return an HTTP
200response 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 Forbiddenresponse, as described above, for requests related to these features.)
- Uploading videos (or video responses)
- Adding comments
- Identifying favorite videos
- Creating playlists (other than the
- Retrieving personalized video recommendations
- Adding or retrieving contacts
- Sending messages to other YouTube users
- Retrieving their own activity feed
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.