YouTube

YouTube API v2.0 – API Query Parameters

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 section explains how to use the API to retrieve a list of videos matching a user-specified search term. To search for videos, send a GET request to the following URL, appending the appropriate query parameters to your request:

https://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":

https://gdata.youtube.com/feeds/api/videos?
    q=football+-soccer
    &orderby=published
    &start-index=11
    &max-results=10
    &v=2

Standard Google Data API query parameters

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, json-in-script, and jsonc. 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 "Most Popular" 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, and if the specified author does not have any of YouTube's most popular videos, the feed will be empty.

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 identifies the callback function to which the API response will be sent. If the value of the alt parameter is jsonc or json-in-script, and you specify a value for the callback parameter, then the API response will be wrapped in a call to the specified function. This parameter is required if the value of the alt parameter is json-in-script.
fields The fields parameter serves one or both of the following purposes:
  • It identifies the data fields that should be included in a partial API response.
  • It specifies conditions that should be used to filter the result set.
The parameter value is formatted using a syntax inspired by XPath as described in the Formatting the fields parameter value section. That section also explains how conditions specified in the parameter value are applied since the API handles filters identified in the fields parameter value differently than filters identified in other query parameters, such as the category or q parameters.
fields-language The fields-language parameter is being used temporarily to force the API server to apply new syntax rules affecting requests to retrieve partial API responses. The rules determine whether a tag's text content is returned in a partial response. They also let you filter results based on the presence of an element that does not contain text content. For example, you could retrieve all entries containing the <app:control> tag, which has subtags but does not contain text content. The new rules are explained in detail in the release notes for August 31, 2010.



To use the new syntax rules for partial API responses, or to filter results based on the presence of an element that does not contain text content, set the fields-language parameter value to r2. (This is the only valid value for this parameter.)

Note: Following a testing period, the new syntax rules will apply to all requests for partial API responses, and the API server will ignore the fields-language parameter.
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.
https://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.

The current API version is 2. Setting the v parameter value (or the GData-Version HTTP request header value) to 2 allows your application to access features that may not be available in previous API versions. For example, captions are only supported in API version 2, and the API supports some different parameters in version 2 than it did in version 1.

Please see the Google Data APIs Protocol Reference for more information about standard Google Data API functionality or about these specific parameters.

Custom query parameters for the YouTube Data API

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:
key

Search parameters:
3d
caption
category
duration
format
hd
license
location
location-radius
lr
orderby
q
safeSearch
time
uploader

Additional parameters for all video feeds:
restriction

Additional parameters for caption track feeds:
fmt
lang

Additional parameters for user activity feeds:
inline
Additional parameters for movie charts:
hl
movie-genre
paid-content
region

Additional parameters for show charts:
genre
region

Additional parameters for YouTube EDU feeds:
category
course

Additional parameters for live event feeds: (deprecated)
ends-after
ends-before
inline
starts-after
starts-before
status
time

Additional parameters for username suggestion feeds:
hint

In general, parameters that are used for filtering and ordering results are only supported for search requests, though there are several exceptions listed above. The API also supports the time parameter for the most_popular standard video feed, 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.

In particular, you should not include search parameters in requests to retrieve an uploaded videos feed. By doing so, you are instructing the API to generate a feed from YouTube's search index, effectively restricting the result set to indexed, public videos rather than retrieving a complete list of the user's uploaded videos.

The following table defines the API's custom search parameters:

Name Definition
3d The 3d parameter lets you restrict a search to only retrieve 3D videos. This parameter is supported for video search requests, related videos feeds, and standard feeds. It is also only supported in API version 2.

To only retrieve 3D videos, set the 3d parameter value to true or include the parameter in your request but do not specify a parameter value. Note that false is not a valid parameter value, and you cannot restrict search results to exclude 3D videos. The API's default behavior is to include both 3D and non-3D videos in returned results. In a video feed entry, the <yt:threed> tag indicates that a video contains 3D content.

