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:
- Videos feeds
- Videos uploaded by a specific user
- Standard video feeds
- Related videos
- User's favorites feed
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:
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.
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.
In the URL above, you should replace the text
userIdwith 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
<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.
most_popular feed supports the time query parameter, which can be set to either
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:
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:
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:
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.
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_popularfeed 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.
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.
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.
In the URL above, you should replace the text
userIdwith 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.