Printable versionThe 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.
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.
This documentation contains the following sections:
The Authentication section describes the two different authentication methods available for associating API operations with a specific user account. This section also outlines the differences between authentication for the YouTube Data API and other Google Data APIs. Throughout this documentation, explanations of specific API functions will clearly indicate whether the function requires user authentication.
The Understanding video feeds and entries section provides a sample API response and explains how to extract information about a single video from a list of videos or a set of search results. This section also illustrates how the XML elements in a YouTube Data API response correspond to the video information typically displayed on YouTube's website. This section also explains the API request format for updating an individual video entry.
The Retrieving and searching for videos section explains how to fetch a list of videos. The YouTube Data API defines several types of standard feeds, such as top-rated or most-viewed videos. This section also explains how also to retrieve a list of videos uploaded by a specific user or a list of related videos, which are videos that YouTube has determined are similar to a particular video. Finally, this section explains how to use the API to let users search through YouTube's video library for videos matching specific search terms or categories.
The Uploading videos section briefly explains two ways that you can allow users to upload videos to YouTube from your application. This section also presents process flow diagrams for each upload method and explains how those methods work in conjunction with the authentication scheme that you are using.
You may need to let users upload videos to use certain other API functions. For example, the API provides a function for adding a video response to a video. However, if the user is uploading a new video as a video response, then your client will need to follow the video uploading instructions to add the video to YouTube before identifying the new video as a response to an existing video.
The Updating and deleting videos section explains how to enable a user to update or delete his videos.
The Using community features section describes API functions that allow your users to interact with YouTube videos. These functions explain requests for posting a rating, comment, video response or complaint to an existing video. You can also use the API to retrieve lists of video comments or video responses or to delete a video response.
The Saving and collecting videos section explains how to use the API to access, create and update favorite videos, video playlists and subscriptions to YouTube channels.
The Enabling user interaction section explains how to use the API to retrieve and update user profiles. This section also explains how to retrieve, add, update and delete user contacts.
Authentication allows a user to access YouTube features that link content or information to a particular YouTube account. These features require the user or your application to provide the YouTube username and password for that account. For example, a user must log in to YouTube to upload a video or to add a comment to an existing video.
This documentation describes a number of API functions that require user authentication, including all of the API functions for creating, updating or deleting content require user authentication.
Please note that if you implement any functionality that does require authentication, we recommend that you include the proper authentication headers in all of your requests even if those requests do not explicitly require authentication.
To properly authenticate, a request must include the Authorization header and either the X-GData-Key header or the key parameter. The X-GData-Key header (or the key parameter) specifies your developer key, a value that uniquely identifies your application(s). The Authorization header specifies a token that you obtain for each user using one of two authentication schemes, AuthSub or ClientLogin, that are available to enable users to access account-specific YouTube features. The following list will help you to select the authentication scheme that is appropriate for your application.
AuthSub proxy authentication enables web applications to authenticate users to their YouTube accounts without having to access the user's YouTube username and password. You should use AuthSub authentication if you are building a web application that will let users link videos, comments, ratings, contacts or other information to their own YouTube accounts.
ClientLogin authentication lets you associate all API actions with a single YouTube account. You should use ClientLogin if you are building a standalone, single-user, installed client, such as a desktop application. In this case, your application will ask the user to enter his YouTube username and password and will then use those values to request a ClientLogin authentication token.
Note: You should never build a web application that implements ClientLogin authentication and requires users to enter their usernames and passwords. If you are building a web application that allows people to associate actions with their YouTube accounts, use AuthSub authentication.
A developer key identifies the YouTube developer that is submitting an API request. A client ID identifies your application for logging and debugging purposes. Please visit http://code.google.com/apis/youtube/dashboard/ to obtain a developer key and client ID.
YouTube provides two ways to specify your client ID and developer key in an API request:
When you make an API request, use the X-GData-Key request header to specify your developer key and the X-GData-Client header to specify your client ID as shown in the following example:
X-GData-Client: <client_id> X-GData-Key: key=<developer_key>
Include the client and key query parameters in the request URL.
http://gdata.youtube.com/feeds/api/videos?q=SEARCH_TERM&client=CLIENT_ID&key=DEVELOPER_KEY
Note: Specifying your client ID and developer key is very simple if you are using one of our client libraries. In the client libraries, you provide your client ID and developer key when initializing the YouTube service object, and all subsequent requests sent using that object will contain the client ID and developer key.
The AuthSub process is documented in more detail at http://code.google.com/apis/accounts/docs/AuthSub.html. In addition, please note that the base URL and scope of service for YouTube AuthSub authentication – http://gdata.youtube.com – are different than the URL and scope specified in that document.
To obtain an authentication token, submit an HTTP POST request to the following URL:
https://www.google.com/accounts/AuthSubRequest?
next=http%3A%2F%2Fwww.example.com%2Fupload.html
&scope=http%3A%2F%2Fgdata.youtube.com
&session=0
&secure=0
The POST request contains the following parameters:
The next parameter contains the URL to which the user will be redirected after logging in to YouTube.
The scope parameter identifies the service that the user is enabling your site to access on his behalf. The value of this parameter must be http://gdata.youtube.com.
The secure parameter contains a boolean value (0 or 1) that indicates whether the authentication service will return a secure or nonsecure token. Secure tokens are issued only to websites that have registered with Google, and video upload requests that use a secure token must be digitally signed. Please see the Google AuthSub documentation for more details about secure tokens.
The session parameter contains a boolean value (0 or 1) that indicates whether the single-use authentication token that the authentication service returns can be exchanged for a session token, which can be used multiple times. Set this variable to 1 to indicate that the single-use token can be exchanged for a session token. Please see the Google AuthSub documentation for an explanation of how to request a session token.
After the user logs in via YouTube's authentication service, YouTube will redirect the user back to the URL identified in the next parameter in your AuthSub request. The redirect contains a single-use authentication token, which is identified by the token parameter in the URL as shown in the following example. If the value of the session parameter in your AuthSub request was 1, then you can exchange the single-use token for a session token by submitting an AuthSubSessionToken request.
The following URL shows how the token parameter will appear in the redirect to your site. Note that the URL for the redirect would have been provided as the value of the next parameter in the AuthSub request.
http://www.example.com/upload.html?token=CKF50YzIHxCT85KMAg
When you make an authenticated API request using an AuthSub authentication token, your request needs to specify the Authorization HTTP request header as shown in the example below. Note: Throughout this documentation, sample requests use AuthSub syntax unless otherwise specified.
Authorization: AuthSub token="<authentication_token>" X-GData-Key: key=<developer_key>
To make an authenticated API request using YouTube's ClientLogin system for single-user authentication, you must identify the YouTube user account associated with the request. You will provide the username and password for the user's YouTube user account, verifying that the user is authorized to perform operations associated with that account. The authenticated actions will then be associated with that account. Please note that the following instructions vary slightly from the standard ClientLogin instructions.
To obtain an authentication token, submit an HTTP POST request to the following URL:
https://www.google.com/youtube/accounts/ClientLogin
The following guidelines apply to the request:
The POST request must specify the value application/x-www-form-urlencoded for the Content-Type header.
The POST body must include a string in the following format:
Email=<youtube_username>&Passwd=<youtube_password> &service=youtube&source=<source>
You need to make the following changes to this string:
Replace the string <youtube_username> with the user's YouTube account username.
Replace the string <youtube_password> with the user's YouTube account password.
Replace the string <source> with a short string that identifies your application for logging purposes.
The <youtube_username>, <youtube_password> and <source> values must all be URL-encoded.
Google will return a response that contains the authentication token that you will need to execute API operations associated with the specified user's YouTube account. The authentication token will be the Auth value on that page. In addition, the YouTubeUser value on the page will be the user's YouTube account username. You must extract the authentication token and username from the page and then submit those values in API requests. Please note that authentication tokens expire periodically. As such, your application may need to repeat this authentication process and update the value of the authentication token when the token is rejected as expired.
Note: The Google ClientLogin documentation explains how to also incorporate a CAPTCHA challenge into an application using ClientLogin authentication.
Authentication Example
For example, suppose you want to authenticate a YouTube account for which the username and password are testuser and testpassword, respectively. You can simulate the HTTP POST request using the Linux 'curl' command, as shown in the following example:
curl \ --location https://www.google.com/youtube/accounts/ClientLogin \ --data 'Email=testuser&Passwd=testpw&service=youtube&source=Test' \ --header 'Content-Type:application/x-www-form-urlencoded'
If your authentication request is successful, the response to your request will have the following format. (Please note that the Auth token value has been shortened in the example.)
Auth=AIwbFARksypDdUSGGYRI_5v7Z9TaijoPQqpIfCEjTFPAikn_---OC-I1VJtQ YouTubeUser=testuser
When you make an authenticated API request using a ClientLogin authentication token, your request needs to specify the Authorization HTTP request header as shown in the example below:
Authorization: GoogleLogin auth=<authentication_token> X-GData-Key: key=<developer_key>
As shown in the examples throughout this documentation, different API operations are executed using either HTTP GET, POST, PUT or DELETE requests. However, Flash applications must send an HTTP POST request in order to set an Authorization header.
To submit an authenticated HTTP GET, PUT or DELETE request from a Flash application, set the X-HTTP-Method-Override header in the request to either GET, PUT or DELETE. If your application is submitting a GET request, it should set the body of the request to the query parameters associated with that request as shown in the following example:
POST /feeds/api/videos HTTP/1.1 X-HTTP-Method-Override: GET Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="<authentication_token>" X-GData-Client: <CLIENT_ID> 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.
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/opensearchrss/1.0/' xmlns:gml='http://www.opengis.net/gml' xmlns:georss='http://www.georss.org/georss' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/standardfeeds/top_rated</id> <updated>2008-02-21T18:57:10.801Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#video'/> <title type='text'>Top Rated</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='alternate' type='text/html' href='http://www.youtube.com/browser?s=tr'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?...'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?...'/> <author> <name>YouTube</name> <uri>http://www.youtube.com/</uri> </author> <generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator> <openSearch:totalResults>99</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b</id> <published>2007-02-16T20:22:57.000Z</published> <updated>2007-02-16T20:22:57.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/keywords.cat" term="Steventon"/> <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat" term="walk"/> <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat" term="Darcy"/> <category scheme="http://gdata.youtube.com/schemas/2007/categories.cat" term="Entertainment" label="Entertainment"/> <title type="text">My walk with Mr. Darcy</title> <content type="html"><div ... html content trimmed ...></content> <link rel="self" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b"/> <link rel="alternate" type="text/html" href="http://www.youtube.com/watch?v=ZTUVgYoeN_b"/> <link rel="http://gdata.youtube.com/schemas/2007#video.responses" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses"/> <link rel="http://gdata.youtube.com/schemas/2007#video.ratings" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/ratings"/> <link rel="http://gdata.youtube.com/schemas/2007#video.complaints" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/complaints"/> <link rel="http://gdata.youtube.com/schemas/2007#video.related" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/> <author> <name>Andy Samplo</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <media:group> <media:title type="plain">Shopping for Coats</media:title> <media:description type="plain"> What could make for more exciting video? </media:description> <media:keywords>Shopping, parkas</media:keywords> <yt:duration seconds="79"/> <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' type='application/x-shockwave-flash' medium='video' isDefault='true' expression="full" duration='215' yt:format="5"/> <media:content url='rtsp://rtsp2.youtube.com/ChoLENy73bIAEQ1k30OPEgGDA==/0/0/0/video.3gp' type='video/3gpp' medium='video' expression="full" duration='215' yt:format="1"/> <media:content url='rtsp://rtsp2.youtube.com/ChoLENy73bIAEQ1k30OPEgGDA==/0/0/0/video.3gp' type='video/3gpp' medium='video' expression="full" duration='215' yt:format="6"/> <media:player url="http://www.youtube.com/watch?v=ZTUVgYoeN_b"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/2.jpg" height="97" width="130" time="00:00:03.500"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/1.jpg" height="97" width="130" time="00:00:01.750"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/3.jpg" height="97" width="130" time="00:00:05.250"/> <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_b/0.jpg" height="240" width="320" time="00:00:03.500"/> </media:group> <yt:statistics viewCount="93"/> <gd:rating min='1' max='5' numRaters='435' average='4.94'/> <gd:comments> <gd:feedLink href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments" countHint='2197'/> </gd:comments> </entry>
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:
This element displays a title for the result set. In your application, this value could be the value of the <title> tag or you can select other text appropriate to the requested feed or search result set.
In the image, the text 1-20 of about 13,800 uses the following elements from the API response:
The pulldown menus allow the user to select values for the orderby and time parameters. The Reference Guide provides a complete list of the query parameters that the YouTube Data API supports and explains the types of queries for which each parameter applies.
This element displays a thumbnail image of the video. YouTube API responses may contain multiple thumbnail images for a video, each of which is identified by a <media:thumbnail> tag. On the YouTube website, the thumbnail image links to a page that displays more information about the video, including comments and video responses, and also allows the user to watch the video. In a video entry, the <link> tag that has a rel attribute value of alternate identifies the URL for the YouTube page where the user could watch the video. On YouTube search result pages, thumbnail images link to that URL.
To obtain information to display the target page in your application, you would submit an HTTP request to the edit URL for the video entry. The following section, Identifying feeds related to a video entry explains how to identify the edit URL in an entry.
The title next to the video is the value of the <media:title> tag for that video. The text below the title is the value of the <media:description> tag.
The right column displays the following values:
The first line displays text corresponding to the value of the <published> tag for the video. Note that the <published> tag contains a timestamp that could be converted into text to approximate the age of the video as shown in the screenshot -- e.g. added 5 months ago. However, you could also display a date -- e.g. 10/22/07 or Oct. 22 2007.
The second line identifies the YouTube username for the video's owner. This value is specified by the <name> tag encapsulated within the <author> tag for the video entry. On YouTube's website, this link directs the user to a page that displays the video owner's profile information. To retrieve this information on your site, you would submit a subsequent request to the value of the <uri> tag encapsulated within the <author> tag for the video entry.
The third line specifies the number of times the video has been viewed. The <yt:statistics> tag's viewCount attribute specifies this value.
The fourth line provides the average user rating for the video. The <gd:rating> tag's average attribute provides this rating. Note that on YouTube, the rating is adjusted to determine the proper star image to display. For example, ratings between 2.75 and 3.2499 display a three-star rating, while ratings between 3.25 and 3.7499 display a 3.5 rating.
The fifth line displays the length of the video. The <yt:duration> tag provides the length of the video in seconds. In the screenshot, the value has been adjusted to display in minutes and seconds (292 seconds = 04:52).
The sixth line displays the name of the category that describes the video. This value is contained in the <media:category> tag's label attribute. On YouTube's website, the category name also links to a page that displays more videos in that category. The Browsing with Categories and Keywords section explains how to request videos that are in a particular category.
To retrieve a feed about a single video in the result set, you would submit an HTTP GET request to the edit URL for that entry, as explained in the following section. For example, you might issue this request when a user linked from a set of search results to watch a particular video in the search result set.
Each entry in a YouTube Data API response identifies several API URLs related to the video. For example, the entry identifies URLs that let you request comments for the video, video responses for the video or the video owner's YouTube public user profile. Some URLs may be used not only for retrieving information but also for creating, updating or deleting information. For example, you send an HTTP GET request to a URL to retrieve comments for that video and an HTTP 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> <id>http://gdata.youtube.com/feeds/api/videos/dMH0bHeiRN</id> <link rel='http://gdata.youtube.com/schemas/2007#video.responses' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/responses'/> <link rel='http://gdata.youtube.com/schemas/2007#video.ratings' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/ratings'/> <link rel='http://gdata.youtube.com/schemas/2007#video.complaints' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/dmH0bHeiRN/complaints'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/dmH0bHeiRN/uploads'/> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/dmH0bHeiRN/uploads'/> ... </entry>
The Using community features, Saving and collecting videos and Enabling user interaction sections of this document all present use cases describing situations when you might use a particular function to request, create, update or delete resources using the YouTube API. Each use case explains the API requests that you would send as well as the values that you would need to parse from the API responses to allow a user to progress through the use case. Frequently, these steps require you to send an API request to a URL identified within a <link> tag in an API response. The use cases identify the URLs for API requests using the value of the <link> tag's rel attribute.
For example, to retrieve a list of video responses for a video, you would send an HTTP GET request to the URL associated with the <link> tag with the rel attribute value http://gdata.youtube.com/schemas/2007#video.responses. To add a rating to a video, you would send an HTTP POST request to the URL associated with the <link> tag with the rel attribute value http://gdata.youtube.com/schemas/2007#video.ratings.
The following screenshot demonstrates how YouTube displays information about a single video. Whereas the screenshot that displays the list of videos only displays information from a single API request, this page synthesizes several API responses into a single page.
The screenshot is annotated, and the list following the screenshot explains how the display elements correspond to the API responses that contain the content.
Note that to display this page, you would first retrieve the feed for the video entry. The XML in a video entry feed is identical to the content that appears for that video in a feed or search result set.
The screenshot displays the following information:
Section 1 displays the title of the video. In an API response, the <media:title> tag contains the video's title.
Section 2 displays the video itself. You can use the following code snippet to display a YouTube video on your own page. Please note that you must replace the MEDIA_CONTENT_URL and MEDIA_CONTENT_TYPE variables with the appropriate values from the XML feed:
To play a video on a web page, replace the MEDIA_CONTENT_URL variable with the url attribute value of the <media:content> tag for which the yt:format attribute value is 5. Also, replace the MEDIA_CONTENT_TYPE variable with the type attribute value from the same <media:content> tag.
To play a video on a mobile device, select the appropriate <media:content> tag values based on the value of the yt:format attribute. Replace the MEDIA_CONTENT_URL variable with the url attribute value from that tag. Also, replace the the MEDIA_CONTENT_URL variable with the url attribute value from the tag.
<object width="425" height="350"> <param name="movie" value="MEDIA_CONTENT_URL"></param> <embed src="MEDIA_CONTENT_URL" type="MEDIA_CONTENT_TYPE" width="425" height="350"> </embed> </object>
Section 3 displays a variety of action buttons as well as statistics about the video:
Action buttons
The Share button on YouTube's website displays an inline form that allows a user to send a message to a contact or any other email address. To duplicate this implementation of the Share button, you would need to provide a form that retrieves and displays the contacts for the logged-in user and then allows the user to select contacts to whom to send a message. When the user submits the message, your application would need to submit one API request for each message recipient.
The Favorite button adds the video to the logged-in user's list of favorite videos. Learn more about adding a favorite video.
The Add to Playlists button toggles an inline form that displays a pulldown menu listing the logged-in user's playlists as well as an option to create a new playlist. If the user selects an existing playlist, the video is added to that playlist. If the user chooses to add a new playlist, the form directs the user to another form for adding a playlist. After submitting information about the new playlist, YouTube also adds the video to the playlist.
To duplicate this functionality, your application would need to send an additional API request to retrieve a list of the user's playlists. If the user selected an existing playlist, your application would add the video to that playlist. If the user elected to create a new playlist, your application would collect the new playlist information, add the playlist and then add the video to the playlist.
The Flag button displays an inline form that allows a user to add a complaint about a video. On YouTube's site, the form displays select menus that are used to generate the value of the <yt:description> tag in the API request for adding the complaint. Your application could display similar pulldown menus or could display a text box allowing the user to enter a complaint.
Statistics
Section 4 displays a list of comments and video responses for the video. (In the example, there are no video responses for the video.) This section displays the following elements:
Above the list of comments, the link to post a video response directs the user to a form that allows him to select a previously uploaded video or to upload a new video as a video response.
To allow the user to select a previously uploaded video, the application retrieves a feed of the videos uploaded by that user. Once the user selected a video, your application would add the video as a video response.
If the user chooses to upload a new video, your application will need to support either the browser-based uploading or direct uploading method for adding new videos to YouTube. After the user uploads the new video using one of those two methods, your application would retrieve the new video's ID and subsequently add the video as a video response.
The second link above the list of comments allows the user to post a text comment. The link toggles an inline form where the user can enter the comment. To provide this functionality, your application would need to send an API request to add the comment after the user submitted the form.
To display the list of comments, your application would need to send an additional API request to retrieve the comments feed for the video.
Section 5 displays additional information about the video and the person who uploaded the video:
To retrieve additional information about the video owner, such as the number of videos that person had uploaded, you would need to send an additional API request to retrieve the owner's profile. A profile feed contains a number of <gd:feedLink> tags that correspond to the something about the user, such as the user's favorite videos, subscriptions or uploaded videos. The countHint attribute of the <gd:feedLink> tag indicates how many favorite videos, subscriptions or uploaded videos the user has.
The Subscribe button next to the video owner's name allows a user to subscribe to the video owner's channel, which contains all videos uploaded by the video owner. To duplicate the functionality of the Subscribe button in your application, you would need to send an API request to add a subscription when a user clicks the button.
The About This Video part of the box contains additional information about the video. You could use the content in the <media:description>, <media:keywords>, <yt:duration> or other tags to provide more information about a video.
Section 6 displays more videos uploaded by the video owner. Learn how to retrieve videos uploaded by a specific user.
Section 7 displays a list of videos that YouTube considers similar to the video featured on the page. The related videos feed allows you to retrieve this list using the API.
This section explains how to retrieve standard YouTube feeds. Standard feeds contain lists of videos that either reflect YouTube user behavior, such as top-rated and most viewed video feeds, or were selected by YouTube staff, such as recently featured and mobile video feeds. Many of these feeds are shown on the Videos tab of the YouTube website. Standard feeds are updated every few minutes.
To retrieve a standard feed, send an HTTP 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 |
|---|---|---|
| Top rated | top_rated | URL: http://gdata.youtube.com/feeds/api/standardfeeds/top_rated Description: This feed contains the most highly rated YouTube videos. |
| Top favorites | top_favorites | URL: http://gdata.youtube.com/feeds/api/standardfeeds/top_favorites Description: This feed contains videos most frequently flagged as favorite videos. |
| Most viewed | most_viewed | URL: http://gdata.youtube.com/feeds/api/standardfeeds/most_viewed Description: This feed contains the most frequently watched YouTube videos. |
| Most popular | most_popular | URL: http://gdata.youtube.com/feeds/api/standardfeeds/most_popular Description: This feed contains the most popular YouTube videos, selected using an algorithm that combines many different signals to determine overall popularity. |
| Most recent | most_recent | URL: http://gdata.youtube.com/feeds/api/standardfeeds/most_recent Description: This feed contains the videos most recently submitted to YouTube. |
| Most discussed | most_discussed | URL: http://gdata.youtube.com/feeds/api/standardfeeds/most_discussed Description: This feed contains the YouTube videos that have received the most comments. |
| Most responded | most_responded | URL: http://gdata.youtube.com/feeds/api/standardfeeds/most_responded Description: This feed contains YouTube videos that receive the most video responses. |
| Recently featured | recently_featured | URL: http://gdata.youtube.com/feeds/api/standardfeeds/recently_featured Description: This feed contains videos recently featured on the YouTube home page or featured videos tab. |
| Videos for mobile phones | watch_on_mobile | URL: http://gdata.youtube.com/feeds/api/standardfeeds/watch_on_mobile Description: This feed contains videos suitable for playback on mobile devices. |
In addition, please note that many of these feeds support the time query parameter, which allows you to restrict the feed to only contain relevant results from the previous day, week or month. For example, to retrieve top-rated videos from the previous day, you would send an HTTP GET request to the following URL:
http://gdata.youtube.com/feeds/api/standardfeeds/top_rated?time=today
Note: The top_rated, top_favorites, most_viewed, most_discussed and most_responded standard feeds support the time parameter.
This section explains how to retrieve a feed containing all of the videos uploaded by a specific user:
To request a feed of all videos uploaded by the currently logged-in user, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.
http://gdata.youtube.com/feeds/api/users/default/uploads
To ensure that the API response contains the most up-to-date information available for the user's videos, do not use any parameters other than start-index and max-results in your request. Requests using other parameters, such as orderby, will return cached results.
Note: In the above URL, the value default in the GET URL signifies that you are requesting videos uploaded by the currently logged-in user. The user is identified by the authentication token that you submit with the request. The default value can be used to identify the currently logged-in user in a number of other API commands. For example, you can send an HTTP GET request to http://gdata.youtube.com/feeds/api/users/default/playlists to retrieve the currently logged-in user's playlists. You can also send an HTTP POST request to the same URL to create a new playlist in the currently logged-in user's account.
To request a feed of all videos uploaded by another user, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://gdata.youtube.com/feeds/api/users/username/uploads
In the URL above, you must replace the text username with the user's YouTube username. You can extract the username from the <name> tag in an API response as shown in the following example.
<author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author>
The API response for this query has exactly the same format as the sample response in the Understanding video feeds and entries section of this document.
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="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related"/>
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.
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.
http://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:
http://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:
http://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: http://gdata.youtube.com/feeds/api/videos/-/bass/fishing category parameter: http://gdata.youtube.com/feeds/api/videos?category=bass%2Cfishing
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: http://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing category parameter: http://gdata.youtube.com/feeds/api/videos?category=bass%2C%2Dfish%2Dfishing
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: http://gdata.youtube.com/feeds/api/videos/-/jesse/ventura/News%7CSports category parameter: http://gdata.youtube.com/feeds/api/videos?category=jesse%2Cventura%2CNews%7CSports
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: http://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy category parameter: http://gdata.youtube.com/feeds/api/videos?category=comedy%2C%2DComedy
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: http://gdata.youtube.com/feeds/api/videos/-/ %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fcategories.cat%7DNews category parameter: http://gdata.youtube.com/feeds/api/videos?category= %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fcategories.cat%7DNews Keywords: URL notation: http://gdata.youtube.com/feeds/api/videos/-/ %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fkeywords.cat%7Ddog category parameter: http://gdata.youtube.com/feeds/api/videos?category= %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fkeywords.cat%7Ddog Developer tags: URL notation: http://gdata.youtube.com/feeds/api/videos/-/ %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fdevelopertags.cat%7Dexample.com category parameter: http://gdata.youtube.com/feeds/api/videos?category= %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fdevelopertags.cat%7Dexample.com
Always specify the schema, as explained in the previous item, if you are requesting videos associated with a particular developer tag.
This section explains how to use the API to retrieve a list of videos matching a user-specified search term. To search for videos, submit an HTTP GET request to the following URL, appending the appropriate query parameters to your request:
http://gdata.youtube.com/feeds/api/videos
The following example searches for the second set of 10 recently uploaded videos matching the query term "football" but not matching the query term "soccer":
http://gdata.youtube.com/feeds/api/videos?
vq=football+-soccer
&orderby=published
&start-index=11
&max-results=10
Search requests can include any of the following parameters. Commonly used parameters are listed first.
| Name | Definition | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| vq | The vq 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 vq 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 vq 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 vq parameter to "boating&7Csailing+-fishing". |
||||||||
| orderby | The orderby parameter specifies the value that will be used to sort videos in the search result set. Valid values for this parameter are relevance, published, viewCount and rating. In addition, you can 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.) In addition, please note that results in other languages will still be returned if they are highly relevant to the search query term. The default value is relevance. | ||||||||
| 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. | ||||||||
| 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. | ||||||||
| author | The author parameter restricts the search to videos uploaded by a particular YouTube user. Note that if you use this parameter when requesting a standard feed, then YouTube will retrieve the standard feed and then filter the response to only include videos uploaded by the specified author. For example, if you request the "Top Rated" feed for user GoogleDevelopers, the API will retrieve the top-rated feed and return a response containing videos in that feed uploaded by user GoogleDevelopers. The API will not return a list of that user's videos ordered by rating.
|
||||||||
| alt | The alt parameter specifies the format of the feed to be returned. Valid values for this parameter are atom, rss, json and json-in-script. 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. | ||||||||
| category | The category parameter enables you to retrieve videos that are in a particular category or are tagged with a particular keyword or developer tag. You can also insert category names, keywords and developer tags into the request URL as described in the
Browsing with categories and keywords
section. That section provides instructions for formatting the category parameter value for a variety of different types of queries.
YouTube supports this parameter for video search requests. |
||||||||
| client | The client parameter is an alphanumeric string that identifies your 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. Your application does not need to specify your client ID twice by using both the client parameter and the X-GData-Client request header, but it should provide your client ID using at least one of those two methods. | ||||||||
| format | The format parameter specifies that videos must be available in a particular video format. Your request can specify any of the following formats:
YouTube supports this parameter for video search requests. |
||||||||
| key | The key parameter specifies your developer key, an alphanumeric string that identifies the developer or company 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. | ||||||||
| location | The location parameter restricts the search to videos that have a geographical location specified in their metadata.
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. |
||||||||
| 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. 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. |
||||||||
| racy | The racy parameter allows a search result set to include restricted content as well as standard content. Valid values for this parameter are include and exclude. By default, restricted content is excluded. Feed entries for videos that contain restricted content will contain the <media:rating> element. | ||||||||
| restriction | The restriction parameter identifies the IP address that should be used to filter videos that can only be played in specific countries. We recommend that you always use this parameter to specify the end user's IP address. (By default, the API filters out videos that cannot be played in the country from which you send API requests. This restriction is based on your client application's IP address.) To request videos playable from a specific computer, include the restriction parameter in your request and set the parameter value to the IP address of the computer where the videos will be played – e.g. restriction=255.255.255.255.To request videos that are playable in a specific country, include the restriction parameter in your request and set the parameter value to the ISO 3166 two-letter country code of the country where the videos will be played – e.g. restriction=DE.You should include this parameter in any request to retrieve a list of videos, including search results, playlists, favorite videos, video responses and so forth. If a video in the API response is not playable in the location that you're using to restrict availability of the content, the <entry> for that tag will not contain a <media:content> tag. However, it will contain a <yt:state> tag that indicates that the video is restricted. |
||||||||
| sortorder | The sortorder parameter, which is only valid for comments feeds, specifies the order in which comments should appear in the API response. If the parameter value is ascending, then comments will be ordered from oldest to newest in the API response. If the parameter value is descending, then comments will be ordered from newest to oldest. | ||||||||
| time | The time parameter restricts the search to videos uploaded within the specified time. 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. This parameter is supported for search feeds as well as for the top_rated, top_favorites, most_viewed, most_popular, most_discussed and most_responded standard feeds. |
Note that search query parameters can also be appended to other types of feed requests. For example, you can retrieve videos uploaded by a specific user that also match a particular keyword.
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.
Note: The YouTube Data API will not allow you to upload additional videos to accounts that already contain 2000 or more videos.
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:
This section provides process flow diagrams for the two authentication schemes and for the two upload methods. Depending on your application, you could combine either authentication scheme with either upload method.
The following diagram illustrates the steps involved in authenticating a user using the AuthSub authentication scheme. AuthSub authentication can be used with either direct uploading or browser-based uploading.
The image shows the following steps:
The user clicks a link on your site to upload a video.
Your site redirects the user to YouTube's Authentication Proxy service.
The user's browser sends a request to the authentication service.
YouTube displays an Access Consent page, prompting the user to log in to his YouTube account.
The user logs in to his account, and YouTube then asks the user to grant or deny the ability for your site to upload the user's video details.
If the user grants access, YouTube redirects the user back to your site. The redirect URL contains the authentication token for your Upload API request.
The user's browser sends a request, including the authentication token, to your site. The Google AuthSub documentation explains the optional step of exchanging the single-use authentication token for a session token that does not expire.
The following diagram illustrates the steps involved in authenticating a user using the ClientLogin authentication scheme. Like AuthSub authentication, ClientLogin authentication can be used with either direct uploading or browser-based uploading.
The image shows the following steps:
The user clicks a link on your site to upload a video.
Your application presents a form for the user to enter a YouTube username and password.
The user submits his YouTube username and password to your installed application.
Your application sends a ClientLogin authentication request to YouTube to obtain an authentication token for uploading the video. The request specifies the username and password for the user's YouTube user account, which will be the account associated with the video.
YouTube verifies the user's username and password and returns the authentication token to your application. If you are using browser-based uploading, the token will allow you to upload the video metadata. If you are using direct uploading, the token will allow you to upload the metadata and the actual video file.
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:
Your site displays a form in which the user will enter details about the video being uploaded.
The user enters the video details, such as the title, description and category for the video.
Your site sends an HTTP 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.
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.
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.
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.
YouTube redirects the user back to your site.
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:
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.
The user selects the video file and enters the video details, such as the title, description and category for the video.
Your site sends an HTTP 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.
YouTube returns an API response describing the new video.
You display a confirmation to the user that the video was uploaded successfully.
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. 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 1 GB or smaller and that videos may not be longer than 10 minutes. You may compress API requests using gzip transfer-encoding. However, please note that the 1 GB size restriction still applies to the uncompressed video file.
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. 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.
To search for videos associated with a specific developer tag, send an API search request that specifies the developertags.cat category scheme and the developer tag that videos must match. The URLs below demonstrate how you would modify the standard API URL to match a developer tag. (You would need to replace the string TagName at the end of the URL with the name of your developer tag.)
Standard URL:
http://gdata.youtube.com/feeds/api/videos/
Retrieving videos associated with a developer tag:
http://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.
The example below shows the format of an API request that uses the AuthSub authentication scheme for browser-based uploading:
POST /action/GetUploadToken HTTP/1.1 Host: gdata.youtube.com Authorization: AuthSub token="<authentication_token>" X-GData-Client: <client_id> X-GData-Key: key=<developer_key> Content-Length: <content_length> Content-Type: application/atom+xml; charset=UTF-8 API_XML_request
You must provide several values in the HTTP POST request. Those values are highlighted in bold text in the example above. The following list explains how to populate each of these values:
authentication_token - This value contains the authentication token for your request. The token will either be a ClientLogin token, an AuthSub single-use token or an AuthSub session token.
client_id - (optional) This value identifies the application making the API request. This value is used for logging and debugging. Please visit http://code.google.com/apis/youtube/dashboard/ to get a client ID.
developer_key - This value identifies the YouTube developer 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 HTTP 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 an HTTP POST request that has all of these values populated with the exception of the binary file data.
POST /action/GetUploadToken HTTP/1.1 Host: gdata.youtube.com Authorization: AuthSub token="DXAA...sdb8" X-GData-Client: b1c4t9sl2159 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>
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>
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 contains a hidden input field containing the upload token.
The following HTML shows a sample form as it would appear on your site:
<form action="URL?nexturl=http%3A%2F%2Fwww.example.com method="post" enctype="multipart/form-data"> <input type="file" name="file"/> <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.
To upload a video, send an HTTP POST request containing the video and associated metadata to http://uploads.gdata.youtube.com/feeds/api/users/<youtube_username>/uploads. You need to replace the string <youtube_username> with the username for the content creator's YouTube account. You can replace the <youtube_username> string with the term default to upload a video to the currently logged-in user's account. The authentication token that you upload with the request identifies that user.
The Upload API request must have the following format:
POST /feeds/api/users/default/uploads HTTP/1.1 Host: uploads.gdata.youtube.com Authorization: AuthSub token="<authentication_token>" X-GData-Client: <client_id> X-GData-Key: key=<developer_key> Slug: <video_filename> Content-Type: multipart/related; boundary="<boundary_string>" Content-Length: <content_length> Connection: close --<boundary_string> Content-Type: application/atom+xml; charset=UTF-8 API_XML_request --<boundary_string> Content-Type: <video_content_type> Content-Transfer-Encoding: binary <Binary File Data> --<boundary_string>--
A request to upload a video using the ClientLogin authentication scheme has one syntactic difference from the example above. The Authorization header is formatted differently for a ClientLogin authentication token. The following example demonstrates how to properly format the Authorization request header for a ClientLogin authentication token:
Authorization: GoogleLogin auth=<authentication_token>
Note: The hostname for uploading a video via the API, uploads.gdata.youtube.com, is different than the hostname used for all other API functions. However, you can use the same authentication token for uploading as for other API functions.
You must provide several values in the HTTP POST request. Those values are highlighted in bold text in the example above. The following list explains how to populate each of these values:
youtube_username - Note that this variable is only relevant for requests that use ClientLogin authentication. This value contains the username for the user's YouTube account. The uploaded video will be associated with this account.
authentication_token - This value contains the authentication token for your request. The token will either be a ClientLogin token, an AuthSub single-use token or an AuthSub session token.
client_id - (optional) This value identifies the application making the API request. This value is used for logging and debugging. Please visit http://code.google.com/apis/youtube/dashboard/ to get a client ID.
developer_key - This value identifies the YouTube developer 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 HTTP POST request.
content_length - This value contains the length, in bytes, of the entire body of the HTTP 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 an HTTP POST request that has all of these values populated with the exception of the binary file data.
POST /feeds/api/users/default/uploads HTTP/1.1 Host: uploads.gdata.youtube.com Authorization: AuthSub token="DXAA...sdb8" X-GData-Client: b1c4t9sl2159 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--
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, submit an HTTP GET request to the URL identified in this <link> tag. See the following section, Checking the status of an uploaded video, for more information.
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, submit an HTTP GET request to the URL identified in this <link> tag.
<link rel='self' type='application/atom+xml'
href='http://gdata.youtube.com/feeds/api/users/username/uploads/Video_ID'/>
When you check the status of an uploaded video, the status information will be contained in the <app:control> tag and its subtags, <app:draft> and <yt:state>. The following XML excerpt shows how these tags appear in an entry in an API response:
<entry> <id>http://gdata.youtube.com/feeds/user/username/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.
To update a video, send an HTTP PUT request to the URL identified in the video entry's <link> tag where the rel attribute value is edit:
<link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/uploads/914IMX9RSTE'>
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.
The following XML shows a sample request to update a video:
PUT /feeds/api/users/USER_ID/uploads/VIDEO_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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> </entry>
To delete a video, send an HTTP DELETE request to the edit URL for that video as shown in the following example:
DELETE /feeds/api/users/USER_ID/uploads/VIDEO_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
Deleted videos are typically removed from a user's public uploaded videos feed within a couple of hours.
A user can add a rating to a video. YouTube uses a 1-5 rating system in which 1 is the lowest rating that can be given. Users cannot update or delete ratings. Typically, a user would rate a video after watching that video.
In an API response, each entry includes two tags that contain information relevant to user ratings:
The <gd:rating> tag identifies the rating scale, the number of ratings of the video and the average rating for the video. This tag is only returned if the video has been rated. The XML excerpt below shows how this URL appears in an API response:
<feed>
<entry>
...
<gd:rating min='1' max='5' numRaters='1914' average='4.24'/>
</entry>
</feed>
A <link> tag identifies the URL to which you would post an API request to add a rating to a 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.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.responses'
type='application/atom+xml'
href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/responses'/>
<link rel='http://gdata.youtube.com/schemas/2007#video.ratings'
type='application/atom+xml'
href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/ratings'/>
...
<media:group>
</entry>
</feed>
To add a rating, send an HTTP POST request that identifies the video being rated and the rating itself. (The user who is rating the video is identified by the authentication token.)
The following XML demonstrates how to add a rating to a video. Please note that the value attribute of the <gd:rating> tag must be an integer between 1 and 5 that identifies the rating being given.
POST /feeds/api/videos/VIDEO_ID/ratings Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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.
YouTube will return an error if your HTTP request specifies an invalid value for the <gd:rating> tag's value attribute, a value other than 1 for the min attribute or a value other than 5 for the max attribute.
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.
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='http://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/opensearchrss/1.0/'> <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?...</id> <updated>2008-02-25T23:14:03.148Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#comment'/> <title type='text'>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='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/watch?v=ZTUVgYoeN_b'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?...'/> <link rel='next' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments?...'/> <author> <name>YouTube</name> <uri>http://www.youtube.com/</uri> </author> <generator version='beta' 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> <id> http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/comments/7F2... </id> <published>2007-05-23T00:21:59.000-07:00</published> <updated>2007-05-23T00:21:59.000-07:00</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#comment'/> <title type='text'>Walking is fun.</title> <content type='text'>Walking is fun.</content> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/watch?v=ZTUVgYoeN_b'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/ZTU.../comments/7F2...'/> <author> <name>andyland744</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland744</uri> </author> </entry> <entry> ... </entry> ... </feed>
Identifying comments that are replies to other comments
YouTube users may respond to a comment with another comment. When displaying these comments, you may want to indent comments that reply to other comments to identify comment threads. You could also link comments that reply to other comments to help users to follow a comment thread. In an XML response, a comment that was posted in response to another comment will contain an in-reply-to link as shown in the following <link> tag:
<link rel="http://gdata.youtube.com/schemas/2007#in-reply-to" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/2cd.../comments/978..."/>
To add a comment to a video, send an HTTP POST request to the URL identified in the <gd:feedLink> tag that appears inside the <gd:comments> tag. The actual comment that you are submitting appears as the value of the <content> tag in the XML that constitutes the body of the POST request.
The sample XML API request below demonstrates how to add a comment to a video.
POST /feeds/api/videos/VIDEO_ID/comments HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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>
The API request for adding a comment in response to a video is nearly identical to the API request for adding a comment in reply to another comment. The only difference is that the latter request contains an additional <link> tag that identifies the comment being replied to. The following instructions explain how to format the <link> tag:
rel attribute value to http://gdata.youtube.com/schemas/2007#in-reply-to.type attribute value to application/atom+xml.href attribute value to the self link for the comment being replied to.The sample XML API request below demonstrates how to add a comment in reply to another comment. The <link> tag that indicates that the comment is a reply to another comment is highlighted in bold text.
POST /feeds/api/videos/VIDEO_ID/comments HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <link rel="http://gdata.youtube.com/schemas/2007#in-reply-to" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/comments/COMMENT_ID"/> <content>This is a comment about another comment.</content> </entry>
Note: The POST URL for this API request specifies the video associated with the new comment. The <link> tag identifies the original comment to which the new comment replies. The new comment and the original comment must be associated with the same video.
A video response is a video that is associated, as a reply, with a second video. A video can be designated as a video response with exactly one other video. Logged-in users can add or delete video responses, but the user must have uploaded the video that is being added or deleted.
This section explains how to retrieve a feed of video responses for a video. Note that some videos may not have any video responses.
Each video entry in an API response contains a series of <link> tags. The <link> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007/#video.responses identifies the URL for retrieving video responses for that video entry. (The <link> tag's href attribute identifies the URL.)
<link rel="http://gdata.youtube.com/schemas/2007#video.responses"
type="application/atom+xml"
href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses"/>
The API response for this query has exactly the same format as the sample response in the Understanding video feeds and entries section of this document.
To add a video response, you will submit an HTTP POST request that identifies two videos – the video that to which you are adding the video response and the video that is being added as a response.
The following XML illustrates the format for a sample request for adding a video response. In the request, the string ORIGINAL_VIDEO_ID identifies the video that to which you are adding the video response, and the string RESPONSE_VIDEO_ID identifies the video that is being added as a response.
POST /feeds/api/videos/ORIGINAL_VIDEO_ID/responses HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www/w3.org/2005/Atom"> <id>RESPONSE_VIDEO_ID</id> </entry>
If YouTube successfully handles your request, the API will return a 201 HTTP response code. However, the video response will not be listed in the video responses feed until the response has been approved by the owner of the original video.
Typically, a user will add a video response to a video after watching that video. In some cases, the user will select a video that he has already uploaded as the response. In other cases, the user will upload a new video, which will serve as the video response. The following list identifies the API calls associated with each type of API request:
The user selects an existing video to serve as a video response.
You retrieve information about a video by submitting an API request to that video's self URL.
The user clicks a link to add a video response to the video and elects to respond with a previously uploaded video. You extract the video response URL for the video to which the user is adding the response.
You send an API request to retrieve the list of videos uploaded by the user. You display the list of videos so that the user can select one of the videos.
When the user selects a video, you send an HTTP POST request to the video response URL for the original video that specifies the <id> of the selected video. The Retrieving a list of video responses section explains how to identify the video response URL for a feed entry.
The user uploads a new video, which will serve as the video response.
This use case also begins with an API request to retrieve information about a video.
The user clicks a link to add a video response to the video and elects to upload (or capture) a new video. You extract the video response URL for the video to which the user is adding the response.
You send an API request to upload the new video to YouTube's video library. If the user first needs to capture the video, you may also need to present a form that lets the user enter a title and other information about the video.
You extract the video ID for the newly added video from the API response to your upload request.
You send an HTTP POST request to the video response URL for the original video to add the newly added video as a video response.
To delete a video response, submit an HTTP DELETE request that identifies the two videos, as shown in the following example.
DELETE /feeds/api/videos/VIDEO_ID/responses/VIDEO_RESPONSE_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
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 will send an HTTP 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 HTTP 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:
The following XML demonstrates how to add a complaint about a video.
POST /feeds/api/videos/VIDEO_ID/complaints HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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:content type="text"> 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. </yt:content> <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.
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.
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 an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.
http://gdata.youtube.com/feeds/api/users/default/favorites
To request a feed of another user's favorite videos, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://gdata.youtube.com/feeds/api/users/username/favorites
In the URL above, you must replace the text username with the user's YouTube username.
The API response for this query has exactly the same format as the sample response in the Understanding video feeds and entries section of this document.
The following request provides the URL and illustrates the XML format for adding a video to the logged-in user's list of favorite videos:
POST /feeds/api/users/default/favorites HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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.
This use case begins with an API request to obtain information about a specific video.
After watching the video, the user elects to flag the video as a favorite video.
Your application sends an API POST request to http://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.
This use case begins with a request to search for videos or to retrieve a particular video feed.
The user selects one or more videos from the list – for example, the user could check a box next to each video.
Your application loops through the selected videos and sends an API request to add each selected video as a favorite. Your application sends each request to http://gdata.youtube.com/feeds/api/users/default/favorites. The <id> tag in each request specifies the <id> tag value for the corresponding video in the video feed from the previous step.
To delete a favorite video, send an HTTP DELETE request to the edit URL for the video entry:
<link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/USER_ID/favorites/FAVORITE_VIDEO_ID'>
Note: The ID that you use to delete a favorite video is not the <id> 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 HTTP 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/USER_ID/favorites/FAVORITE_VIDEO_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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:
This use case begins with a request to retrieve a feed of the user's favorite videos.
The user selects one or more videos from the list – for example, the user could check a box next to each video.
Your application loops through the selected videos and sends an HTTP 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.
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.
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 an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.
http://gdata.youtube.com/feeds/api/users/default/playlists
To request a feed of another user's playlists, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://gdata.youtube.com/feeds/api/users/username/playlists
In the URL above, you must replace the text username with the user's YouTube username.
The following XML shows a sample API response containing a playlists feed. The response contains a series of <entry> tags, with each entry describing a playlist. Each entry contains the playlist's title, description, author and modification date as well as a <gd:feedLink> 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/opensearchrss/1.0/' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/users/andyland74/playlists?...</id> <updated>2008-02-26T00:26:15.635Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/> <title type='text'>andyland74's Playlists</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_play_list?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists?...'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' 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> <id> http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BC... </id> <published>2007-11-04T17:30:27.000-08:00</published> <updated>2008-02-22T09:55:14.000-08:00</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#playlistLink'/> <title type='text'>My New Playlist Title</title> <content type='text'>My new playlist Description</content> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/view_play_list?p=8BCDD04DE8F771B2'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists/8BC...'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:description>My new playlist Description</yt:description> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist' href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2'/> </entry> </feed>
As noted in the previous section, each entry in a user's playlists feed contains a <gd:feedLink> 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:
<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist'
href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2'/>
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 <yt:description> tag. The <yt:description> 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.
To create a playlist, you must provide a title and description for the playlist. The <yt:private> tag, which is optional, indicates whether the playlist will be publicly visible. (By default, playlists are visible to other users.)
The following request provides the URL and shows the XML format for creating a new playlist:
POST /feeds/api/users/default/playlists HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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> <yt:description>A selection of sports highlights</yt:description> </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.
This use case begins with an API request to obtain information about a specific video.
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.
Your application sends an HTTP POST request to http://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.
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.
This use case begins with an API request to search for videos or to retrieve a particular video feed.
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.
Your application displays a form to allow the user to enter a title and description for the playlist.
Your application sends an HTTP POST request to http://gdata.youtube.com/feeds/api/users/default/playlists to create the playlist using the title and description entered by the user.
Your application then loops through the selected videos and sends an additional API request to add each selected video to the 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 an HTTP PUT request and the API URL must specify the ID of the playlist being updated.
PUT /feeds/api/users/USER_ID/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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> <yt:description>A selection of sports highlights</yt:description> </entry>
The following use case describes a scenario where a user would modify a playlist:
This use case begins with a request to retrieve a feed of the user's playlists.
The user selects a playlist from the list and clicks a link to update the playlist.
Your application displays a form that lets the user update the title and description of the playlist.
Your application then sends an HTTP PUT request to the playlist's edit URL to update the playlist.
To add a video to a playlist, you will 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, you must first add the video. Then you must update the playlist entry using the <yt:position> tag to adjust the order in which the video appears in the playlist.
The following request provides the URL and illustrates the XML format for adding a video to a playlist:
POST /feeds/api/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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> </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.
This use case begins with an API request to obtain information about a specific video.
After watching the video, the user clicks a link to add the video to a playlist.
Your application submits an API request to retrieve a list of the user's playlists and then displays the list.
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.
This use case begins with an API request to search for videos or to retrieve a particular video feed.
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.
Your application submits an API request to retrieve a list of the user's playlists and then displays the list.
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 <id> 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.
A user can update the order in which a video appears in a playlist entry. The following sample request illustrates the XML format for modifying a playlist entry. Please note that the XML submitted in the request has the same format as a request to create a playlist entry. However, this request is an HTTP PUT request and the API URL, which specifies the ID of the playlist entry being updated, is different.
PUT /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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:
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 an HTTP PUT request to the edit URL for that entry.
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.
The user reorders the playlist entries and clicks a link to update the playlist.
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.
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 an HTTP DELETE request to the edit URL for that entry.
DELETE /feeds/api/playlists/PLAYLIST_ID/PLAYLIST_ENTRY_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
The following list describes a common use case for deleting a playlist entry:
This use case begins with a request to retrieve a specific playlist.
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.
Your application loops through the selected entries and sends an HTTP 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 removes a playlist altogether. The following sample API request demonstrates how to delete a playlist:
DELETE /feeds/api/users/USER_ID/playlists/PLAYLIST_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
The following list describes a common use case for deleting a playlist:
This use case begins with a request to retrieve a feed of the user's playlists.
The user selects a playlist from the list to delete and you send an API request to delete the playlist.
A subscription refers to an entity that notifies a user when new videos are uploaded. Users can subscribe to another user's channel, another user's list of favorites, or a keyword tag. 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 create or delete 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 an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.
http://gdata.youtube.com/feeds/api/users/default/subscriptions
To request a feed of another user's subscriptions, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://gdata.youtube.com/feeds/api/users/username/subscriptions
In the URL above, you must replace the text username with the user's YouTube username.
A subscriptions feed contains a series of <entry> tags, with each entry describing a subscription. Users can subscribe to YouTube channels, other users' lists of favorite videos, and keyword tags. Each entry in the subscription feed contains a <category> tag for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. The value of the term attribute for that <category> tag indicates whether the subscription is to a channel, a list of favorite videos, or a keyword tag.
If the feed entry describes a channel subscription, the <category> tag's term attribute will have a value of channel. The entry will also contain the <yt:username> element, which specifies the owner of the channel.
If the feed entry describes a subscription to another user's list of favorite videos, the <category> tag's term attribute will have a value of favorites. The entry will also contain the <yt:username> element, which specifies the user whose favorite videos are being subscribed to.
If the feed entry describes a keyword subscription, the <category> tag's term attribute will have a value of query. The entry will also contain the <yt:queryString> element, which specifies the keyword that is the subject of the subscription.
The following XML shows a sample API response containing a subscriptions feed. The response contains a series of three entries. The entries show a channel, keyword, and favorite videos subscription. The <gd:feedLink> tag in each entry specifies the URL for retrieving videos in that subscription. The second and third entries only show the tags that contain values different than the same tags in the first entry.
<?xml version='1.0' encoding='UTF-8'?> <feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?start-index=1&max-results=25</id> <updated>2008-02-26T00:26:15.635Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#subscription'/> <title type='text'>andyland74's Subscriptions</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_subscriptions?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions'/> <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/batch'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?start-index=1&max-results=25'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' 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> <id>http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/d411759045e2ad8c</id> <published>2007-11-04T17:30:27.000-08:00</published> <updated>2008-02-22T09:55:14.000-08:00</updated> <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 type='text'>Videos published by : NBC</title> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_videos?user=NBC'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/d411759045e2ad8c'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:username>NBC</yt:username> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads' href='http://gdata.youtube.com/feeds/api/users/nbc/uploads'/> </entry> <entry> ... <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='query'/> <title type='text'>Videos matching : surfing</title> <link rel='alternate' type='text/html' href='http://www.youtube.com/results?search_query=surfing'/> ... <yt:queryString>surfing</yt:queryString> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#video.query' href='http://gdata.youtube.com/feeds/api/videos?vq=surfing'/> </entry> <entry> ... <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='favorites'/> <title type='text'>Favorites of : kemlye</title> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_favorites?user=kemlye'/> ... <yt:username>kemlye</yt:username> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads' href='http://gdata.youtube.com/feeds/api/users/kemlye/favorites'/> </entry> </feed>
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 HTTP GET request to the following URL:
http://gdata.youtube.com/feeds/api/users/default/newsubscriptionvideos
To request a feed of another user's subscriptions, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://gdata.youtube.com/feeds/api/users/username/newsubscriptionvideos
In the URL above, you must replace the text username with the user's YouTube username.
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='http://gdata.youtube.com/feeds/api/users/andyland74/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.
To create a subscription, you must identify the YouTube user name for the authenticated user who is creating the subscription. You must also use the <category> tag to indicate whether the user is subscribing to a channel, list of favorites, or keyword.
The following requests illustrate the XML format for creating different types of subscriptions:
POST /feeds/api/users/default/subscriptions HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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>andyland74</yt:username> </entry>
POST /feeds/api/users/default/subscriptions HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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="favorites"/> <yt:username>andyland74</yt:username> </entry>
POST /feeds/api/users/default/subscriptions HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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="query"/> <yt:queryString>Dog Skateboarding</yt:queryString> </entry>
The following list identifies common use cases for creating subscriptions and describes the API calls associated with each use case:
A user watches a video and subscribes to the video owner's channel.
This use case begins with an API request to retrieve information about a specific video.
After watching the video, the user clicks a link to subscribe to the video owner's channel.
Your application sends an API request to http://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 channel.
A user watches a video and then subscribes to all videos matching a keyword associated with that video.
This use case begins with an API request to search for videos or to retrieve a particular video feed.
The user clicks on a video in the result set from step 1, prompting a second API request to retrieve information about that specific video. In this step, the user links to a page to watch the selected video.
The page where the user watches the video displays a list of keywords associated with the video and allows the user to subscribe to individual keywords. The user clicks a link to subscribe to a keyword.
Your application sends an API request to http://gdata.youtube.com/feeds/api/users/default/subscriptions to create the subscription. In the XML entry in your request, the <yt:queryString> tag's value is the keyword. The <category> tag's term attribute has a value of query.
The following sample API request demonstrates how to delete a subscription:
DELETE /feeds/api/users/USER_ID/subscriptions/SUBSCRIPTION_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
The following list identifies a common use case for deleting a subscription:
A user looks at his list of subscriptions and removes one or more from the list.
This use case begins with a request to retrieve a feed of the user's subscriptions.
Your application displays a list of the user's subscriptions, and the user selects one or more subscriptions to delete.
Your application loops through the selected subscriptions and sends an HTTP 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.
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.
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 an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.
http://gdata.youtube.com/feeds/api/users/default
To request another user's profile, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://gdata.youtube.com/feeds/api/users/username
In the URL above, you must replace the text username with the user's YouTube username.
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, inlcuding the number of people who have viewed the user's profile, the number of videos the user has watched and the number of people who subscribe to the user's uploaded 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:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/users/andyland74</id> <published>2006-10-16T00:09:45.000-07:00</published> <updated>2008-02-26T11:48:21.000-08:00</updated> <category scheme='http://gdata.youtube.com/schemas/2007/channeltypes.cat' term='Standard'/> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#userProfile'/> <title type='text'>andyland74 Channel</title> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile?user=andyland74'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:firstName>33</yt:firstName> <yt:lastName>Jones</yt:lastName> <yt:age>33</yt:age> <yt:username>andyland74</yt:username> <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: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 viewCount='9' videoWatchCount='21' subscriberCount='1' lastWebAccess='2008-02-25T16:03:38.000-08:00'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.favorites' href='http://gdata.youtube.com/feeds/api/users/andyland74/favorites' countHint='4'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.contacts' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts' countHint='1'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.inbox' href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox' countHint='0'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.playlists' href='http://gdata.youtube.com/feeds/api/users/andyland74/playlists'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.subscriptions' href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions' countHint='4'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.uploads' href='http://gdata.youtube.com/feeds/api/users/andyland74/uploads' countHint='1'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.newsubscriptionvideos' href='http://gdata.youtube.com/feeds/api/users/andyland74/newsubscriptionvideos'/> </entry>
The YouTube Data API enables a user to add, update or delete contacts.
This section explains how to retrieve a feed containing a list of a specific user's contacts.
To request the currently logged-in user's contact list, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.
http://gdata.youtube.com/feeds/api/users/default/contacts
To request another user's contact list, send an HTTP GET request to the following URL. Note that this request does not require authentication.
http://gdata.youtube.com/feeds/api/users/username/contacts
In the URL above, you must replace the text username with the user's YouTube username.
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 <category> tag indicates whether the contact is a friend or family.
The <yt:username> tag specifies the contact's YouTube username.
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:
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/opensearchrss/1.0/' xmlns:yt='http://gdata.youtube.com/schemas/2007'> <id>http://gdata.youtube.com/feeds/api/users/andyland74/contacts?start-index=1&max-results=25</id> <updated>2008-02-28T18:43:32.084Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#friend'/> <title type='text'>andyland74's Contacts</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile_friends?user=andyland74'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?start-index=1&max-results=25'/> <link rel='next' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?start-index=26&max-results=25'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' 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> <id>http://gdata.youtube.com/feeds/api/users/andyland74/contacts/danidanciu</id> <published>2007-01-06T09:38:08.000-08:00</published> <updated>2008-02-28T18:43:32.082Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#friend'/> <title type='text'>danidanciu</title> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/danidanciu'/> <link rel='alternate' type='text/html' href='http://www.youtube.com/profile?user=danidanciu'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts/danidanciu'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <yt:username>danidanciu</yt:username> <yt:status>accepted</yt:status> </entry> </feed>
To add a contact, you will send an API request that identifies two users: the user who is adding the contact and the contact being added. The request can also use the <category> tag to specify whether the contact is being added to the user's list of family or friends. If the request does not specify a category for the contact, then the contact will appear in the user's list of contacts but will not be placed into either the family or friends category.
The following request provides the URL and illustrates the XML format for adding a contact:
POST /feeds/api/users/default/contacts HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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/contact.cat" term="Friends"/> <yt:username>CONTACT_ID</yt:username> </entry>
The following list identifies a common use case for adding a contact:
A user watches a video and then adds the video owner as a friend.
This use case begins with a request to retrieve information about a specific video.
After watching the video, the user clicks a link to view the video owner's profile.
Your application submits an API request to retrieve the video owner's profile.
The page on your site that displays information about the video owner displays a link to add the video owner as a friend. If the user clicks this link, then your application submits an API request to http://gdata.youtube.com/feeds/api/users/default/contacts to create the contact. In the request, the <yt:username> tag identifies the YouTube user who is being added as a contact. In addition, the <category> tag's term attribute indicates whether the contact is a friend (term="Friends") or family (term="Family").
To update a contact, submit an HTTP PUT request to the edit url for that contact. The XML excerpt below shows how the edit URL appears in a contact entry:
<entry> <id>http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID</id> ... <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/USER_ID/contacts/CONTACT_ID'/> ... </entry>
The API enables a user to update a contact in two ways:
A user can accept a contact that has a status of requested. To update a contact in this fashion, in your API request, set the value of the <yt:status> tag to accepted as shown in the sample request below. (Similarly, to reject a contact, set the value of the <yt:status> tag to rejected.
Contacts can be categorized as friends or as family. You can use the API to recategorize contacts into either of these groups. If you categorize a contact as a friend, then the <category> tag's value must be Friends. If you categorize a contact as family, then the <category> tag's value must be Family.
The following sample request demonstrates how to update a contact. In the example, the contact is being accepted and classified as family. 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/USER_ID/contacts/CONTACT_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Content-Length: CONTENT_LENGTH Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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/contact.cat" term="Family"/> <status>accepted</status> </entry>
The following use case describes a scenario where a user would modify a contact:
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. To update or delete a contact, send an API request to the edit URL for that contact entry.
Your application displays the list of contacts as well as a select menu next to each contact allowing the user to recategorize the contact as family or as a friend. Your application also lets users accept or reject contacts that have a status of either pending or requested.
The user modifies one or more contacts and submits his changes.
Your application loops through the contacts and sends an HTTP PUT request to update each modified contact. Your application would submit each API request to the edit URL for the contact being updated.
The following sample API request demonstrates how to delete a contact.
DELETE /feeds/api/users/USER_ID/contacts/CONTACT_ID HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
The following list describes a common use case for deleting a contact:
As with the use case for modifying a contact, this use case begins with a request to retrieve a user's list of contacts.
Your application displays the list of contacts as well as a checkbox next to each contact allowing the user to delete that contact.
The user checks one or more contacts and submits his changes.
Your application loops through the contacts and sends an HTTP DELETE request to delete each selected contact. Your application would send each API request to the edit URL for the corresponding contact.
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.
To retrieve a feed containing a list of the messages in the currently logged-in user's inbox, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. This restriction ensures that a user can only retrieve messages from her own inbox. The authentication token enables YouTube to identify the user.
http://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 <yt:description> 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 <yt:description> 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 an HTTP 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/opensearchrss/1.0/' xmlns:gml='http://www.opengis.net/gml' xmlns:georss='http://www.georss.org/georss' xmlns:media='http://search.yahoo.com/mrss/' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'> <id>http://gdata.youtube.com/feeds/api/users/default/inbox</id> <updated>2008-06-10T20:55:40.271Z</updated> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#videoMessage'/> <title type='text'>Inbox of andyland74</title> <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo> <link rel='alternate' type='text/html' href='http://www.youtube.com/my_messages?folder=inbox&filter=videos'/> <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox?...'/> <author> <name>andyland74</name> <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri> </author> <generator version='beta' 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> <id> http://gdata.youtube.com/feeds/api/users/andyland74/inbox/ffb9a5f32cd5f55 </id> <published>2008-06-10T13:55:32.000-07:00</published> <category scheme='http://schemas.google.com/g/2005#kind' term='http://gdata.youtube.com/schemas/2007#videoMessage'/> <title type='text'>andyland74sFriend sent you a video!</title> <content type='text'>Check out this video!</content> <link rel='alternate' type='text/html' href='http://www.youtube.com/watch?v=jXE6G9CYcJs'/> <link rel='http://gdata.youtube.com/schemas/2007#video.responses' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/responses'/> <link rel='http://gdata.youtube.com/schemas/2007#video.ratings' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/ratings'/> <link rel='http://gdata.youtube.com/schemas/2007#video.complaints' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/complaints'/> <link rel='http://gdata.youtube.com/schemas/2007#video.related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/related'/> <link rel='related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs'/> <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox/ffb9a5f32cd5f55'/> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74/inbox/ffb9a5f32cd5f55'/> <author> <name>andyland74sFriend</name> <uri> http://gdata.youtube.com/feeds/api/users/andyland74sFriend </uri> </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'/> <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/ChoLENyDSANFEgGDA==/0/0/0/video.3gp' type='video/3gpp' medium='video' expression='full' duration='202' yt:format='1'/> <media:content url='rtsp://rtsp2.youtube.com/ChoLENyESARFEgGDA==/0/0/0/video.3gp' type='video/3gpp' medium='video' expression='full' duration='202' yt:format='6'/> <media:player url='http://www.youtube.com/watch?v=jXE6G9CYcJs'/> <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/2.jpg' height='97' width='130' time='00:01:41'/> <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/1.jpg' height='97' width='130' time='00:00:50.500'/> <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/3.jpg' height='97' width='130' time='00:02:31.500'/> <media:thumbnail url='http://img.youtube.com/vi/jXE6G9CYcJs/0.jpg' height='240' width='320' time='00:01:41'/> </media:group> <yt:statistics viewCount='56620' favoriteCount='67'/> <gd:rating min='1' max='5' numRaters='372' average='3.93'/> <gd:comments> <gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/jXE6G9CYcJs/comments' countHint='481'/> </gd:comments> <yt:description>Check out this video!</yt:description> </entry> </feed>
To send a message, you will send an authenticated HTTP POST request that identifies the user to whom the message is being sent. The XML sent in the request body specifies the <id> 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_USER_ID/inbox HTTP/1.1 Host: gdata.youtube.com Content-Type: application/atom+xml Authorization: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID 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>http://gdata.youtube.com/feeds/api/videos/Qm6znjThL2Y</id> <yt:description>sending a message from the api</yt:description> </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:
This use case begins with a request to retrieve information about a specific video.
After watching the video, the user clicks a link to share the video.
Your application submits a request to retrieve the contact list for the currently authenticated user.
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.
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.
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: AuthSub token="AUTHORIZATION_TOKEN" X-GData-Client: CLIENT_ID X-GData-Key: key=DEVELOPER_KEY
The following steps describe a common use case for deleting a message:
This use case begins with a request to retrieve the video messages in a user's inbox.
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.
The user checks one or more messages and submits her changes.
Your application loops through the messages and sends an HTTP DELETE request to delete each selected message. Your application would send each API request to the edit URL for the corresponding message.
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 (HTTP 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.
Note: Batch processing requests support query (HTTP 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 entire feed for the playlist.
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.
To submit a batch processing request, you will send an HTTP 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>http://gdata.youtube.com/feeds/api/users/USERNAME/playlists</id>
...
<link rel='http://schemas.google.com/g/2005#batch'
type='application/atom+xml'
href='http://gdata.youtube.com/feeds/api/users/USERNAME/playlists/batch'/>
...
In the example above, the batch URL for the user's playlists feed is http://gdata.youtube.com/feeds/api/users/USERNAME/playlists/batch.
Important: 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. However, every entry in the 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.
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.
The following batch processing request performs the following operations on a playlist:
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>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b</id> <batch:id>InsertedVideo1</batch:id> </entry> <entry> <batch:operation type="delete"/> <id>http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/77473B5FB369B676</id> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/77473B5FB369B676'/> </entry> <entry> <batch:operation type="delete"/> <id>http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/B21A4EE5CD829174</id> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/B21A4EE5CD829174'/> </entry> <entry> <id>http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/B7D3D08BD2F219CF</id> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/B7D3D08BD2F219CF'/> <yt:position>1</yt:position> </entry> <entry> <id>http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/E7F3D18BA3E217CB</id> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/E7F3D18BA3E217CB'/> <yt:position>2</yt:position> </entry> <entry> <id>http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/C1A3B17AC5E587AB</id> <link rel='edit' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2/C1A3B17AC5E587AB'/> <yt:position>3</yt:position> </entry> </feed>
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'?> <atom:feed xmlns:atom='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/' 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'> <atom:updated>2008-07-11T19:37:13.547Z</atom:updated> <atom:entry> <atom:id> http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/A5B2B2C5FFCF79AB </atom:id> <atom:title type='text'> Custom title for new video in playlist </atom:title> <yt:position>11</yt:position> <yt:description>The newest video in my playlist!</yt:description> <batch:id>InsertedVideo1</batch:id> <batch:status code='201' reason='Created'/> <batch:operation type='insert'/> </atom:entry> <atom:entry> <atom:id> http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/77473B5FB369B676 </atom:id> <atom:updated>2008-07-11T19:37:13.970Z</atom:updated> <atom:title type='text'>Deleted</atom:title> <atom:content type='text'>Deleted</atom:content> <batch:status code='200' reason='Success'/> <batch:operation type='delete'/> </atom:entry> <atom:entry> <atom:id> http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/B21A4EE5CD829174 </atom:id> <atom:updated>2008-07-11T19:37:13.970Z</atom:updated> <atom:title type='text'>Deleted</atom:title> <atom:content type='text'>Deleted</atom:content> <batch:status code='200' reason='Success'/> <batch:operation type='delete'/> </atom:entry> <atom:entry> <atom:id> http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/B7D3D08BD2F219CF </atom:id> ... <yt:position>1</yt:position> <batch:status code='200' reason='Success'/> <batch:operation type='update'/> </atom:entry> <atom:entry> <atom:id> http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/E7F3D18BA3E217CB </atom:id> ... <yt:position>2</yt:position> <batch:status code='200' reason='Success'/> <batch:operation type='update'/> </atom:entry> <atom:entry> <atom:id> http://gdata.youtube.com/feeds/playlists/8BCDD04DE8F771B2/C1A3B17AC5E587AB </atom:id> ... <yt:position>3</yt:position> <batch:status code='200' reason='Success'/> <batch:operation type='update'/> </atom:entry> </atom:feed>
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 http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b. But in the sample response, the <id> tag for that entry has the value http://gdata.youtube.com/feeds/playlists/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.
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"/>
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.
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:
You select an API operation that you want to perform. For example, you could search for (query) videos, retrieve standard feeds, 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.
Construct the API request.
Click the Submit button. The XML response will display at the bottom of the page.
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. 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: http://gdata.youtube.com/feeds/api/videos Stage: http://stage.gdata.youtube.com/feeds/api/videos Uploads: Production: http://uploads.gdata.youtube.com/feeds/api/videos Stage: http://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.
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.
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:
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>
The YouTube API supports two different URLs for retrieving information about a single video:
Please see the Retrieving information about a single video section for more information.
The YouTube Data API, like other Google Data APIs, supports ClientLogin authentication, which lets you associate all API actions with a single (YouTube) account. However, the YouTube Data API uses a different URL for authenticating users than other Google Data APIs.
To authenticate a user to use the YouTube API using ClientLogin, send a POST request to the following URL:
https://www.google.com/youtube/accounts/ClientLogin
Other Google Data APIs use the following URL for ClientLogin authentication:
https://www.google.com/accounts/ClientLogin
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.
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.
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.
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.
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.
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>
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'>http://gdata.youtube.com/feeds/users/username/uploads</location> </error> </errors>
An authentication error, which is identified by a <domain> tag value of yt:authentication, identifies a problem related to an improperly authenticated request to execute an API function requiring user authentication. 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 authentication 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 authentication 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>
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>
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 most_linked standard feed has been deprecated. Queries for this feed will now return an empty feed.
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 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 tag will not contain a <media:content> tag. However, it will contain a <yt:state> tag that indicates that the video is restricted.
This update contains the following changes:
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 <id>, 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 new 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.
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 an HTTP 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.
This update contains the following changes:
The category parameter now provides an alternate way to search for videos that are in certain categories or are tagged with particular keywords or developer tags. 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.
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.
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 in the Searching for videos section 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.
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.
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.
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.