Note: The API will return an HTTP 400 response if you specify any parameter value other than true.
caption The caption parameter enables you to restrict a search to videos that have or do not have caption tracks:
  • To only request videos that have captions, set the caption parameter value to true. For example, the URL below would retrieve videos that have captions and that match the search term "surfing":

    https://gdata.youtube.com/feeds/api/videos?q=surfing&caption&v=2
    

    Note: For backward-compatibility reasons, the API will also only return videos that have captions if you include the caption parameter but do not specify a parameter value.

  • To only request videos that do not have captions, set the caption parameter value to false. For example, the URL below would retrieve videos that do not have captions and that match the search term "surfing":

    https://gdata.youtube.com/feeds/api/videos?q=surfing&caption=false&v=2
    
Note: The API will return an HTTP 400 response if you specify the parameter with any value other than true or false.
category The category parameter has two uses:
  • In video search requests, it 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.

  • In requests to retrieve YouTube EDU content, it specifies the YouTube EDU category that courses or lectures must be associated with to be included in the API response.

client Deprecated on March 22, 2010. API requests no longer need to specify a client ID.

The client parameter specifies an alphanumeric string that identifies the developer or distributor of an 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.
course The course parameter lets you retrieve a list of lectures (videos) associated with the specified course. The parameter's value is a YouTube playlist ID that uniquely identifies a course that is accessible via YouTube EDU.
duration The duration parameter lets you filter search results based on video length. The following parameter values are valid:
  • short – Only include videos that are less than four minutes long.
  • medium – Only include videos that are between four and 20 minutes long (inclusive).
  • long – Only include videos longer than 20 minutes.
In a video feed entry, the <yt:duration> tag specifies a video's length.
ends-after
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

The ends-after parameter restricts a live events feed to only include events that ended or are scheduled to end at or after the specified date and time. The parameter value must be a date or a date and time in ISO 8601 format.
  • If you specify a date, but not a time, the API response will include events that ended on or after the specified date. For example, if you set the parameter value to 2011-06-15, the API will include events that ended on June 15, 2011, in the response.
  • If you specify a date and a time, the API response will include events that ended at or after the specified time.
ends-before
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

The ends-before parameter restricts a live events feed to only include events that ended or are scheduled to end at or before the specified date and time. The parameter value must be a date or a date and time in ISO 8601 format.
  • If you specify a date, but not a time, the API response will include events that ended before the specified date. For example, if you set the parameter value to 2011-06-15, the API will return events that ended on June 14, 2011, but not events that ended on June 15, 2011.
  • If you specify a date and a time, the API response will include events that ended at or before the specified time.
fmt The fmt parameter specifies the return format for a caption track that you are retrieving via the API. Set the parameter value to one of the following values:

  • sbv – Subviewer-compatible
  • srt – Subrip-compatible
If you are retrieving a caption track generated using automatic speech recognition and you do not set a value for this parameter, the API will automatically return the track in Subviewer-compatible (sbv) format.

The API will return an HTTP 400 response code if YouTube cannot convert the original caption track to the requested format.
format The format parameter, which is supported for video search requests, specifies that videos must be available in at least one of the video formats listed in the parameter value. Your request can specify one or more of the following formats:

Value Video Format
1 RTSP streaming URL for mobile video playback. H.263 video (up to 176x144) and AMR audio.
5 HTTP URL to the embeddable player (SWF) for this video. This format is not available for a video that is not embeddable. Developers commonly add &format=5 to their queries to restrict results to videos that can be embedded on their sites.
6 RTSP streaming URL for mobile video playback. MPEG-4 SP video (up to 176x144) and AAC audio.


