Developer's Guide: Data API Protocol – Video Feed Types

This page describes several different types of video feeds that can be retrieved using the YouTube API. A video feed contains a list of videos that would be displayed in a list on your site. You can use standard API query parameters to customize the number of videos that you retrieve.

This page explains how to retrieve the following types of video feeds:

Videos feeds

The API returns a videos feed in response to a request to search for videos. A videos feed contains a maximum of 999 entries. To retrieve search results, send an API request to the following URL:

http://gdata.youtube.com/feeds/projection/videos?v=2

Search requests can use any of the API's standard or custom query parameters. For example, the following URL requests all videos related to the query "skateboarding dog," starting with the 21st search result and returning 10 results:

http://gdata.youtube.com/feeds/api/videos?
     q=skateboarding+dog
     &start-index=21
     &max-results=10
     &v=2

Videos uploaded by a specific user

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.

Standard video feeds

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:

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.

Retrieving region-specific standard feeds

The API enables you to retrieve region-specific standard feeds by inserting a region ID in the standard feed URL. The following URL demonstrates the format of the URLs that you would use to retrieve region-specific standard feeds:

http://gdata.youtube.com/feeds/api/standardfeeds/regionID/feedID?v=2

For example, to retrieve a list of the top-rated videos in Japan, you would send an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/standardfeeds/JP/top_rated?v=2

Note: Region-specific versions of the watch_on_mobile standard feed are not available.

The following table identifies the countries for which the YouTube Data API supports localized feeds and the regionID associated with each country:

Retrieving category-specific standard feeds

The API also enables you to retrieve category-specific standard feeds by appending an underscore and a category name to the standard feed URL. inserting a region ID in the standard feed URL. The following URL demonstrates the format of the URLs that you would use to retrieve region-specific standard feeds:

http://gdata.youtube.com/feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME?v=2

For example, to retrieve a list of the top-rated comedies in Japan, you would send an HTTP GET request to the following URL:

http://gdata.youtube.com/feeds/api/standardfeeds/JP/top_rated_Comedy?v=2

Please note the following guidelines when generating URLs for category-based standard feeds:

• The Category list for uploaded videos section explains how to retrieve the categories that could be used to classify video content. That section also explains how to identify the regions where each category is browsable.

• If you retrieve a localized category list, the category name that you append to the URL is still the English word that is the value of the <atom:category> tag's term attribute in the category list.

  Category listing:
  <atom:category term='Entertainment' label='Divertissement' xml:lang='fr-FR'>
  
  URL for feed of top-rated entertainment videos in France:
  http://gdata.youtube.com/feeds/api/standardfeeds/FR/top_rated_Entertainment
  

• The regionID in the feed URL is optional. If you do not specify a region ID, the API response will contain a category-based standard feed that is not restricted to a particular locale.

• If your request does specify a regionID, then the specified category must be browsable in the specified region. For example, you can request a feed of the top-rated nonprofit videos in the United States because "Nonprofit" is a browsable category in the United States. However, you cannot request the top-rated nonprofit videos in France since "Nonprofit" is not a browsable category there.

Video responses

A video responses feed contains videos that have been explicitly designated as a response to another video. A video can be designated as a video response to exactly one other video, and 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 as shown in the following example.)

<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?v=2"/>

Related videos

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?v=2"/>

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.

User's favorites feed

The favorite videos feed retrieves a list of videos that a particular user has explicitly flagged as a favorite video. On YouTube's website, 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.

• 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?v=2

• 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?v=2

  In the URL above, you must replace the text username with the user's YouTube username.

The favorites feed returns a maximum of 50 entries. We strongly recommend that you paginate the feed by using the start-index and max-results query parameters to optimize the response size and latency. The recommended value for max-results is 10, yielding a response that contains about 60KB of data.