Printable versionThis section explains how to use the API to retrieve a list of videos matching a user-specified search term. To search for videos, submit an HTTP GET request to the following URL, appending the appropriate query parameters to your request:
http://gdata.youtube.com/feeds/api/videos
This page lists standard Google Data API parameters and custom parameters that the YouTube API supports. For example, a request to the following URL searches for the second set of 10 recently uploaded videos matching the query term "football" but not matching the query term "soccer":
|
http://gdata.youtube.com/feeds/api/videos?
q=football+-soccer
&orderby=published
&start-index=11
&max-results=10
&v=2
The YouTube Data API supports the following standard Google Data query parameters.
| Name | Definition |
|---|---|
| alt | The alt parameter specifies the format of the feed to be returned. Valid values for this parameter are atom, rss, json, and json-in-script. The default value is atom and this document only explains the format of Atom responses. For more information about using API responses in JavaScript, please see Using JSON with Google Data APIs. If you set the parameter value to json-in-script, then you must also set the callback parameter value to identify the callback function to which the API response will be sent. |
| author | In a search request, the author parameter restricts the search to videos uploaded by a particular YouTube user. Note that if you use this parameter when requesting a standard feed, then YouTube will retrieve the standard feed and then filter the response to only include videos uploaded by the specified author. For example, if you request the "Top Rated" feed for user GoogleDevelopers, the API will retrieve the top-rated feed and return a response containing videos in that feed uploaded by user GoogleDevelopers. The API will not return a list of that user's videos ordered by rating.
In a request for a user activity feed, the author parameter contains a comma-separated list of up to 20 YouTube usernames. The API response will contain activities performed by any of those users. |
| callback | The callback parameter, which is only used if the value of the alt parameter is json-in-script, identifies the callback function to which the API response will be sent. |
| max-results | The max-results parameter specifies the maximum number of results that should be included in the result set. This parameter works in conjunction with the start-index parameter to determine which results to return. For example, to request the second set of 10 results – i.e. results 11-20 – set the max-results parameter to 10 and the start-index parameter to 11. The default value of this parameter is 25, and the maximum value is 50. However, for displaying lists of videos, we recommend that you set the max-results parameter to 10. |
| prettyprint | The prettyprint parameter lets you request an XML response formatted with indentations and line breaks. Set the parameter's value to true to have the response formatted as such. The default parameter value is false. |
| start-index | The start-index parameter specifies the index of the first matching result that should be included in the result set. This parameter uses a one-based index, meaning the first result is 1, the second result is 2 and so forth. This parameter works in conjunction with the max-results parameter to determine which results to return. For example, to request the second set of 10 results – i.e. results 11-20 – set the start-index parameter to 11 and the max-results parameter to 10. |
| strict | The strict parameter can be used to instruct YouTube to reject an API request if the request contains invalid request parameters. The default API behavior is to ignore invalid request parameters. If you want YouTube to reject API requests that contain invalid parameters, set the strict parameter value to true. For example, YouTube would reject the following request because "foo" is not a valid request parameter.http://gdata.youtube.com/feeds/api/videos?foo=nonono&strict=true |
| v | The v parameter specifies the version of the API that YouTube should use to handle the API request. Your request can specify the desired API version using either the v parameter or the GData-Version HTTP request header. All Google-provided client libraries always select a major API version. If your request does not specify an API version, YouTube will handle your request using API version 1. Please see the API versioning section for more information about specifying an API version. |
Please see the Google Data APIs Protocol Reference for more information about standard Google Data API functionality or about these specific parameters.
In addition to the standard Google Data query parameters, the YouTube Data API defines the following API-specific query parameters:
|
Parameters for all API requests: client key Search parameters: caption category format location location-radius lr orderby q safeSearch time uploader |
Additional parameters for all video feeds: restriction |
In general, parameters that are used for filtering and ordering results are only supported for search requests. However, the API also supports the time parameter for many standard feeds, the author parameter for user activity feeds, and the restriction parameter for video feeds. Please see the Testing and troubleshooting section for tips on how to filter API response feeds that do not support these parameters.
The following table defines each of these parameters:
| Name | Definition | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| caption | The caption parameter, which is specified without a value, restricts the search to videos that have caption tracks. The example below shows how to request videos that have captions and that match the search term "surfing":
http://gdata.youtube.com/feeds/api/videos?q=surfing&caption&v=2 The API will return an HTTP 400 response if you specify the parameter with a value. |
||||||||
| category | The category parameter enables you to retrieve videos that are in a particular category or are tagged with a particular keyword or developer tag. You can also insert category names, keywords and developer tags into the request URL as described in the
Browsing with categories and keywords
section. That section provides instructions for formatting the category parameter value for a variety of different types of queries.
YouTube supports this parameter for video search requests. |
||||||||
| client | The client parameter is an alphanumeric string that identifies your application. The client parameter is an alternate way of specifying your client ID. You can also use the X-GData-Client request header to specify your client ID. Your application does not need to specify your client ID twice by using both the client parameter and the X-GData-Client request header, but it should provide your client ID using at least one of those two methods. | ||||||||
| format | The format parameter specifies that videos must be available in a particular video format. Your request can specify any of the following formats:
YouTube supports this parameter for video search requests. |
||||||||
| key | The key parameter specifies your developer key, an alphanumeric string that identifies the developer or company making an API request. You can also use the X-GData-Key request header to specify your developer key. Your application does not need to specify your developer key twice by using both the key parameter and the X-GData-Key request header, but it should provide your developer key using at least one of those two methods. | ||||||||
| location | The location parameter restricts the search to videos that have a geographical location specified in their metadata.
The parameter can be used in either of the following contexts:
YouTube supports this parameter for video search requests. |
||||||||
| location-radius | The location-radius parameter, in conjunction with the location parameter, defines a geographic area. If the geographic coordinates associated with a video fall within that area, then the video may be included in search results. The location-radius parameter value must be a floating point number followed by a measurement unit. Valid measurement units are m, km, ft and mi. For example, valid parameter values include "1500m", "5km", "10000ft" and "0.75mi". The API will return an error if the radius is greater than 1000 kilometers. YouTube supports this parameter for video search requests. |
||||||||
| lr | In a video search request, the lr parameter restricts the search to videos that have a title, description or keywords in a specific language. This parameter can be used when requesting any video feeds other than standard feeds. In a request to retrieve a list of the caption tracks available for a video, the lr parameter filters the list of caption tracks to only include the specified language. Valid values for the lr parameter are ISO 639-1 two-letter language codes. You can also use the values zh-Hans for simplified Chinese and zh-Hant for traditional Chinese. |
||||||||
| orderby | The orderby parameter, which is only supported for video feeds, specifies the value that will be used to sort videos in the search result set. Valid values for this parameter are relevance, published, viewCount and rating. In addition, you can request results that are most relevant to a specific language by setting the parameter value to relevance_lang_languageCode, where languageCode is an ISO 639-1 two-letter language code. (Use the values zh-Hans for simplified Chinese and zh-Hant for traditional Chinese.) In addition, please note that results in other languages will still be returned if they are highly relevant to the search query term. The default value for this parameter is relevance for a search results feed. Note: For a playlist feed, the default ordering is based on the position of each video in the playlist. For a user's playlists or subscriptions feed, the default ordering is arbitrary. YouTube supports this parameter for video search requests. |
||||||||
| q | The q parameter specifies a search query term. YouTube will search all video metadata for videos matching the term. Video metadata includes titles, keywords, descriptions, authors' usernames, and categories. Note that any spaces, quotes or other punctuation in the parameter value must be URL-escaped. To search for an exact phrase, enclose the phrase in quotation marks. For example, to search for videos matching the phrase "spy plane", set the q parameter to %22spy+plane%22. Your request can also use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several search terms. For example, to search for videos matching either "boating" or "sailing", set the q parameter to boating%7Csailing. (Note that the pipe character must be URL-escaped.) Similarly, to search for videos matching either "boating" or "sailing" but not "fishing", set the q parameter to "boating&7Csailing+-fishing". |
||||||||
| restriction | The restriction parameter identifies the IP address that should be used to filter videos that can only be played in specific countries. We recommend that you always use this parameter to specify the end user's IP address. (By default, the API filters out videos that cannot be played in the country from which you send API requests. This restriction is based on your client application's IP address.) To request videos playable from a specific computer, include the restriction parameter in your request and set the parameter value to the IP address of the computer where the videos will be played – e.g. restriction=255.255.255.255.To request videos that are playable in a specific country, include the restriction parameter in your request and set the parameter value to the ISO 3166 two-letter country code of the country where the videos will be played – e.g. restriction=DE.You should include this parameter in any request to retrieve a list of videos, including search results, playlists, favorite videos, video responses and so forth. If a video in the API response is not playable in the location that you're using to restrict availability of the content, the <entry> for that tag will not contain a <media:content> tag. However, it will contain a <yt:state> tag that indicates that the video is restricted. |
||||||||
| safeSearch | The safeSearch parameter indicates whether the search results should include restricted content as well as standard content. YouTube will determine whether content is restricted based on the user's IP address or location, which you specify in your API request using the restriction parameter. If you do request restricted content, then feed entries for videos that contain restricted content will contain the <media:rating> element. The following values are valid for this parameter:
Note: The safeSearch parameter was introduced in version 2 of the YouTube Data API and replaced the racy parameter, which was used in version 1. YouTube supports this parameter for video search requests. |
||||||||
| time | The time parameter restricts the search to videos uploaded within the specified time. Valid values for this parameter are today (1 day), this_week (7 days), this_month (1 month) and all_time. The default value for this parameter is all_time. This parameter is supported for search feeds as well as for the top_rated, top_favorites, most_viewed, most_popular, most_discussed and most_responded standard feeds. |
||||||||
| uploader | The uploader parameter, which is only supported for search requests, lets you restrict a query to YouTube partner videos. A YouTube partner is a person or organization that has been accepted into and participates in the YouTube Partner Program. The uploader parameter's value must be partner. In an API response, a feed entry contains a partner video if the entry contains a <media:credit> tag for which the value of the yt:type attribute is partner. <media:credit role="uploader" scheme="urn:youtube yt:type="partner">partner_name</media:credit> YouTube supports this parameter for video search requests. |