To specify multiple formats, separate format values with a comma. For example, format=1,5 indicates that the API should return videos that are available in at least one of those two formats.
genre The genre parameter restricts a show chart to only include shows in a particular genre. The parameter value is an integer that corresponds to a particular genre. The following values are valid:

  • 1 – Action & Adventure
  • 2 – Animation & Cartoons
  • 3 – Classic TV
  • 4 – Comedy
  • 5 – Drama
  • 6 – Home & Garden
  • 7 – News
  • 8 – Reality & Game Shows
  • 9 – Science & Tech
  • 10 – Science Fiction
  • 11 – Soaps
  • 13 – Sports
  • 14 – Travel
  • 16 – Entertainment
  • 17 – Documentary
  • 20 – Nature
  • 21 – Beauty & Fashion
  • 23 – Food
  • 24 – Gaming
  • 25 – Health & Fitness
  • 26 – Learning & Education
  • 27 – Foreign Language

hd The hd parameter lets you restrict a search to only include HD videos, meaning videos that are available for playback in at least 720p. Higher resolutions, like 1080p, might be available for HD videos as well. This parameter is supported for video search requests, related videos feeds, and standard feeds. It is also only supported in API version 2.

To only retrieve HD videos, set the hd parameter value to true or include the parameter in your request but do not specify a parameter value. Note that false is not a valid parameter value, and you cannot restrict search results to exclude HD videos. The API's default behavior is to return all videos, regardless of their resolution. In a video feed entry, the <yt:hd> tag indicates that a video contains HD content.

Note: The API will return an HTTP 400 response if you specify any parameter value other than true.
hint Deprecated. The hint parameter, which is now deprecated, was specified in a request to retrieve a list of unused YouTube channel names similar to that hint.
hl The hl parameter specifies the primary language of the movies in a movie chart. The parameter value is an ISO 639-1 two-letter language code.
inline The inline parameter is only supported for activity feeds and live event feeds.
  • In a request to retrieve an activity feed, this parameter indicates whether events in the feed that involve videos – video_rated, video_shared, video_favorited, video_commented and video_uploaded – will include a video entry that contains all of the metadata for that video. If the video entry is included, it will be encapsulated inside the <link> element that has a rel attribute value of http://gdata.youtube.com/schemas/2007#video.

    Set the parameter's value to true to specify that video entries should be embedded inside the activity feed.
  • In a request to retrieve a live events feed, this parameter indicates whether events in the feed will include a live video entry or a playlist entry that contains information about the event's video stream or streams, respectively. If an entry is inlined, it will be encapsulated inside the event entry's <content> element.

    Set the parameter value to true to specify that video (or playlist) entries should be embedded in the event entries.
The default parameter value is false.
key The key parameter specifies your developer key, an alphanumeric string that uniquely identifies the application 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.
lang The lang parameter specifies the language into which you want a caption track to be translated. Set the parameter value to the ISO 639-1 two-letter language code that identifies the desired caption language.

YouTube supports this parameter for requests to retrieve a caption track. The API will return an HTTP 400 response code if YouTube cannot translate the caption track to the requested language or if the language code that you specified is not valid.
license The license parameter lets you filter search results to only include videos with a particular license. YouTube lets video uploaders choose to attach either the Creative Commons license or the standard YouTube license to each of their videos, and the license parameter supports the following values:
  • cc – Only return videos that have a Creative Commons license. Users can reuse videos with this license in other videos that they create. Learn more.
  • youtube – Only return videos that have the standard YouTube license.
The API's default behavior is to return all videos, regardless of which license they have. In a video feed entry, the <media:license> tag identifies the license that is associated with a video.
location Not working. This API parameter is temporarily disabled. See the API issue tracker for more information.

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:

  • The parameter value can specify geographic coordinates (latitude,longitude) that identify a particular location. In this context, the location parameter operates in conjunction with the location-radius parameter to define a geographic area. The API response will then contain videos that are associated with a geographical location within that area.

    Note that when a user uploads a video to YouTube, the user can associate a location with the video by either specifying geographic coordinates (-122.08427,37.42307) or by providing a descriptive address (Munich, Germany). As such, some videos may be associated with a location within the area specified in a search query even though those videos are not associated with specific coordinates that can be plotted on a map.

    To exclude videos from the API response if those videos are associated with a descriptive address but not with specific geographic coordinates, append an exclamation point ("!") to the end of the parameter value. This practice effectively ensures that all videos in the API response can be plotted on a map.

    The following examples show sample uses of this parameter:

    location=37.42307,-122.08427&location-radius=100km
    location=37.42307,-122.08427!&location-radius=100km
    

    In an API response, feed entries that are associated with specific coordinates will contain the <georss:where> tag and may also contain the <yt:location> tag. Feed entries that are associated with a descriptive address but not with specific geographic cooordinates specify the address using the <yt:location> tag.

  • The parameter value can be empty or a single exclamation point. In this context, the parameter does not require a value and its presence serves to restrict the search results to videos that have a geographical location, but it does not enable you to find videos with a specific geographical location. This parameter can be used with all video feeds. A video that has a geographical location will have a <georss:where> tag in its metadata.


