YouTube API v2.0 – Favorite Videos

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information. Please use the YouTube Data API (v3) for new integrations and migrate applications still using the v2 API to the v3 API as well.

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 page contains the following sections:

1. Retrieving a user's favorite videos
2. Adding a favorite video
3. Deleting a favorite video

Retrieving a user's favorite videos

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 a GET request to the following URL. Note: For this request, you must provide an authentication token, which enables YouTube to identify the user.

  https://gdata.youtube.com/feeds/api/users/default/favorites

• To request a feed of another user's favorite videos, send a GET request to the following URL. Note that this request does not require authentication.

  https://gdata.youtube.com/feeds/api/users/userId/favorites

  In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

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.

Adding a favorite video

To add a favorite video, you must provide the video ID that YouTube uses to uniquely identify that video. The following request shows the URL and format of an XML request to add 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: Bearer ACCESS_TOKEN
GData-Version: 2
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.

  1. This use case begins with an API request to obtain information about a specific video.

  2. After watching the video, the user elects to flag the video as a favorite video.

  3. Your application sends a POST request to https://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.

  1. This use case begins with a request to search for videos or to retrieve a particular video feed.

  2. The user selects one or more videos from the list – for example, the user could check a box next to each video.

  3. Your application loops through the selected videos and sends a POST request to add each selected video as a favorite. Your application sends each request to https://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.

Deleting a favorite video

To delete a favorite video, send a DELETE request to the edit URL for the video entry:

<link rel='edit' type='application/atom+xml'
   href='https://gdata.youtube.com/feeds/api/users/default/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 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/default/favorites/FAVORITE_VIDEO_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
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:

1. This use case begins with a request to retrieve a feed of the user's favorite videos.

2. The user selects one or more videos from the list – for example, the user could check a box next to each video.

3. Your application loops through the selected videos and sends a 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.