Printable versionA 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 page contains the following sections:
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 a favorite videos feed is almost identical to a typical video feed or search results feed. (A sample video feed is shown in the Understanding video feeds and entries section of this document.) However, the favorite videos feed differs a typical video feed in the following ways:
The value of the term attribute for each <category> tag in the feed will be http://gdata.youtube.com/schemas/2007#favorite rather than http://gdata.youtube.com/schemas/2007#video, identifying the feed contents as favorite videos.
The <published> tag in a favorite videos feed entry identifies the time that the video was marked as a favorite and not the time that the video was published.
The <author> tag in a favorite videos feed entry identifies the person who marked the video as a favorite. The <media:credit> tag identifies the owner of the video. In a typical videos feed, both tags identify the video owner.
Each entry in a favorite videos feed contains a <link> tag for which the rel attribute value is related. You can use this link to navigate from the favorite video entry to the standard video entry for that video.
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" GData-Version: 2 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 <yt:videoid> 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 <yt:videoid> for that video but a different value that uniquely associates the video with the user who marked it as a favorite. To delete a favorite video, always send the 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" GData-Version: 2 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.
|