YouTube supports this parameter for video search requests.
location-radius Not working. This API parameter is temporarily disabled. See the API issue tracker for more information.

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.
movie-genre The movie-genre parameter restricts a movie chart to only include movies in a particular genre. The parameter value is an integer that corresponds to a particular genre. The following values are valid:

  • 1 – Action & Adventure
  • 2 – Animation & Cartoons
  • 3 – Classics
  • 4 – Comedy
  • 5 – Crime
  • 6 – Drama
  • 7 – Documentary & Biography
  • 8 – Family
  • 9 – Foreign
  • 10 – Horror
  • 11 – Mystery & Suspense
  • 12 – Romance
  • 13 – Science Fiction
  • 15 – Sports
  • 18 – Indian Cinema
  • 19 – Nigerian Cinema

orderby The orderby parameter, which is supported for video feeds and playlist feeds, specifies the method that will be used to order entries in the API response. The parameter is used differently for video and playlist feeds:

  • In a request for a video feed, the following values are valid for this parameter:
    • relevance – Entries are ordered by their relevance to a search query. This is the default setting for video search results feeds.
    • published – Entries are returned in reverse chronological order. This is the default value for video feeds other than search results feeds.
    • viewCount – Entries are ordered from most views to least views.
    • rating – Entries are ordered from highest rating to lowest rating.
    When searching for videos, you can also 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.) Please note that results in other languages will still be returned if they are highly relevant to the search query term.
  • In a request for a playlist feed, the following values are valid for this parameter:
    • position – Entries are ordered by their position in the playlist. This is the default setting.
    • commentCount – Entries are ordered by number of comments from most comments to least comments.
    • duration – Entries are ordered by length of each playlist video from longest video to shortest video.
    • published – Entries are returned in reverse chronological order.
    • reversedPosition – Entries are ordered in reverse of their position in the playlist.
    • title – Entries are ordered alphabetically by title.
    • viewCount – Entries are ordered from most views to least views.
Note: A user's playlists feed is ordered by publication time beginning with the newest playlist. For a user's subscriptions feed, the default ordering is arbitrary.
The paid-content parameter can be used to restrict a search or a movie chart to only include either paid content or free content. By default, search results and movie charts include both paid and free content.
  • To restrict a result set to only include paid content, set the paid-content parameter value to true or include the parameter in your request but do not specify a parameter value.
  • To restrict a result set to exclude paid content, set the paid-content parameter value to false.
Using the paid_content parameter for movie charts

For paid content, the video uploader will define offers that specify the country where a video can be rented. For example, a movie may be available for rental in the United States before it can be rented in other countries. As such, you must also specify a value for the region parameter if you want any paid content to be included in the API results.

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.
region The region parameter restricts a movie or show chart to only list content that is viewable in a specified region. If set, the parameter value must be an ISO 3166-1 alpha-2 country code. The default behavior is to return content that is viewable worldwide.

Important: You must specify a region parameter value if you want a movie chart to include rental (paid-content) videos. If you do not specify a value for this parameter, the chart will only contain movies that are viewable worldwide. Since each video rental offer specifies the country where the offer is valid, YouTube can only determine whether a user could potentially view a rental video if an API request specifies the country where the user is located. Since there are no rental videos that are accessible worldwide, a chart will be empty if you set the paid-content parameter to true for a movie chart and do not also specify a region parameter value.

