Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.

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:

1. Videos feeds
2. Videos uploaded by a specific user
3. Standard video feeds
4. Related videos
5. User's favorites feed

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. You should not include search parameters in requests to retrieve an uploaded videos feed. The parameters will generate a feed from YouTube's search index, effectively restricting the result set to indexed, public videos, rather than returning a complete list of the user's uploaded videos.

• To request a feed of all videos uploaded by the currently logged-in user, send a GET request to the following URL. This request requires an authentication token, which enables YouTube to identify the user.

  https://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 URL, the value default 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 is also used to identify the currently logged-in user in other API commands.

• To request a feed of all videos uploaded by another user, send a GET request to the following URL. This request does not require authentication.

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

  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. You can extract the user ID from the <yt:userId> tag and the username from either the <name> or the <yt:username> tag in an API response. The XML excerpt below shows both values:

  <author>
    <name>GoogleDevelopers</name>
    <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
    <yt:userId>_x5XG1OV2P6uZZ5FSM9Ttw<</yt:userId>
  </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

Note: All standard video feeds except the most_popular feed have been deprecated. In response to requests for other feeds, the API will return the most_popular feed with a default time parameter value of today. In addition, if your request for another feed specifies a region or category, the API will return the most_popular feed for that region or category.

A standard feed contains a list of videos that either reflect YouTube user behavior. The only standard feed that the API still supports is the most_popular feed, which contains the most popular YouTube videos, selected using an algorithm that combines many different signals to determine overall popularity.

The most_popular feed supports the time query parameter, which can be set to either today or all_time. The feeds are updated periodically, but the feed that captures daily results may be updated more frequently. If you request a deprecated feed, and your request sets the time parameter value to all_time, the API will return a feed of YouTube's most popular videos of all time. Otherwise, the API will return the feed of the most popular videos for the past day.

To retrieve the most_popular feed, send a GET request to the following URL:

https://gdata.youtube.com/feeds/api/standardfeeds/most_popular

Note: The top_rated, top_favorites, most_shared, most_recent, most_discussed, most_responded, recently_featured, on_the_web, and most_viewed feeds have all been deprecated. The most_viewed feed was deprecated on July 23, 2012, and the remaining feeds were deprecated on September 12, 2013.

Retrieving region-specific standard video feeds

You can retrieve a region-specific version of the most_popular standard feed by inserting a region ID in the feed URL as shown below:

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

Note: If you request a deprecated standard feed, but your request specifies a region, the API will return the most_popular feed for that region.

The tables below list the countries for which the YouTube Data API supports localized feeds and the regionID associated with each country:

Retrieving category-specific standard video feeds

You can retrieve a category-specific version of the most_popular standard feed by appending an underscore and a category name to the feed URL as shown below:

https://gdata.youtube.com/feeds/api/standardfeeds/regionID/most_popular_CATEGORY_NAME?v=2

If you request a deprecated standard feed, but your request specifies a category, the API will return the most_popular feed for that category.

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 most popular entertainment videos in France:
  https://gdata.youtube.com/feeds/api/standardfeeds/FR/most_popular_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 most_popular 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 most popular nonprofit videos in the United States because "Nonprofit" is a browsable category in the United States. However, you cannot request the most popular nonprofit videos in France since "Nonprofit" is not a browsable category there.

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="https://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 authorization token in the Authorization HTTP request header. The token enables YouTube to verify that the user authorized access to the resource.

  http://gdata.youtube.com/feeds/api/users/default/favorites?v=2

• 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 user authorization.

  http://gdata.youtube.com/feeds/api/users/userId/favorites?v=2

  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.

By default, the favorites feed returns 25 entries at a time, and it returns a maximum of 50 entries at a time. 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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.