restriction The restriction parameter lets the API server apply country restrictions that are based on the end user's location for videos that can only be played in specific countries. The parameter value identifies the end user's IP address to the API server. We recommend that you always use this parameter to specify the end user's IP address. However, it is particularly important to set this parameter when a server or middle layer in your application stack uses the API on the end user's behalf and also sends all of the API requests on the user's behalf. This case usually applies to website applications that use the API.

If you do not set the restriction parameter value, then the API server might apply country restrictions incorrectly. For example, it might base restrictions on your middle-layer server's location rather than on the end user's actual location. Note that the API's Terms of Service prohibit lying about an end user's location to circumvent these restrictions.

There are two ways to use this parameter:
  • To request videos playable from a specific IP address, 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, 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:
Value Description
none YouTube will not perform any filtering on the search result set.
moderate YouTube will filter some content from search results and, at the least, will filter content that is restricted in your locale. Based on their content, search results could be removed from search results or demoted in search results. Note: The default value for the safeSearch parameter is moderate.
strict YouTube will try to exclude all restricted content from the search result set. Based on their content, search results could be removed from search results or demoted in search results.
SafeSearch filtering for the YouTube Data API is designed to function similarly to SafeSearch Filtering for Google WebSearch results. Please note that YouTube makes every effort to remove restricted content from search results in accordance with the SafeSearch setting that you specify. However, filters may not be 100% accurate and restricted videos may occasionally appear in search results even if you have specified strict SafeSearch filtering. If this happens, please flag the video by filing a complaint, which will help us to better identify restricted content.

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.
starts-after
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

The starts-after parameter restricts a live events feed to only include events that began or are scheduled to begin at or after the specified date and time. The parameter value must be a date or a date and time in ISO 8601 format.
  • If you specify a date, but not a time, the API response will include events that started on or after the specified date. For example, if you set the parameter value to 2011-06-15, the API will include events that started on June 15, 2011, in the response.
  • If you specify a date and a time, the API response will include events that started at or after the specified time.
starts-before
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

The starts-before parameter restricts a live events feed to only include events that began or are scheduled to begin at or before the specified date and time. The parameter value must be a date or a date and time in ISO 8601 format.
  • If you specify a date, but not a time, the API response will include events that started before the specified date. For example, if you set the parameter value to 2011-06-15, the API will return events that started on June 14, 2011, but not events that started on June 15, 2011.
  • If you specify a date and a time, the API response will include events that started at or before the specified time.
status
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

The status parameter restricts a live event feed to only list events with the specified status. The following values are valid:
  • pending – The event has not started yet.
  • active – The event has already started but has not yet ended.
  • completed – The event has already ended.
  • delayed – The event has not yet started and will start later than its originally scheduled time.
  • cancelled – The event, though scheduled, will not happen.
  • rejected – YouTube will not stream the event.
time The time parameter is supported for search feeds and the most_popular standard video feed. 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.
  • In a request to retrieve search results, the time parameter restricts the search to videos uploaded within the specified time.
  • In a request to retrieve a standard feed, the time parameter restricts the API response to only contain results relevant to the specified time frame. For example, if the time parameter value is set to all_time in a request for the most_popular standard video feed, the feed will contain the most popular videos on YouTube based on a number of different popularity signals.

    This parameter is supported for the following feeds and charts:
    • most_popular standard video feed – This feed only supports the parameter values today and all_time.
    • Standard channel feeds
      • most_subscribed – This feed only supports the parameter values this_week, this_month, and all_time.
      • most_viewed
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:display='partner_name'
  yt:type='partner'>partner_name</media:credit>

YouTube supports this parameter for video search requests.
pagination links

« Previous
Browsing with Categories and Keywords
Next »
Retrieving Data for a Single Video

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.