Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.
Contents
- Overview
- Projection values
- Feed Types
- Navigating between feeds
- HTTP response codes for YouTube Data API requests
- Searching for videos
- XML element definitions
- Atom elements reference
- OpenSearch elements reference
- YouTube elements reference
- yt:aboutMe
- yt:accessControl
- yt:age
- yt:archived
- yt:aspectratio
- yt:audioTracks
- yt:availability
- yt:books
- yt:captionTracks
- yt:cdn
- yt:channelId
- yt:channelStatistics
- yt:company
- yt:contentType
- yt:countHint
- yt:derived
- yt:duration
- yt:episode
- yt:favoriteId
- yt:firstName
- yt:firstReleased
- yt:gender
- yt:googlePlusUserId
- yt:groupId
- yt:hd
- yt:hobbies
- yt:hometown
- yt:incomplete
- yt:lastName
- yt:location
- yt:material
- yt:maxUploadDuration
- yt:movies
- yt:music
- yt:noembed
- yt:occupation
- yt:option
- yt:playlistId
- yt:position
- yt:private
- yt:rating
- yt:recorded
- yt:relationship
- yt:schedule
- yt:school
- yt:season
- yt:spam
- yt:state
- yt:statistics
- yt:status
- yt:threed
- yt:unreadCount
- yt:uploaded
- yt:uploaderId
- yt:userId
- yt:username
- yt:videoid
- yt:when
- Media RSS elements reference
- GData elements reference
- GeoRSS elements reference
- GML elements reference
- Atom Publishing Protocol element reference
- Browser-based upload API response elements reference
- Batch processing element reference
- Error response element reference
- Appendixes
- Revision History
Overview
This document is intended for programmers who are writing client applications that interact with YouTube. The document supplements the information in the developer's guide protocol as well as the language-specific guides for Java, PHP and Python developers.
This document lists the different types of feeds that you can retrieve using the YouTube Data API. It also provides diagrams that explain how to navigate between different feeds – for example, the diagrams show that a user's playlists feed contains URLs that reference individual playlists and data such as a user's profile. The diagrams also indicate how you would navigate from one feed to another. Finally, this document defines the parameters used in YouTube Data API requests as well as the XML tags returned in an API response. For Java, PHP and Python developers, the XML tags may correspond directly to a property of a VideoEntry, ProfileEntry or other type of object.
Expected latency for data updates
The YouTube Data API retrieves search results from a specially optimized search index. The index is designed to include new videos as quickly as possible while ensuring high performance even under heavy API server loads. Please note that there may be delays between the time that a video is uploaded or updated and the time the new information is included in video feeds. The following list provides expected data latencies for various API functions:
- Standard feeds are updated periodically, with the update frequency varying from feed to feed. Many feeds are updated every 30 to 40 minutes but other feeds – such as those that capture daily, weekly or monthly results – may only be updated hourly or even daily.
- Uploaded videos will be included in a user's public uploaded videos feed a few minutes after the upload completes and YouTube finishes processing the video.
- Uploaded videos will usually be available in search feeds within 30 minutes to two hours after the upload completes and YouTube finishes processing the video. However, this delay may be longer under heavy API server loads.
- Video metadata updates are typically reflected in search feeds within 30 minutes to two hours after the upload completes. However, this delay may be longer under heavy API server loads, and updates may take up to 24 hours to show up.
- Deleted videos will usually be removed from a user's public uploaded videos feed within 30 minutes to two hours after the upload completes. However, this delay may be longer under heavy API server loads.
- Statistics, such as the number of times a video has been viewed or the number of comments available for a video, are typically updated within 30 minutes to two hours after the upload completes. However, this delay may be longer under heavy API server loads.
- On an ongoing basis, statistics for a video are typically updated every 30 minutes to two hours. However, updates may occur less frequently under heavy server loads or for videos that are viewed very infrequently. In search feeds, updates to ratings and view counts could take as long as a couple of weeks for infrequently viewed videos.
- Events that are listed in activity feeds will usually be available in those feeds within 30 minutes of the times that they occur.
Projection values
The YouTube Data API offers different views, or projections, of the data available in the API. A projection changes the structure of a feed but does not alter the content of a feed. As such, two different projections of the same feed will identify the same items, but will use different sets of XML tags. For example, the mobile
projection returns a subset of the tags that the api
projection returns.
The Developer's Guide and the examples in this document all use the api
projection, which supports all of the tags defined in the XML element definitions section of this document.
All API requests must specify a projection.
Most developers who are using this documentation will use the api
projection. However, if you are developing applications for mobile devices, you can substitute mobile
for api
in any of the sample requests described in the API documentation. Similarly, if you prefer to use the base
projection, which is well suited to feed readers, you can substitute base
for api
in any of the sample requests described in the API documentation.
The following table describes the supported projection values:
Projection Name | Description |
---|---|
api |
This projection yields feeds that support all of the XML elements defined in this document, including all relevant tags in the YouTube and Media RSS schemas. All properties contain plain text, not HTML. |
base |
This projection yields basic Atom feeds without any extension elements. Its <atom:summary> and <atom:content> properties contain entity-encoded HTML. |
mobile |
This projection filters out some of the XML elements that would not be used by developers building mobile applications, allowing for a rich user experience while also reducing bandwidth usage for mobile users. Note that this projection does not ensure that an API response only contains videos suitable for mobile playback. To ensure that an API response only includes videos suitable for playback on a mobile device, add the fields parameter to the API request URL with the value shown below: fields=entry[link/@rel='http://gdata.youtube.com/schemas/2007%23mobile'] See the Retrieving a partial response section of the Developer's Guide for more information about partial responses. |
Feed Types
You can retrieve the following types of feeds from the YouTube Data API:
User's playlists feed
User's subscriptions feed
Video comments feed
User profile entry
User's contacts feed
The API allows you to submit an unauthorized request to retrieve any of these feeds. However, in some cases, an authorized request may retrieve additional information. For example, if you submit an authorized request for a user's own list of uploaded videos, the feed will contain private videos as well as rejected or pending videos. Private, pending and rejected videos would not appear in a response to an unauthorized API request or a request for videos uploaded by someone other than the currently authenticated user.
To add or update videos, playlists, subscriptions, ratings, comments or any other entity, you must authorize all requests, including GET requests, using a developer key and OAuth 2.0 authorization. (Several other supported authorization and authentication schemes – OAuth 1.0, AuthSub, and ClientLogin have already been deprecated, so we recommend that you migrate applications to use OAuth 2.0 authorization instead.)
Video feeds
Video feeds return a collection of video entries. In turn, each video entry contains information about a specific video in the video feed's result set. The YouTube Data API allows you to retrieve the following types of video feeds:
Videos 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:
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
Related videos feed
The related videos feed contains 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"/>
Related videos feeds contain a maximum of 100 videos.
Standard 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.
Using the time parameter with standard feeds
All standard 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&v=2
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.
Playlist feed
A playlist feed contains information about a collection of up to 200 videos that can be viewed sequentially. A user can view and edit his list of playlists on his account page, and a user's playlists are also publicly visible to other YouTube users. In addition, users can modify an individual playlist by adding or removing videos from the playlist.
A playlist can be public or private. The API allows you to retrieve public playlists with or without user authorization. However, you can only retrieve a private playlist for a user who is properly authenticated and authorized to view the playlist.
Before retrieving a playlist feed, you will probably first retrieve a user's playlists feed, which contains a list of the playlists created by that user. Within the user's playlists feed, each entry describes a single playlist. (On the other hand, a playlist feed describes the individual videos that comprise a single playlist.) Each entry in a user's playlists feed contains a <content> tag that identifies the URL that allows you to retrieve the feed for that playlist.
<content type='application/atom+xml;type=feed' href='http://gdata.youtube.com/feeds/api/playlists/PLAYLIST_ID?v=2'/>
Note: The actual URL will contain an ID that uniquely identifies the playlist in place of the term PLAYLIST_ID.
User's playlists feed
A user's playlists feed contains a list of the playlists created by that user. If you are requesting the playlists feed for the currently authenticated user, the feed will contain both public and private playlists. However, if you send an unauthorized request or request playlists created by someone other than the currently authenticated user, the feed will only contain public playlists.
In a playlists feed, each entry contains information about a single playlist, including the playlist title, description and author. The <gd:feedLink> tag in the entry identifies the URL that allows you to retrieve the playlist feed, which specifies information about the videos in the playlist.
-
To request a feed of the currently logged-in user's playlists, send a GET request to the following URL. Note: For this request, you must provide an authorization token, which enables YouTube to verify that the user authorized access to the resource.
https://gdata.youtube.com/feeds/api/users/default/playlists?v=2
-
To request a feed of another user's playlists, send a GET request to the following URL. This request does not require user authorization.
https://gdata.youtube.com/feeds/api/users/userId/playlists?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.
User's subscriptions feed
A user's subscriptions feed contains a list of the user actions and channels to which the user has subscribed.
-
To request a feed of the currently logged-in user's subscriptions, send a GET request to the following URL. Note: For this request, you must provide an authorization token, which enables YouTube to verify that the user authorized access to the resource.
https://gdata.youtube.com/feeds/api/users/default/subscriptions?v=2
-
To request a feed of another user's subscriptions, send a GET request to the following URL. Note that this request does not require user authorization.
https://gdata.youtube.com/feeds/api/users/userId/subscriptions?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.
In a subscriptions feed, each entry contains information about a single subscription. Each entry contains the following key tags:
-
The <content> tag in the entry identifies the URL that allows you to retrieve videos for the subscription.
-
For one of the
<category>
tags in the entry, thescheme
attribute value will behttp://gdata.youtube.com/schemas/2007/subscriptiontypes.cat
. That tag'sterm
attribute indicates whether the entry describes a subscription to a channel (term="channel"
) or a user's YouTube activity (term="user"
) – activities include uploading a video, rating a video, or commenting on a video. -
The
<yt:channelId>
tag identifies the channel associated with the subscription. -
The
<yt:username>
tag identifies the display name for the user whose activities are being subscribed to or the channel that is being subscribed to.
Video comments feed
Each video entry contains a <gd:comments> tag, which encapsulates the URL to which you will send API requests to retrieve or append to the list of comments for the video. The sample XML below shows how this URL appears in a video feed:
<feed>
<entry>
...
<media:group>
...
</media:group>
<gd:comments>
<gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/VIDEO_ID/comments'/>
</gd:comments>
</entry>
</feed>
Each entry in the comments feed contains information about a single comment. Each comment has an author, a title, content, and an in-reply-to link.
User profile entry
A user profile contains information that the user lists on his YouTube profile page.
-
To request the currently logged-in user's profile, 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?v=2
-
To request another user's profile, send an HTTP GET request to the following URL. This request does not require user authorization.
http://gdata.youtube.com/feeds/api/users/userId?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.
Note: Whereas many API responses contain information about the response feed and a list of entries, the request to retrieve a profile only contains a single entry. As such, the root tag in the API response for this request is <entry>.
User's contacts feed
To request the currently logged-in user's contact list, send a GET request to the following URL. Your request must provide an authorization token, which enables YouTube to verify that the user authorized access to the resource.
https://gdata.youtube.com/feeds/api/users/default/contacts?v=2
If you try to retrieve contacts for the default user without providing proper authorization, the API returns a 401 (User authentication required) HTTP response.
Note: The API does not allow one user to retrieve another user's contacts.
Navigating between feeds
Every feed and entry contains <link rel="relationshipID">, <content> and <gd:feedLink rel="relationshipID"> elements that specify links to related feeds or entries. These tags identify URLs that enable you to implement API functionality without hardcoding URLs into your application.
-
A <link> tag identifies a relationship between related, but not nested, feeds. For example, the following
<link>
element, which might appear in a video entry, provides a link to a feed that contains related videos for that entry.<link rel="http://gdata.youtube.com/schemas/2007#video.related" type="application/atom+xml" href="http://gdata.youtube.com/feeds/api/videos/UwOA8H5Vaak/related?v=2"/>
-
A <content> tag specifies the feed URL that corresponds to an entry in a subscriptions feed or a playlists feed – i.e. the tag specifies the feed URL for an individual subscription or playlist. For example, the following
<content>
element might appear in an entry in a subscriptions feed. This tag identifies the URL from which you would retrieve a feed of videos for the subscription.<content type='application/atom+xml' src='http://gdata.youtube.com/feeds/api/users/nbc/uploads?v=2'/>
-
A <gd:feedLink> tag identifies a feed that might otherwise be nested within the original response except for the fact that actually nesting the feeds would make the feed too large. For example, the following
<gd:feedLink>
element might appear in a user profile entry. This tag identifies the URL from which you would retrieve a feed of that user's contacts.<gd:feedLink rel="http://gdata.youtube.com/schemas/2007#user.contacts" href="http://gdata.youtube.com/feeds/api/users/liz/contacts?v=2"/>
The use cases in the Developer's Guide attempt to explain how to navigate between the different feeds.
Paging through results
API responses use <link> tags to identify pagination links for the previous and/or next page of entries in a feed. To avoid pagination problems, we recommend that you use these links to enable users to link to different pages of API results.
- If a feed contains a previous page of results, the API response will contain a <link> tag with a
rel
attribute value ofprevious
. - If a feed contains a next page of results, the API response will contain a <link> tag with a
rel
attribute value ofnext
.
The API uses the start-index and max-results request parameters to determine which results to include in an API response. In addition, API responses use the <openSearch:totalResults> tag to approximate the total number of entries in a feed, and the <openSearch:startIndex> and <openSearch:itemsPerPage> tags to specify the particular entries in the API response. For example, the following tags indicate that an API response contains the 26th to 50th entries of a total result set of 107 items. (The response starts with item 26 and contains 25 items.)
<openSearch:startIndex>26</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <openSearch:totalResults>107</openSearch:totalResults>
In this example, the response would also contain two <link> tags, one for the previous page of 25 results (entries 1-25) and another for the next page of 25 results (entries 51-75). Each <link> tag specifies a feed URL with the correct values for the start-index and max-results request parameters.
<link rel='previous' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos?start-index=1&max-results=25...'/> <link rel='next' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos?start-index=51&max-results=25...'/>
Limits on result counts and accessible results
The <openSearch:totalResults>
tag has a maximum value of 1,000,000. As such, if the tag value is 1000000
, you can be sure that there are not exactly one million results but rather that there are so many matches that we just stopped counting.
For any given query, you will not be able to retrieve more than 1,000 results even if there are more than that. The API will return an error if you try to retrieve greater than 1,000 results. Thus, the API will return an error if you set the start-index
query parameter to a value of 1001
or greater. It will also return an error if the sum of the start-index
and max-results
parameters is greater than 1,001.
For example, if you set the start-index
parameter value to 1000
, then you must set the max-results
parameter value to 1
, and if you set the start-index
parameter value to 980
, then you must set the max-results
parameter value to 21
or less.
Pagination and total result counts
Note that the total count expressed in the <openSearch:totalResults>
tag generally presents an approximation of the number of total results rather than an exact count of results. In many cases, the number will not be accurate, and your application should not depend on its accuracy.
You may see the total number of results change as you navigate through the result set. In your user interface, you can allow for this possible discrepancy by displaying links to the previous and next pages of results rather than displaying links to numbered results pages that may not exist.
For example, suppose your website displays 25 results per page, and an API response indicates that a query has 76 results. In this case, there may, in fact, be 76 results, which would display on your site as three pages showing 25 results and one page showing one result. However, if the query actually has only 73 results, which would display on three pages instead of four, you do not want your application to display a link to a page that shows no results.
As such, rather than displaying links to numbered results pages, we recommend that your application check the API response for the presence of links to the next and previous pages of results and then display pagination links accordingly. This approach will ensure that your application only displays links to pages that will definitely display results.
HTTP response codes for YouTube Data API requests
This section explains the HTTP response codes that YouTube returns for different types of API requests.
Retrieving feeds
-
A 200 response code indicates that YouTube successfully handled an HTTP GET request to retrieve a feed.
-
A 400 response code identifies a bad request. For example, you will receive a 400 response code if you submit a request to the wrong URL or include an unsupported or nonexistent parameter in your request. The API response content will explain the reason why the API returned a 400 response code.
Uploading a video
-
Browser-based uploading
-
200 - The API returns a 200 response code in two cases:
-
You successfully upload a video's metadata. The Uploading video metadata section of the developer's guide explains this process in more detail.
-
Your request to upload the video file does not actually specify the file being uploaded. In this case, the API directs you to a page that says "No file found in upload request." To avoid this error case, your application should require the user to select a file before allowing the user to submit the form to upload the video as described in the instructions for uploading a video file for browser-based uploads.
-
-
301 - When the user uploads his actual video file directly to YouTube via the form on your site, YouTube will send a 301 redirect to the user's browser, causing the browser to request and load the URL that you had specified with the nexturl parameter in your upload form. (Learn more about the upload form.) YouTube will append the following variables to that URL, and you need to extract those variables to provide the appropriate user experience:
- id - This request parameter identifies the video ID of a newly created video.
- status - This request parameter indicates whether the user successfully uploaded the video. The value will be 200 if the video was uploaded successfully and a 4xx or 5xx (e.g. 400, 403, 503, etc.) if the upload was unsuccessful.
- code - This request parameter provides additional detail about why an upload failed. Possible values for this parameter include "INVALID_TOKEN", "MISSING_TOKEN", "DUPLICATE" and "TOKEN_EXPIRED".
-
-
Direct uploading
-
201 - The API returns a 201 response code if your video uploads successfully.
-
400 (Bad request) - A 400 response code indicates that a request was poorly formed or contained invalid data. For example, the API would return a 400 response code if your request contained poorly formed XML or if you tried to submit keywords containing invalid characters.
-
Adding information via HTTP POST
The API returns the following response codes for requests to add resources such as ratings, comments, complaints, favorite videos, playlists, playlist entries, subscriptions and contacts.
-
201 (Created) - A 201 response code indicates that an HTTP POST request to add a rating, comment, complaint, subscription, playlist or contact was successfully handled.
-
400 (Bad request) - A 400 response code indicates that a request was poorly formed or contained invalid data. For example, the API would return a 400 response code if your request contained poorly formed XML or if you tried to submit a rating of "16" for a video since the rating must be between 1 and 5. The API response content will explain the reason why the API returned a 400 response code.
Updating information via HTTP PUT
The API returns the following response codes for requests to update resources such as videos, playlists, playlist entries and contacts:
-
200 (OK) - A 200 response code indicates that YouTube successfully handled an HTTP PUT request to update a resource.
-
400 (Bad request) - A 400 response code indicates that a request was poorly formed or contained invalid data. The API response content will explain the reason why the API returned a 400 response code.
Deleting resources via HTTP DELETE
The API returns the following response codes for requests to delete resources such as videos, favorite videos, playlists, playlist entries, subscriptions and contacts.
-
200 (OK) - A 200 response code indicates that YouTube successfully handled an HTTP DELETE request to delete a resource.
-
401 (Not authorized) - A 401 response code indicates that a request did not contain an Authorization header, that the format of the Authorization header was invalid, or that the authorization token supplied in the header was invalid.
-
403 (Forbidden) - A 403 response code indicates that you have submitted a request that is not properly authenticated for the requested operation.
-
404 (Not found) - A 404 response code indicates that you have tried to modify a resource that does not exist. For example, you would receive a 404 response code if you tried to delete a subscription but you specified the wrong URL for the subscription.
Additional response codes for unsuccessful requests
The API may also return the following response codes:
-
401 (Not authorized) - A 401 response code indicates that a request did not contain an Authorization header, that the format of the Authorization header was invalid, or that the authorization token supplied in the header was invalid.
-
403 (Forbidden) - A 403 response code indicates that you have submitted a request that is not properly authenticated for the requested operation.
-
500 (Internal error) - A 500 response code indicates that YouTube experienced an error handling a request. You could retry the request at a later time.
-
501 (Not implemented) - A 501 response code indicates that you have tried to execute an unsupported operation, such as retrieving a list of ratings or updating a complaint.
-
503 (Service unavailable) - A 503 response code indicates that the YouTube Data API service can not be reached. You could retry your request at a later time.
Searching for videos
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
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
Query parameter definitions
Standard Google Data API 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:
|
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 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:
true or false . |
||||||||
category |
The category parameter has two uses:
|
||||||||
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:
<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.
|
||||||||
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.
|
||||||||
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 ) 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:
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:
|
||||||||
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.
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:
<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:
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:
|
||||||||
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:
|
||||||||
paid-content |
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.
paid_content parameter for movie chartsFor 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:
<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. |
||||||||
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.
|
||||||||
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.
|
||||||||
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:
|
||||||||
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 .
|
||||||||
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. |
Category search in video feeds
YouTube videos can be categorized in the following ways:
-
Each video can be associated with one predefined YouTube category, such as Comedy, Music, News or Sports. A video's category is identified by the <media:category> tag and by the <category> tag for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/categories.cat.
-
Each video can be associated with an arbitrary number of keywords, which are also known as tags. A video's tags are identified using the <media:keywords> tag in API requests and responses. Keyword tags are also identified by <category> tags for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/keywords.cat.
-
Each video can also be associated with an arbitrary number of developer tags. You can search for videos using developer tags. However, developer tags are not displayed on YouTube's website and you should not display them in your application. A video's developer tags are identified in <media:category> and <category> tags for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/developertags.cat.
Please see the developer's guide for more information about assigning developer tags.
The YouTube Data API supports two different methods for retrieving videos that are in a particular category or that are labeled with a specific keyword or developer tag.
-
Use the following URL to retrieve videos that are in a specific category or that are labeled with a specific keyword or developer tag. The hyphen (-) in the URL is a standard Google Data API notation that indicates that the rest of the URL consists of a series of one or more tags.
http://gdata.youtube.com/feeds/api/videos/-/category_or_tag?v=2
The following example shows the URL that you would use to request videos in the "Comedy" category:
http://gdata.youtube.com/feeds/api/videos/-/Comedy?v=2
-
Specify the category, keyword or developer tags using the category parameter in the request URL. The following example shows the URL that you would use to request videos in the "Comedy" category:
http://gdata.youtube.com/feeds/api/videos?category=Comedy&v=2
The following guidelines provide more detail about requesting videos associated with particular categories or tags:
-
If your request specifies a category and one or more keywords or if your request does not specify a category but does specify multiple keywords, separate each individual category and keyword name with a forward slash. (If you are using the category parameter, separate the different category and tag names with a comma. (The comma must be URL-encoded in your request.) For example, you could use either of the following URLs to request videos related to the keywords "bass" and "fishing":
URL notation: https://gdata.youtube.com/feeds/api/videos/-/bass/fishing?v=2 category parameter: https://gdata.youtube.com/feeds/api/videos?category=bass%2Cfishing&v=2
-
Your request can use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several keywords or categories. For example, if you wanted to display videos related to "bass" and "music", the most effective search might be for videos associated with the keyword "bass" but not associated with the keywords "fish" or "fishing" as shown in the example below. (Searching for videos associated with the "Music" category and the keyword "bass" might exclude instructional videos about how to play bass.)
URL notation: https://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing?v=2 category parameter: https://gdata.youtube.com/feeds/api/videos?
category=bass%2C%2Dfish%2Dfishing&v=2The following example shows how to search for videos that are tagged with the keywords "Jesse" and "Ventura" and that are in either the "News" or "Sports" categories. The category names are separated by the value "%7C", which represents a URL-encoded pipe (|) character specifying that the video must be associated with one of the two categories:
URL notation: https://gdata.youtube.com/feeds/api/videos/-/jesse/ventura/News%7CSports?v=2 category parameter: https://gdata.youtube.com/feeds/api/videos?category=jesse%2Cventura%2CNews%7CSports&v=2
-
Capitalize the names of categories and lowercase the names of keywords. For example, the following query identifies videos associated with the keyword "comedy" that are not in the "Comedy" category:
URL notation: https://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy?v=2 category parameter: https://gdata.youtube.com/feeds/api/videos?category=comedy%2C%2DComedy&v=2
-
If you are generating category or keyword searches automatically based on the information in an API response, specify the schema as part of the category name to clearly differentiate YouTube categories from keyword tags or developer tags. The following URLs demonstrate how to specify the schema in the category name. (Note that each URL should actually appear on one line but has been split into multiple lines for printing purposes.)
Categories: URL notation: https://gdata.youtube.com/feeds/api/videos/-/ %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fcategories.cat%7DNews?v=2 category parameter: https://gdata.youtube.com/feeds/api/videos?category= %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fcategories.cat%7DNews&v=2 Keywords: URL notation: https://gdata.youtube.com/feeds/api/videos/-/ %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fkeywords.cat%7Ddog?v=2 category parameter: https://gdata.youtube.com/feeds/api/videos?category= %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fkeywords.cat%7Ddog&v=2 Developer tags: URL notation: https://gdata.youtube.com/feeds/api/videos/-/ %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fdevelopertags.cat%7Dexample.com?v=2 category parameter: https://gdata.youtube.com/feeds/api/videos?category= %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007 %2Fdevelopertags.cat%7Dexample.com&v=2
-
Always specify the schema, as explained in the previous item, if you are requesting videos associated with a particular developer tag.
Spelling suggestions in API responses
API responses may contain suggested alternate spellings for the search query term specified in your request. For example, a user who entered the search term flowrs – note the missing "e" in the word – might actually be looking for videos matching the term flowers. By displaying a link to search results matching the spelling suggestion, you can enable users (and particularly users who are not the best spellers) to more easily locate relevant videos.
If YouTube identifies a suggested alternate spelling for a query term, the corresponding API response will contain a <link> tag for which the rel attribute value is http://schemas.google.com/g/2006#spellcorrection. The value of that tag's title attribute will be the suggested alternate spelling for the search query term. For example, the tag below shows a suggested alternate spelling for the term flowrs.
<link rel='http://schemas.google.com/g/2006#spellcorrection' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos?q=flowers&oi=spell&spell=1&v=2' title='flowers'/>
XML element definitions
The YouTube Data API uses tags from multiple XML schemas. The following table identifies the different schemas that the API uses, the namespace prefix associated with each schema, and the namespace URL for each schema.
Schema | Namespace Prefix | Schema URL |
---|---|---|
Atom Syndication Format | [None] - this is the default namespace | http://www.w3.org/2005/Atom |
Open Search Schema | openSearch | http://a9.com/-/spec/opensearch/1.1/ |
Media RSS | media | http://search.yahoo.com/mrss/ |
YouTube XML Schema | yt | http://gdata.youtube.com/schemas/2007 |
Google Data Schema | gd | http://schemas.google.com/g/2005 |
GeoRSS | georss | http://www.georss.org/georss |
Geography Markup Language | gml | http://www.opengis.net/gml |
Atom Publishing Protocol | app | http://www.w3.org/2007/app |
Google Data API Batch Processing | batch | http://schemas.google.com/gdata/batch |
The following lists define the XML tags from each of these schemas that appear in YouTube Data API requests and responses. Tags are presented in alphabetical order in each list.
- Atom elements reference
- OpenSearch elements reference
- YouTube elements reference
- Media RSS elements reference
- GData elements reference
- GeoRSS elements reference
- GML elements reference
- Atom Publishing Protocol element reference
- Browser-based upload API response elements reference
- Batch processing element reference
- Error response element reference
Certain symbols may be displayed next to some child tags in the definitions below. These symbols, and their meanings, are:
* = zero or more instances of the child tag
+ = one or more instances of the child tag
Atom elements reference
author
The <author> tag usually contains information about the YouTube user who owns a piece of video content, a subscription, a list of favorite videos, a contact or other entity. However, the <author> tag has a different meaning in the following feeds:
- In a favorite videos feed entry, the <author> tag identifies the user who marked the video as a favorite.
- In a playlist feed entry, the <author> tag contains information about the YouTube user who created the playlist entry.
- In an inbox feed entry, the <author> contains information about the YouTube user who sent the inbox entry.
Example
<author>
Child of
Children
category
The <category> tag specifies the category to which the entry belongs.
When the <category> tag appears as a subtag of either <feed> or <entry>, the tag can identify the type of item described in each feed entry. The value of the scheme attribute is http://schemas.google.com/g/2005#kind and the value of the term attribute indicates whether feed entries describe videos, playlist links, subscriptions, contacts or another entity type.
When the <category> tag appears as a subtag of <entry> and the entry describes a video, the tag can also specify a particular keyword or category associated with that video. In this case, the scheme attribute indicates whether the term attribute value refers to a keyword or a category. Note that a video entry will only include keywords if the API request was authorized by the video's owner. If the API request was not authorized or was authorized by another user,
<category>
tags containing keywords will not be included in the feed.
The <category> tag is required in a request to add a subscription, in which case it identifies the type of subscription being created.
Attributes
Name | Format | Description |
---|---|---|
scheme | Text (URI) | The scheme attribute specifies a URI that identifies the categorization scheme associated with the label.
|
term | Text | The term attribute identifies the type of entity contained in a feed entry or a category or keyword associated with a video.
|
label | Text | The label attribute specifies the entity-escaped name of the YouTube category to which the video belongs or the YouTube EDU category associated with a lecture or course. This attribute is only included in <category> tags that refer to a category (and not a keyword or entity type). Please refer to the Category list for uploaded videos section for more information about YouTube video categories and the YouTube EDU section for more information about YouTube EDU categories. |
Example
<category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='channel'/>
Child of
content
The <content> tag is used in several different contexts:
In a request to add a comment, the <content> tag is required and contain the text of the comment.
- In a video entry or playlist entry, the <content> tag contains a description of a video or playlist. In this case, the tag may contain the same description as the <media:description> tag.
In a live video entry, the <content> tag contains either a feed URL for the live video entry associated with an event or it encapsulates the XML for the live video entry. In time, the <content> tag could contain a feed URL for a playlist entry or encapsulate the XML for a playlist entry (rather than a live video entry).
- If your API request set the
inline
parameter tofalse
or did not include theinline
parameter, then the <content> tag for an event entry will specify the feed URL for the live video entry associated with the event. In this case, the tag'stype
andsrc
attributes will both appear in the response. - If your API request set the
inline
parameter totrue
, then the <content> tag for an event entry will encapsulate an<entry>
tag describing the live video entry associated with the event. In this case, the tag'stype
attribute will be set, and itssrc
attribute will not be set.
- If your API request set the
Attributes
Name | Format | Description |
---|---|---|
src | String | The src attribute specifies the feed URL that you would use to retrieve the live video entry associated with an event. This attribute will only be present in an API response if you did not set the inline parameter value to true in the API request. |
type | String | The type attribute specifies the format of the content that is either encapsulated within the <content> tag or accessible at the URL specified in the src attribute value. |
Example
<content type="text">Video comments are cool.</content>
Child of
Children
entry
The <entry> tag encapsulates information about a video, playlist, subscription, contact or other entity. The <entry> tag is the root tag in all YouTube Data API requests to add (POST) or update (PUT) data.
Example
<entry>
Child of
Children
The lists below identify possible subtags of the <entry> tag for different retrieve (GET), create (POST) and update (PUT) API operations. For example, when you retrieve a playlist feed, each entry contains many different fields. However, when you create or update a playlist entry, you only need to provide the title, description and playlist position for the entry.
GET operations
Video, playlist, lecture, or course entries: id, published?, updated, category*, title, content?, link*, author?, summary? (this tag only appears in a playlist entry), media:group?, yt:position? (this tag only appears in a playlist entry), yt:statistics?, gd:comments?, gd:rating?, yt:rating?, yt:location?, yt:recorded?, yt:accessControl+, yt:availability?, yt:episode?, yt:favoriteId?, yt:firstReleased?, yt:material*, georss:where?, app:control?
Comment feed entries: id, published?, updated, category*, title, content?, link*, author?, yt:spam?
Playlists feed entries: id, published?, updated, category*, title, content?, link*, author?, summary?, playlistId, yt:countHint
Subscriptions feed entries: id, published?, updated, category*, title, content?, link*, author?, yt:channelId, yt:countHint, media:thumbnail?, yt:unreadCount?, yt:username
Profile entry for a user with a YouTube account: id, published?, updated, category*, title, content?, link*, author?, yt:aboutMe?, yt:age?, yt:books?, yt:company?, firstName?, yt:gender?, yt:hobbies?, yt:hometown?, lastName?, yt:location?, yt:maxUploadDuration?, yt:movies?, yt:music?, yt:occupation?, yt:school?, yt:username?, yt:statistics?, media:thumbnail?, gd:feedLink*
Profile entry for a user with an unlinked Google Account: id, published, updated, category, title, link*, author?, yt:age, yt:incomplete, yt:location?, yt:statistics
Contacts feed entries: id, published?, updated, category*, title, link*, author?, yt:username, yt:status
Inbox (messages) feed entries: id, published?, category*, title, content?, link*, author?, media:group?, yt:statistics?, gd:rating?, gd:comments?, summary
Activity feed entries: id, updated?, category*, title, link*, author?, yt:groupId?, yt:videoid
Channel branding settings entry: id, published, updated, app:edited, category, link*, yt:option*
Channel entries: id, updated, category, title, summary, link*, author, yt:channelId, yt:channelStatistics?, gd:feedLink, media:thumbnail?
Show feed entries: id, published, updated, category, title, summary, content, link*, author, yt:countHint, media:group, yt:schedule*, gd:feedLink
POST and PUT operations
Adding favorite videos: id
Adding and updating playlists: title, summary?, yt:private?
Adding and updating playlist entries: title, summary?, yt:position?
Adding subscriptions: category, yt:username
Adding and updating contacts: category, yt:username
Adding ratings: gd:rating
Adding complaints: summary
If the <entry> tag appears in a batch processing request, then it might also include the <batch:operation> <batch:id> tags.
If the <entry> tag appears in a response to a batch processing request, then it will also include the <batch:operation> and <batch:status> tags and it may also include the <batch:id> and <batch:interrupted> tags.
feed
The <feed> tag is the root tag for several types of YouTube Data API feeds, including video feeds, subscription feeds, playlist feeds, favorite video feeds and contact feeds. A feed contains a series of <entry> elements, each of which contains information about a single video, playlist, subscription or other entity.
Example
<feed xmlns='http://www.w3.org/2005/Atom' xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/' xmlns:gml='http://www.opengis.net/gml' xmlns:georss='http://www.georss.org/georss xmlns:media='http://search.yahoo.com/mrss/' xmlns:batch='http://schemas.google.com/gdata/batch' xmlns:yt='http://gdata.youtube.com/schemas/2007' xmlns:gd='http://schemas.google.com/g/2005'>
Children
id, updated, category*, title, subtitle?, logo?, link*, author?, generator?, openSearch:itemsPerPage?, openSearch:startIndex?, openSearch:totalResults?, media:group?, yt:material*, batch:operation?, entry*
generator
The <generator> tag identifies the software used to create the feed. This information might be used for debugging purposes.
Attributes
Name | Format | Description |
---|---|---|
version | Text | The version attribute specifies the version of the software application used to generate the feed. |
uri | Text (URI) | The uri attribute specifies a URI related to the feed-generating software. |
Example
<generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator>
Child of
id
The <id> tag specifies a URN that uniquely and permanently identifies a feed or feed entry.
Example
<id>tag:youtube,2008:video:24Ryj1ywosw</id>
Child of
link
The <link> tag contains an IRI reference that is relevant to a feed or a feed entry.
Attributes
Name | Format | Description |
---|---|---|
rel | Text | The rel attribute indicates how the URI specified in the href attribute is related to the current result set:
|
type | Text | The type attribute specifies the media type of the resource at the associated URL. The links in a YouTube Data API response typically refer to either an HTML page or another API response (Atom feed). As such, the most common values for the type attribute are text/html and application/atom+xml. |
href | Text (URI) | The href attribute specifies a URI that identifies the resource identified in the <link> tag. |
yt:hasEntries | Boolean | The yt:hasEntries attribute indicates whether the feed identified in the <link> tag is an empty feed. The feed is empty if the yt:hasEntries attribute value is false. |
Example
<link rel='http://gdata.youtube.com/schemas/2007#video.related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/AlPqL7IUT6M/related'/>
Child of
logo
The <logo> tag specifies an image that provides visual identification for the feed. The logo in a YouTube Data API feed is the YouTube logo.
Example
<logo>http://www.gstatic.com/youtube/img/logo.png</logo>
Child of
name
The <name> tag contains the author's YouTube username.
Example
<name>GoogleDevelopers</name>
Child of
published
The <published> tag specifies the time that a feed entry was created. Times are specified in UTC.
Example
<published>2007-10-15T15:39:34.000-07:00</published>
Child of
subtitle
The <subtitle> tag contains a description of a playlist.
Example
<subtitle>My playlist description</subtitle>
Child of
summary
The <summary> tag contains either the description that a user entered for a playlist, a custom description that a user entered for a video in a playlist, or the text of a complaint.
Example
<summary>Dan is getting ready for the game.</summary>
Child of
title
The <title> tag provides a human-readable title for a feed or an entry in a feed. This tag is also required in a request to add a playlist, in which it specifies the title of the playlist to be added.
Example
<title>GoogleDeveloper's Subscriptions</title>
Child of
updated
The <updated> tag specifies the time that a feed or feed entry was last updated.
Example
<updated>2007-10-15T15:39:34.000-07:00</updated>
Child of
uri
The <uri> tag contains a URL related to the author.
Example
<uri>http://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
Child of
OpenSearch elements reference
openSearch:itemsPerPage
The <openSearch:itemsPerPage> tag indicates how many entries are in an API response.
Example
<openSearch:itemsPerPage>25</openSearch:itemsPerPage>
Child of
openSearch:startIndex
The <openSearch:startIndex> tag identifies the one-based index of the first item returned in the feed.
Example
<openSearch:startIndex>1</openSearch:startIndex>
Child of
openSearch:totalResults
The <openSearch:totalResults> tag identifies the number of items in the result set for the feed. Please note that the tag value is an approximation and may not represent an exact value. In addition, the maximum value for this tag is 1,000,000. You should not use this value to create pagination links. Use the <link rel="next"> and <link rel="prev"> tags to determine whether to show pagination links:
If the feed contains a <link> tag for which the rel attribute value is next, then there is another page of results. Otherwise, the current page is the last page in the result set. Similarly, if the feed contains a <link> tag for which the rel attribute value is prev, then there is a previous page of results. Otherwise, the current page is the first page in the result set.
Example
<openSearch:totalResults>36</openSearch:totalResults>
Child of
YouTube elements reference
yt:aboutMe
The <yt:aboutMe> tag contains whatever content the user entered in the "About Me" field of the user's YouTube profile. This tag appears in a user profile entry.
Example
<yt:aboutMe>I am very funny.</yt:aboutMe>
Child of
yt:accessControl
The <yt:accessControl> tag indicates whether users are allowed to rate a video, add comments about a video, rate comments about the video, or embed the video on third-party websites. Another setting indicates whether YouTube can show the video on YouTube properties other than the YouTube.com website.
These access control settings are set by the video uploader. However, if a user has uploaded content, such as a music video, that is owned by another user, then the actual content owner may override the access control settings that the uploader provided. Please note the following exceptions:
- If a video entry contains a
<yt:state>
tag that has itsname
andreasonCode
attributes set torestricted
andlimitedSyndication
, respectively, then the video's actual owner disallows syndication of the video. That setting will prevent playback of the video on other platforms regardless of the uploader's setting for thesyndicate
access control.
Attributes
Name | Format | Description |
---|---|---|
action | Text | The action attribute identifies the type of access control being set. The list below identifies valid values for this attribute:
|
permission | Text | The permission attribute indicates whether a particular action is allowed. The attribute values allowed and denied are valid for all actions. In addition, the attribute value moderated is valid for the comment action. This permission indicates that people can add comments, but that the video owner will have the ability to review and approve those comments before they are visible to other users. |
Example
<yt:accessControl action='comment' permission='allowed'/>
Child of
yt:age
The <yt:age> tag specifies the user's age, which is calculated based on the birthdate provided for the user's YouTube profile. This tag appears in a user profile entry.
Example
<yt:age>33</yt:age>
Child of
yt:archived
The <yt:archived> tag indicates whether you want the live video stream from your event to be recorded so that it can be viewed after the event (like any other video). The tag's default value is false
. Set the value to true
to have the event's video recorded for future viewing.
Example
<yt:archived>true</yt:archived>
Child of
yt:aspectratio
The <yt:aspectratio> tag identifies the aspect ratio of a video. The only valid value for this tag is widescreen, which indicates that the video has an aspect ratio of, or very close to, 16:9. YouTube's standard video player has a 16:9 aspect ratio, and the player will frame a video with vertical bars (pillarboxing) or horizontal bars (letterboxing) when playing a non-widescreen video.
Note: At the time of this documentation change in June 2009, YouTube had recently begun to generate this tag, as appropriate, for newly uploaded videos. However, feed entries for older videos in the YouTube library may not include this tag even if those videos are widescreen. As such, the presence of this tag in a feed entry indicates that the video is a widescreen video, but the absence of the tag does not decisively indicate that the video is not a widescreen video.
Example
<yt:aspectratio>widescreen</yt:aspectratio>
Child of
yt:audioTracks
The <yt:audioTracks> tag identifies the languages in which audio is available for a movie or show. The tag value is a list of ISO 639-1 two-letter language codes separated by a comma and a space (", ").
Example
<yt:audioTracks>en</yt:audioTracks>
Child of
yt:availability
The <yt:availability> tag specifies the date range when a movie will be available on YouTube.
Attributes
Name | Format | Description |
---|---|---|
start | DateTime | The start attribute specifies the date and time when a movie or show episode was first available on YouTube. |
end | DateTime | The end attribute specifies the date and time after which a movie or show episode will no longer be available on YouTube. If this attribute is not present, the video's owner has not specified an end date for the video's availability range. |
Example
<yt:availability start=2009-06-04T15:00:00.000Z' end='2019-06-15T23:59:00.000Z'/>
Child of
yt:books
The <yt:books> tag identifies the user's favorite books as entered in the user's YouTube public profile. This tag appears in a user profile entry.
Example
<yt:books>Catch-22</yt:books>
Child of
yt:captionTracks
The <yt:captionTracks> tag identifies the languages in which captions are available for a movie or show. The tag value is a list of ISO 639-1 two-letter language codes separated by a comma and a space (", ").
Example
<yt:captionTracks>de, en, fr</yt:captionTracks>
Child of
yt:cdn
The <yt:cdn> tag contains CDN information for the live streaming event. It contains one or more <media:content>
tags, each of which identifies a format in which the event's video will be streamed.
Attributes
Name | Format | Description |
---|---|---|
name | String. Valid values are primary and backup . |
The name attribute indicates whether the <yt:cdn> tag contains the primary or backup CDN information. You must stream video to a primary CDN and have the option of simultaneously streaming the same content to a backup CDN. |
Example
<yt:cdn name="primary">
Child of
Children
yt:channelId
The <yt:channelId> tag contains a value that uniquely identifies a YouTube channel.
Example
<yt:channelId>UCoUrIeCQbjRzAObg1lSS-uw</yt:channelId>
Child of
yt:channelStatistics
The <yt:channelStatistics> tag provides statistics about a YouTube channel, and it only appears in channel entries.
Attributes
Name | Format | Description |
---|---|---|
commentCount | Integer | The commentCount attribute specifies the number of comments that YouTube users have submitted on the channel page. |
subscriberCount | Integer | The subscriberCount attribute specifies the number of YouTube users who have subscribed to the channel. |
totalUploadViewCount | Integer | The totalUploadViewCount attribute specifies the total number of views for all of a channel's videos. |
videoCount | Integer | The videoCount attribute specifies the number of videos uploaded to the channel. |
viewCount | Integer | The viewCount attribute specifies the number of times that the channel's channel page has been viewed. |
Example
<yt:channelStatistics commentCount='34' totalUploadViewCount='8623741' videoCount='71' viewCount='716912'/>
Child of
yt:company
The <yt:company> tag identifies the company that the user works for as entered by the user in the user's public YouTube profile. This tag appears in a user profile entry.
Example
<yt:company>Google</yt:company>
Child of
yt:contentType
The <yt:contentType> tag identifies the type of resource being recommended in a suggestions feed. At this time, the only valid value for this tag is channel
.
Example
<yt:contentType>channel</yt:contentType>
Child of
yt:countHint
The <yt:countHint> tag specifies the number of entries in a playlist feed. The <yt:countHint> tag appears in the entries in a playlists feed, where each entry contains information about a single playlist.
Example
<yt:countHint>9</yt:countHint>
Child of
yt:derived
The <yt:derived> tag identifies a caption track that was generated using automatic speech recognition (ASR). For caption track entries that were generated using ASR, this tag will have a value of speechRecognition
.
Example
<yt:derived>speechRecognition</yt:derived>
Child of
yt:duration
The <yt:duration> tag specifies the duration, in seconds, of either a video or of all of the videos in a playlist.
Attributes
Name | Format | Description |
---|---|---|
seconds | Integer | The seconds attribute indicates the duration, in seconds, of a video or of all of the videos in a playlist. |
Example
<yt:duration seconds='344'/>
Child of
yt:episode
The <yt:episode> tag specifies the episode number associated with an episode of a show. This tag will only be included in a video entry if the video is an episode linked to a show that is listed in YouTube's Shows category.
Attributes
Name | Format | Description |
---|---|---|
number | Text | The number attribute specifies the episode number. The value is a string since some episode numbers may be values like 12a (in the case of a multi-part episode) or have other non-numeric components. |
Example
<yt:episode number='12'/>
Child of
yt:favoriteId
The <yt:favoriteId> tag specifies a value that YouTube uses to uniquely identify a favorite video. The ID refers to both the video and the user who marked the video as a favorite. As such, if two different users mark the same video as a favorite video, YouTube will assign a different ID to each favorite video instance.
Example
<yt:favoriteId>vjVQa1PpcFP9NzIof2dlerfluOcvDpkm8zDBp7uuzOo</yt:favoriteId>
Child of
yt:firstName
The <yt:firstName> tag specifies the user's first name. This tag appears in a user profile entry.
Example
<yt:firstName>John</yt:firstName>
Child of
yt:firstReleased
The <yt:firstReleased> tag specifies the original release date for a movie or television show episode.
Example
<yt:firstReleased>2009-06-04T00:00:00.000Z</yt:firstReleased>
Child of
yt:gender
The <yt:gender> tag specifies the user's gender as entered in the user's public YouTube profile. This tag appears in a user profile entry.
Example
<yt:gender>m</yt:gender>
Child of
yt:googlePlusUserId
The <yt:googlePlusUserId> tag indicates that a comment entry represents a comment submitted through the YouTube commenting system that is powered by Google+ and that was introduced in November 2013. If the tag is present in a comment entry, then you can parse the Google+ Activity ID for the comment thread from the entry's <id>
tag. You can use that ID to call the Google+ API's comments:list
method and retrieve up to 20 recent replies to that comment.
Example
yt:googlePlusUserId>11191035744455860991</yt:googlePlusUserId>
Child of
yt:groupId
The <yt:groupId> tag identifies user events in an activity feed that are associated with the same user and resource. For example, if a user rates a video and marks the same video as a favorite, the entries for those events would have the same <yt:groupId>
value in the user's activity feed. In your user interface, you can avoid repetition by grouping events with the same <yt:groupId>
value. The image below shows a user interface that combines two events associated with the same user and video:
Example
<yt:groupId>WnhFLWZvbzNoM0IzbWI0Y3VpQmNLQTMxMjcwMTQ5MTI0NTc</yt:groupId>
Child of
yt:hd
The <yt:hd> tag indicates, by its presence, that the video is available in at least one HD format that has a resolution of at least 720p. HD videos may be available in higher resolutions, like 1080p, as well.
Example
<yt:hd/>
Child of
yt:hobbies
The <yt:hobbies> tag identifies the user's hobbies as entered in the user's YouTube public profile. This tag appears in a user profile entry.
Example
<yt:hobbies>Testing YouTube APIs</yt:hobbies>
Child of
yt:hometown
The <yt:hometown> tag identifies the user's hometown as entered in the user's YouTube public profile. This tag appears in a user profile entry.
Example
<yt:hometown>Albany, GA</yt:hometown>
Child of
yt:incomplete
The <yt:incomplete> tag instructs YouTube to automatically generate certain metadata values if they are not otherwise specified when you upload a video. YouTube uses the following rules to generate metadata if the <yt:incomplete>
element is included in the metadata for the uploaded video:
- If the entry does not contain a
<media:title>
element, YouTube sets the video's filename as the video title. - If the entry does not contain a
<media:keywords>
element, YouTube sets the video's filename as the video's keyword tag. - If the entry does not contain a
<media:category>
element, YouTube sets the video's category to the category of the last video that the user uploaded. If no prior upload exists, YouTube sets the video's category toPeople
.
You can only include the
<yt:incomplete>
element in a video entry at the time that you upload the video. When you retrieve a video entry for a video uploaded with incomplete metadata, the entry will contain the <yt:incomplete>
element. If you choose to update the video, you must at least remove the <yt:incomplete>
element from the entry before submitting your update request.Note that videos uploaded with the
<yt:incomplete>
element will not be included in YouTube's search index, and therefore will not appear in search results, until their metadata has been updated. After the video's metadata is updated, and the <yt:incomplete>
element is removed from the metadata, then the video will be eligible for inclusion in YouTube's search index.
Example
<yt:incomplete/>
Child of
yt:lastName
The <yt:lastName> tag specifies the user's last name. This tag appears in a user profile entry.
Example
<yt:lastName>Smith</yt:lastName>
Child of
yt:location
In a video entry, the <yt:location> tag contains descriptive text about the location where the video was taken. In a user profile entry, the <yt:location> tag identifies the user's location as entered in the user's YouTube public profile.
Example
<yt:location>US</yt:location>
Child of
yt:material
The <yt:material> identifies additional or related material for a course or lecture. For example, it could identify lecture notes, sample exams, or supplemental reading.
Attributes
Name | Format | Description |
---|---|---|
description | Text | The description attribute contains a description of the material. |
name | Text | The name attribute specifies the name of the supplemental material. |
type | Text | The type attribute identifies the type of the supplemental material. |
url | Text | The url attribute specifies a URL where the material can be accessed. |
Example
<yt:material description="This file contains solutions for quiz 1 questions." name="Quiz 1 (solution)" type="exam" url="http://www.example.edu/courses/1234/exams/q1_sol.pdf"/>
Child of
yt:maxUploadDuration
The <yt:maxUploadDuration> tag identifies the duration limit for uploaded videos from a particular user account. Your application could use this data before attempting to encode and upload a video to ensure that the video did not exceed the maximum video duration allowed for the user's account.
If the tag is absent, then there is no limit on video duration from the account.
Attributes
Name | Format | Description |
---|---|---|
seconds | Integer | The seconds attribute specifies the duration limit, in seconds, for uploaded videos from a particular user's account. |
Example
<yt:maxUploadDuration seconds="930"/>
Child of
yt:movies
The <yt:movies> tag identifies the user's favorite movies as entered in the user's YouTube public profile. This tag appears in a user profile entry.
Example
<yt:movies>Aqua Teen Hungerforce</yt:movies>
Child of
yt:music
The <yt:music> tag identifies the user's favorite music as entered in the user's YouTube public profile. This tag appears in a user profile entry.
Example
<yt:music>Elliott Smith, the Kooks</yt:music>
Child of
yt:noembed
Deprecated on Feb. 18, 2010. Please use the <yt:accessControl> element to enable or disable embedding.
The <yt:noembed> tag specifies that a video may not be embedded on other websites. This tag may be included in a request to upload or update a video's metadata. By default, videos can be embedded on other sites unless they are private videos. If a request does not include either the <yt:noembed> tag or the <yt:private> tag, a video will be embeddable on other websites.
Example
<yt:noembed/>
Child of
yt:occupation
The <yt:occupation> tag identifies the user's occupation as entered in the user's public YouTube profile. This tag appears in a user profile entry.
Example
<yt:occupation>Technical writer</yt:occupation>
Child of
yt:option
The <yt:option> tag contains information about a channel branding setting. The tag's name attribute identifies the setting, and the tag's value specifies the value that the channel currently uses for that setting.
Attributes
Name | Format | Description |
---|---|---|
name | Text | The name attribute identifies the branding setting that the <yt:option> tag provides a value for. See the branding options documentation for a complete list of values. |
Example
<yt:option name='channel.featured_video_module.video_id.string'>3jNiR8pY7XI</yt:option>
Child of
yt:playlistId
The <yt:playlistId> tag identifies the value that YouTube uses to uniquely identify a playlist. This tag appears in a playlist feed entry.
Example
<yt:playlistId>C344114E1E41B2FA</yt:playlistId>
Child of
yt:position
The <yt:position> tag specifies the order in which a video appears in a playlist.
Example
<yt:position>4</yt:position>
Child of
yt:private
The <yt:private> tag indicates that a video is private, meaning that the video will not be publicly visible on YouTube's website. A private video can only be viewed by people personally selected by the video's owner. This tag may be included in a request to upload or update a video's metadata. The tag should not specify a value. The tag's presence indicates that the video is private. The tag's absence indicates that the video will be visible to all YouTube users. By default, videos are publicly visible on YouTube. The tag's absence indicates that the video will be visible to all YouTube users. (By default, videos are visible to all YouTube users, and you must include the <yt:private> tag in all requests to upload or update a video to indicate that the video is private.)
Example
<yt:private/>
Child of
yt:rating
The <yt:rating> tag specifies the rating that a user is assigning to a video (in a request to add a rating) or, in an API response, the total number of raters who liked and disliked a video.
Attributes
Name | Format | Description |
---|---|---|
numDislikes | Integer | The numDislikes attribute specifies the number of raters who indicated that they disliked a video. |
numLikes | Integer | The numLikes attribute specifies the number of raters who indicated that they liked a video. |
value | Text | The value attribute indicates whether a rater likes or dislikes a video. Valid values for this attribute are like and dislike . |
Example
In an API response:
<yt:rating numDislikes='28' numLikes='141'/>
In a request to add a rating:
<yt:rating value="like"/>
Child of
yt:recorded
The <yt:recorded> tag specifies the date that a video was recorded.
Example
<yt:recorded>2003-08-03</yt:recorded>
Child of
yt:relationship
The <yt:relationship> tag indicates whether the user is in a relationship according to the information in the user's public YouTube profile.
Example
<yt:relationship>taken</yt:relationship>
Child of
yt:schedule
The <yt:schedule> tag contains information about a show's broadcast schedule. A show entry may contain multiple <yt:schedule>
tags if the show runs at more than one time during the specified time period (type
).
Attributes
Name | Format | Description |
---|---|---|
broadcaster | Text | The broadcaster attribute identifies the network that broadcasts the show at the specified time. |
country | Text. The value is an ISO 3166 two-letter country code. | The country attribute identifies the country where the show is broadcast. |
dayOfWeek | Integer | The dayOfWeek attribute specifies the day of the week where the show is broadcast. This value is only included if the type attribute value is weekly . The value is an integer between 1 (Monday) and 7 (Sunday). |
hour | Integer | The hour attribute specifies the hour of the day when the show airs. The value will be an integer between 0 and 23 inclusive. |
minute | Integer | The minute attribute specifies the minute(s) of the time when the show airs. The value will be an integer between 0 and 59 inclusive. |
second | Integer | The second attribute specifies the second(s) of the time when the show airs. The value will be an integer between 0 and 59 inclusive. |
timezone | Text | The timezone attribute specifies the time zone associated with the broadcast schedule information. |
type | Text | The type attribute indicates how frequently the show airs. Possible values are daily , weekly , weekdays , and weekends . If the value is weekly , then the tag will also specify a value for the dayOfWeek attribute. |
Example
<yt:schedule broadcaster="ABC" country="US" dayOfWeek="1" hour="22" minute="0" second="0" timezone="EST" type="weekly"/>
Child of
yt:school
The <yt:school> tag identifies the school that the user attended according to the information in the user's public YouTube profile. This tag appears in a user profile entry.
Example
<yt:school>University of North Carolina</yt:school>
Child of
yt:season
The <yt:season> tag specifies the season number associated with a season of a show. This tag is included in season feed entries.
Attributes
Name | Format | Description |
---|
Example
<yt:season number='2'/>
Child of
yt:spam
The <yt:spam> tag indicates, by its presence, that a comment has been flagged as spam. The absence of this tag in a comment feed entry indicates that the corresponding comment has not been flagged as spam. This tag is only supported in API version 2.
Example
<yt:spam/>
Child of
yt:state
The <yt:state> tag contains information that describes the status of a video that cannot be played. Video entries that contain a <yt:state> tag are not playable. The name and reasonCode attributes and the tag value provide insight into the reason why the video is not playable.
Attributes
Name | Format | Description |
---|---|---|
name | Text | The name attribute identifies the status of an unpublished video. Valid values for this tag are processing, restricted, deleted, rejected and failed. |
reasonCode | Text | The reasonCode attribute provides information about a video's state. For example, the reasonCode could explain why a video upload request failed or how access to view a video is restricted. The <yt:state> tag will not include a reasonCode attribute if the value of the name attribute is processing. The following list identifies possible reasonCode values for restricted, rejected or failed uploads:
|
helpUrl | Text | The helpUrl parameter contains a link to a YouTube Help Center page that may help the developer or the video owner to find additional information about the video's state. |
Example
<yt:state name="rejected" reasonCode="tooLong" helpUrl="http://www.youtube.com/t/community_guidelines">Video is too long</yt:state>
Child of
yt:statistics
The <yt:statistics> tag provides statistics about a video or a user. The <yt:statistics> tag is not provided in a video entry if the value of the viewCount attribute is 0. This tag appears in video, playlist and user profile entries.
Attributes
Name | Format | Description |
---|---|---|
viewCount | Integer | The viewCount attribute appears in statistics for videos and channels.
|
videoWatchCount | Integer | The videoWatchCount attribute specifies the number of videos that a user has watched on YouTube. The videoWatchCount attribute is only specified when the <yt:statistics> tag appears within a user profile entry. |
subscriberCount | Integer | The subscriberCount attribute specifies the number of YouTube users who have subscribed to a particular user's YouTube channel. The subscriberCount attribute is only specified when the <yt:statistics> tag appears within a user profile entry. |
lastWebAccess | DateTime | Deprecated. This attribute will always return a value of 1970-01-01T00:00:00.000Z .The lastWebAccess attribute indicates the most recent time that a particular user used YouTube. |
favoriteCount | Integer | The favoriteCount attribute specifies the number of YouTube users who have added a video to their list of favorite videos. The favoriteCount attribute is only specified when the <yt:statistics> tag appears within a video entry. |
totalUploadViews | Integer | The totalUploadViews attribute specifies the total number of views for all of a channel's videos. This attribute is only specified when the <yt:statistics> tag appears within a user profile entry. |
Example
<yt:statistics viewCount='9' videoWatchCount='24' subscriberCount='1' lastWebAccess='2008-02-29T13:09:48.000-08:00'/>
Child of
yt:status
The <yt:status> tag appears in contact feed entries and live event feed entries.
- In a contact feed entry, this tag identifies the status of a contact. It is only included in the entry if you are retrieving the currently authenticated user's contacts. The following tag values are valid:
accepted
– The authenticated user and another user have added each other as contacts.requested
– Another user has added the authenticated user as a contact, but the authenticated user has not also added the other user as a contact.pending
– The authenticated user has added another user as a contact, but that user has not also added the authenticated user as a contact.
- In a live event entry, this tag specifies the status of an event. The following tag 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.
Example
In a contact feed entry:
<yt:status>accepted</yt:status>
In a live events feed entry:
<yt:status>pending</yt:status>
Child of
yt:threed
The <yt:threed> tag indicates, by its presence, that a video contains 3D content.
Attributes
Name | Format | Description |
---|---|---|
source | Text | The source attribute explains why the video is labeled as 3D content. Possible attribute values are:
|
Example
<yt:threed source='declared'/>
Child of
yt:unreadCount
The <yt:unreadCount> tag shows the amount of activity for the subscribed-to channel since the last time the user was logged in and filtered to that channel via the YouTube channel guide. The guide displays on the YouTube home page.
Note that similar events may be aggregated in the tag's value. For example, if the channel owner uploads a video and marks it as a favorite, those two actions may only increment the <yt:unreadCount>
value by one.
Example
<yt:unreadCount>5</yt:unreadCount>
Child of
yt:uploaded
The <yt:uploaded> tag specifies the time that a playlist entry was originally uploaded to YouTube.
Example
<yt:uploaded>2007-10-15T15:39:34.000-07:00</yt:uploaded>
Child of
yt:uploaderId
The <yt:uploaderId> tag specifies a unique ID that YouTube uses to identify the user who uploaded a video.
Example
<yt:uploaderId>WBw1PCAJfWtqaNpsFIOeiA</yt:uploaderId>
Child of
yt:userId
The <yt:userId> tag contains a value that uniquely identifies a YouTube user regardless of account characteristics such as whether the user's account has a YouTube channel or is connected to a Google+ profile. If you need to manually generate a feed URL that is not for the default user, you can use this value as the username in the feed URL.
Example
<yt:userId>ZxF-foo3h3B3mb4cuiBcKA</yt:userId>
Child of
yt:username
The <yt:username> tag specifies either a YouTube username or a globally unique YouTube user ID that identifies the user account. (See the <yt:userId>
tag definition for more details about that value.) Regardless, the value will be a valid value to use in a feed URL. However, we recommend that you use the value of this tag's display attribute as a meaningful value to display when identifying a user.
- In a subscriptions feed, the <yt:username> tag identifies the user whose actions are being subscribed to (for a user activity subscription), or the owner of the YouTube channel associated with the subscription.
- In a request to add a subscription, the <yt:username> tag identifies the user whose activity or channel is being subscribed to.
- In a profile entry, the <yt:username> tag identifies the user associated with the profile.
- In a user contact entry, the <yt:username> tag identifies the contact of the logged-in user.
- In an activity feed entry, the <yt:username> tag identifies the user associated with an action. For example, it might identify the user who owns a channel that was subscribed to.
- In a request to upgrade an unlinked Google Account so that it is associated with a YouTube username (and channel), the <yt:username> tag identifies the YouTube username that the account holder wants to have.
Attributes
Name | Format | Description |
---|---|---|
display | Text | The display attribute contains a meaningful, but non-unique, value for a user that is suitable to display as a username. For users who have accounts that are connected to Google+, the attribute value will be the user's full public display name. For users who have full YouTube accounts (as opposed to unlinked Google accounts) that are not connected to Google+, the attribute value will be set to the user's YouTube account name. |
Example
<yt:username display="GoogleDevelopers">googledevelopers</yt:username>
Child of
yt:videoid
The <yt:videoid> tag specifies a unique ID that YouTube uses to identify a video. In an activity feed entry, the <yt:videoid> tag identifies the video that was rated, shared, commented on, uploaded, or marked as a favorite.
Example
<yt:videoid>QbEwKcs-8Hc</yt:videoid>
Child of
yt:when
The <yt:when> tag identifies the time that a live event started (or is expected to start). The tag can also specify the time that the event ended or is expected to end.
Attributes
Name | Format | Description |
---|---|---|
start | DateTime | Required. The start attribute specifies the time that a live event started or is expected to start. |
end | DateTime | Optional. The start attribute specifies the time that a live event ended or is expected to end. |
Example
<yt:when end="2011-06-14T14:37:24.000Z" start="2011-06-14T13:00:00.000Z"/>
Child of
Media RSS elements reference
media:category
The <media:category> tag specifies information that describes a video, lecture, or course.
- For any video, the
<media:category>
tag can specify a YouTube category associated with that video. The Category List for Uploaded Videos section discusses YouTube video categories that may be associated with a video, and each video may be assigned to exactly one such category. - For any video, the
<media:category>
tag can specify a developer tag that describes that video. A developer tag is a private category or keyword and uses the category schemehttp://gdata.youtube.com/schemas/2007/developertags.cat
. Please see the Assigning Developer Tags section of the protocol document for more information about developer tags. - For videos in the Movies, Shows, or Trailers categories, the
<media:category>
tag can contain any of the following additional types of information:- If the categorization scheme is
http://gdata.youtube.com/schemas/2007/mediatypes.cat
, then the tag indicates whether the video is a feature film, a short film, a full television show episode, a television show clip, or a trailer. Valid tag values for this categorization scheme are1
– Feature-length film2
– Short film3
– Full episode4
– Show clip5
– Trailer
- If the categorization scheme is
http://gdata.youtube.com/schemas/2007/moviegenres.cat
, then the tag identifies a genre that describes a movie or trailer. (A movie or trailer may be associated with multiple genres.) Valid tag values for this categorization scheme are:1
– Action & Adventure2
– Animation & Cartoons3
– Classics4
– Comedy5
– Crime6
– Drama7
– Documentary & Biography8
– Family9
– Foreign10
– Horror11
– Mystery & Suspense12
– Romance13
– Science Fiction15
– Sports18
– Indian Cinema19
– Nigerian Cinema
- If the categorization scheme is
http://gdata.youtube.com/schemas/2007/releasemediums.cat
, then the tag specifies the original release medium for the video. Valid tag values for this categorization scheme are1
– Theatrical or festival film releases2
– Premium cable or satellite subscription channels, such as HBO3
– Basic cable and satellite channels, such as Comedy Central or MTV4
– Broadcast TV networks and local TV stations5
– Promotional clips and trailers6
– Original web content7
– Direct-to-video release
- If the categorization scheme is
- For courses and lectures, the
<media:category>
tag can use the category schemehttp://gdata.youtube.com/schemas/2007/educategories.cat
, in which case the tag identifies a YouTube EDU category associated with the course or lecture.
Attributes
Name | Format | Description |
---|---|---|
label | Text | The label attribute specifies the entity-escaped name of the YouTube category to which the video belongs. |
scheme | Text (URI) | The scheme attribute specifies a URI that identifies the categorization scheme associated with the label. |
Example
<media:category label='Sports' scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>Sports</media:category>
Child of
media:content
The <media:content> tag is used in the following contexts:
- In a video entry, the <media:content> tag provides a URL and various other types of information about a video.
- In a live video entry, the tag also specifies a streaming format as well as the stream name and the ingestion URL that you should use when streaming video to YouTube in that format.
Depending on which application or tool you use to encode your video stream, you may need to enter the stream URL and stream name separately or you may need to concatenate them in the following format:STREAM_URL/STREAM_NAME
Attributes
Name | Format | Description |
---|---|---|
url | Text (URL) | The url attribute specifies the URL for the media object. |
type | Text | The type attribute specifies the MIME type of the media object. |
isDefault | Boolean | The isDefault attribute indicates whether the corresponding <media:content> tag identifies the default media resource for the media group. In a YouTube Data API response, the default media resource is the URL for the embeddable player (SWF) for the video. |
expression | Text | The expression attribute indicates whether the video object represents a sample of the video, the complete version of the video, or a live video stream. The corresponding (and only) valid values for this attribute are sample, full and nonstop. |
duration | Integer | The duration attribute specifies the length of the video in seconds. |
yt:format | Text | The yt:format attribute specifies either the video format of the video object described by the <media:content> element. It can also specify a format in which the owner of a live event will stream video for that event. The following list identifies the valid values for this attribute when it refers to the video format of a playable video:
|
yt:name | String | The yt:name attribute specifies the RTMP stream name assigned to a particular video stream. YouTube will assign a different stream name to each ingestion URL. |
Example
Video entry:
<media:content url='http://www.youtube.com/v/8aYQ_wjmriQ' type='application/x-shockwave-flash' medium='video' isDefault='true' expression='full' duration='166' yt:format='5'/>
Live video entry:
<media:content yt:format="19" yt:name='yt-live_SpQXZYILnN0_35' url='rtmp://rtmp1.youtube.com/videolive?...'/>
Child of
media:credit
The <media:credit> tag can appear in several contexts:
- In video feed entries, it can either identify the YouTube partner that owns a video, or it can identify a contributor (actor, director, producer, or writer) if the video is a movie or television show episode.
- In playlist feed entries and inbox feed entries, it will only identify the YouTube partner that owns the video, and it will identify a different user than the <author> tag. (The <author> tag in those feeds identifies a user other than the video owner.)
- In course entries, lecture entries, and feeds of lectures in a course, it can identify a lecturer for the course or lecture.
Attributes
Name | Format | Description |
---|---|---|
role | Text | The role attribute specifies the way that a YouTube user is associated with a particular video. The attribute's possible value set is determined by the specified role scheme. (See the scheme parameter.)
|
scheme | Text | The scheme attribute identifies the role scheme.
|
yt:display | Text | The yt:display attribute contains a meaningful, but non-unique, value for a user that is suitable to display as a username. For users who have accounts that are connected to Google+, the attribute value will be the user's full public display name. For users who have full YouTube accounts (as opposed to unlinked Google accounts) that are not connected to Google+, the attribute value will be set to the user's YouTube account name. |
yt:type | Text | The yt:type attribute indicates that a video was uploaded by a YouTube partner. When present, the value of this attribute will be partner. This attribute is only present if the role attribute's value is uploader . |
Example
<media:credit role="uploader" scheme="urn:youtube">scenarioIAM</media:credit><br/><media:credit role='Writer' scheme='urn:ebu'>Dennis Johnson</media:credit>
Child of
media:description
The <media:description> tag contains a summary or description of a video. This field is required in requests to upload or update a video's metadata. The description should be sentence-based, rather than a list of keywords, and may be displayed in search results. The description has a maximum length of 5000 bytes and may contain all valid UTF-8 characters except < and >.
In API response feeds, descriptions are truncated to 500 characters unless one of the following conditions is true:
You submitted an authorized request for a single video entry on behalf of the video owner. In this case, you submitted the API request to the following URL:
http://gdata.youtube.com/feeds/api/users/default/uploads/VIDEO_ID
You submitted an authorized request for the currently authenticated user's uploaded videos and your request did not specify search parameters other than start-index or max-results. In this case, you submitted the API request to the following URL:
http://gdata.youtube.com/feeds/api/users/default/uploads
Attributes
Name | Format | Description |
---|---|---|
type | Text | The type attribute specifies the type of text provided in the tag's value. YouTube content feeds require plain text (type=plain) format. |
Example
<media:description type="plain">Granny takes crocheting to the extreme during a rodeo and while surfing.</media:description>
Child of
media:group
The <media:group> tag encapsulates metadata about a video resource.
Example
<media:group>
Child of
Children
media:title?, media:description?, media:keywords?, media:category, media:content*, media:credit*, media:player?, media:price*, media:rating?, media:restriction?, media:thumbnail*, yt:aspectratio?, yt:audioTracks?, yt:captionTracks?, yt:duration?, yt:private?, yt:uploaded?, yt:uploaderId?, yt:videoid?
media:keywords
The <media:keywords> tag contains a comma-separated list of words associated with a video. This field has a maximum length of 500 bytes including commas, and may contain all valid UTF-8 characters except < and >. In addition, each keyword must be at least two bytes long and may not be longer than 30 bytes.
Keywords may contain spaces, meaning an individual keyword can actually be more than one word long. For example, crazy,surfing,stunts and crazy, surfing stunts are both valid values for this tag, but the former value contains three keywords and the latter value contains only two ("crazy" and "surfing stunts"). In addition, if a keyword contains spaces, then the API server will infer that there are quotation marks around the keyword. As such, the keyword surfing stunts is handled as a 16-byte keyword containing 13 letters, two quotation marks and one space.
Note: A video entry in an API response only includes a value for the <media:keywords>
tag if the API request is authorized by the owner of that video. If the request is not authorized or is authorize by a user other than the video owner, then the <media:keywords>
tag in the video entry will be empty.
Example
<media:keywords>winter, snowball fight, snowman, corncob pipe</media:keywords>
Child of
media:license
The <media:license> tag identifies the license associated with the video. Possible values are cc
, which indicates that the video has a Creative Commons license, and youtube
, which indicates that the video has a standard YouTube license. You can set the license for a video at upload time or you can edit it later.
Attributes
Name | Format | Description |
---|---|---|
type | Text | The type attribute specifies the MIME type of the content at the URL provided for the license. |
href | Text | The href attribute specifies the URL for a human-readable document that specifies the license terms. |
Example
<media:license type='text/html' href='http://creativecommons.org/licenses/by/3.0/'>cc</media:license>
or
<media:license type='text/html' href='http://www.youtube.com/t/terms'>youtube</media:license>
Child of
media:player
The <media:player> tag specifies a URL where the full-length video is available through a media player that runs inside a web browser. In a YouTube Data API response, the <media:player> tag specifies the URL for the page on YouTube's website that plays the video.
Attributes
Name | Format | Description |
---|---|---|
url | Text (URL) | The url attribute identifies a URL that uses a video player to show the video in a browser window. |
Example
<media:player url='http://www.youtube.com/watch?v=8aYQ_wjmriQ'/>
Child of
media:price
The <media:price>
tag contains pricing information about a particular offer for an item. An item can contain multiple <media:price>
tags, each containing a different offer. For example, a video rental might be available in different formats (standard vs. HD) for different prices. Video entries for rental content will contain <media:price>
tags if the API request specified a developer key.
Attributes
Name | Format | Description |
---|---|---|
type | Text | The type attribute specifies the type of offer. The Media RSS specification defines the valid values for this attribute to be rent , purchase , package , and subscription . |
price | Decimal | The price attribute specifies the numeric cost of the offer. |
currency | Text | The currency attribute specifies the currency associated with the offer price. The value will be an ISO 4217 three-letter currency code. |
yt:duration | Text | The yt:duration attribute specifies the amount of time that a user has to watch the content. The tag value is an ISO 8601 duration. The value is specified in the format PT#S , in which the letters PT indicate that the value specifies a period of time, and the letter S indicates that the time period is specified in seconds. The # is an integer that specifies the number of seconds that the content is available for viewing. For example, a value of PT86400S indicates that the content is available for 86,400 seconds, or one day. |
Example
<media:price type='rent' price='1.99' currency='USD' yt:duration='PT86400S'/>
Child of
media:rating
The <media:rating> tag serves one of the following purposes:
- If the
scheme
attribute value is eitherurn:mpaa
orurn:v-chip
, then the tag specifies the rating that a movie received under that rating scheme. - If the
scheme
attribute value ishttp://gdata.youtube.com/schemas/2007#mediarating
, then the tag indicates that a video contains restricted content. In this context, the tag will only be included in a video entry if the video contains restricted content. However, even if the <media:rating> tag is included in a video entry, the video content may not be restricted in the country where the user watching the video is located. Your application can check the value of the tag's country parameter to determine where the video content is considered to be restricted.
Note: A feed will only include content that is restricted in all countries if your API request included the safeSearch parameter with a value of none (safeSearch=none). The <media:rating> tag replaced the <yt:racy> tag, which was deprecated with the release of version 2 of the API.
Attributes
Name | Format | Description |
---|---|---|
scheme | Text | The scheme attribute identifies the categorization scheme associated with the rating. Valid values are:
|
country | Text | The country attribute identifies the country or countries where a video is considered to contain restricted content. The attribute value will either be the word all, which indicates that the video contains content that is considered restricted everywhere, or a comma-delimited list of ISO 3166 two-letter country codes identifying particular countries where the video content is restricted. Note: This attribute will only be specified for a <media:rating> tag if the value of the scheme attribute is http://gdata.youtube.com/schemas/2007#mediarating . |
Example
<media:rating scheme="http://gdata.youtube.com/schemas/2007#mediarating" country="HK,TW">1</media:rating>
<media:rating scheme="urn:v-chip">pg-13</media:rating>
Child of
media:restriction
The <media:restriction> tag identifies the country or countries where a video may or may not be played. The attribute value is a space-delimited list of ISO 3166 two-letter country codes. The <media:restriction> tag only appears in a feed entry if the corresponding video cannot be played in all countries. (Note that a video will only be included in an API response if it is allowed to be played at the location specified by the restriction parameter.)
Attributes
Name | Format | Description |
---|---|---|
type | Text | The type attribute specifies the type of information conveyed by the tag's value. The value of this attribute will be country, indicating that the tag value contains a list of country codes. |
relationship | Text | The relationship attribute indicates whether the video is allowed to be played in the specified countries. If the tag's value is allow, then the video can be played in the specified countries. If the tag's value is deny, then the video cannot be played in the specified countries. |
Example
<media:restriction type='country' relationship='deny'>US</media:restriction>
Child of
media:thumbnail
The <media:thumbnail> tag specifies the location of an image that can be used to represent a video or playlist in a list of results. A videos feed may reference multiple thumbnail images and multiple sizes of those images. Your code should not make any assumptions about the order in which <media:thumbnail>
tags appear in API responses. Instead, your code should rely on the value of the yt:name
attribute to select the most appropriate image for your application.
A video entry might list any or all of the following thumbnails:
- The tag that has a
yt:name
attribute value ofhqdefault
identifies a high-quality image for the video. The high-quality image does not have a timestamp and could be from any point in the video. It may also be larger than the other thumbnails referenced in the entry. - The tag that has a
yt:name
attribute value ofmqdefault
identifies a 320x180 (16:9) thumbnail image. This image does also does not have a timestamp and could be from any point in the video. - The tags with attribute values of
start
,middle
, andend
show video frames that occur at different points of the video. However, the times given for those thumbnails do not necessarily reflect the times when those frames actually appear in the video. In addition, the relative ordering of thumbnails implied by theyt:name
values may also not be accurate. - Movies uploaded by YouTube partners can also have a thumbnail image with a
yt:name
attribute value ofposter
, which identifies the poster art for the movie. A movie poster is typically 169px wide and 243px high.
- Different sizes of the poster art for the show are identified by the tags with
yt:name
attribute values ofposter
(150px by 150px),hqposter
(300px by 300px), orhqposterlarge
(600px by 600px) represent different sizes of the poster art for the show. - Different sizes of 16:9 marketing artwork for a show are identified by tags with
yt:name
attribute values ofmarket
(72px by 128px) orhqmarket
(243px by 432px).
Attributes
Name | Format | Description |
---|---|---|
url | Text (URL) | The url attribute specifies the URL for the thumbnail image. |
height | Integer | The height attribute specifies the height of the thumbnail image. |
width | Integer | The width attribute specifies the width of the thumbnail image. |
time | Time | The time attribute specifies the time offset at which the frame shown in the thumbnail image appears in the video. The attribute value is expressed in DSM-CC's Normal Play Time (NTP) as used in RTSP. The time value enables you to display a sequence of screenshots from a video. Note that if your application does display a series of screenshots, you may want to check the values of the height and width attributes to ensure that each screenshot is the same size. The time attribute does not appear on the <media:thumbnail> tag that identifies the high-quality (HQ) thumbnail image. |
yt:name | Text | The yt:name attribute specifies a name that identifies a thumbnail image. Possible values are hqdefault , mqdefault , default , market , hqmarket , poster , hqposter , hqposterlarge , start , middle , and end . |
Example
<media:thumbnail url='http://img.youtube.com/vi/8aYQ_wjmriQ/2.jpg' height='90' width='120' time='00:01:23' yt:name='default'/>
Child of
media:title
The <media:title> tag identifies the title of the video. This field has a maximum length of 100 bytes. The title may contain all valid UTF-8 characters except < and >.
Attributes
Name | Format | Description |
---|---|---|
type | Text | The type attribute specifies the type of text provided in the tag's value. YouTube content feeds require plain text (type=plain) format. |
Example
<media:title type="plain">Extreme crocheting in high surf, rodeo</media:title>
Child of
GData elements reference
gd:comments
The <gd:comments> tag encapsulates a link to the comments feed for a video.
Example
<gd:comments>
Child of
Children
gd:feedLink
The <gd:feedLink> tag identifies a logically nested feed. For example, a comments feed is logically nested beneath a video entry. Similarly, the feed for a single playlist is logically nested within a playlist entry in a user's playlists feed.
Attributes
Name | Format | Description |
---|---|---|
rel | Text | The rel attribute contains the name of the related feed linked to in the href attribute. |
href | Text (URL) | The href attribute contains the absolute URL of the related feed. |
gd:countHint | Integer | The gd:countHint specifies the number of entries in the related feed. For example, if the <gd:feedLink> tag specifies a link to the comments feed for a video, the gd:countHint attribute indicates how many comments exist for the video. |
Example
<gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/8aYQ_wjmxiQ/comments' countHint='0'/>
Child of
gd:rating
Deprecated on April 14, 2011. Please use the <yt:rating>
element instead.
The <gd:rating> tag specifies the rating that you are assigning to a video (in a request to add a rating) or the current average rating of the video based on aggregated YouTube user ratings.
Attributes
Name | Format | Description |
---|---|---|
min | Integer | The min attribute specifies the minimum rating that can be assigned to a video. This value must be 1. |
max | Integer | The max attribute specifies the maximum rating that can be assigned to a video. This value must be 5. |
numRaters | Integer | The numRaters attribute indicates how many people have rated the video. This attribute is not used in a request to add a rating. |
average | Double | The average attribute indicates the average rating given to the video. This attribute is not used in a request to add a rating. |
value | Integer | The value attribute specifies the rating that the logged-in user is giving to a video. This attribute is only specified in a request to add a rating. The value must be between 1 and 5 inclusive. |
Example
Rating information in an API response:
<gd:rating min='1' max='5' numRaters='7773' average='4.75'/>
Assigning a rating to a video:
<gd:rating value="4" min="1" max="5"/>
Child of
GeoRSS elements reference
georss:where
The <georss:where> tag encapsulates information about a geographic location. Note that if there is already a geographic location associated with a video, you must include that location information in subsequent requests to update that video's information or the geographic location will be deleted.
Example
<georss:where>
Child of
Children
GML elements reference
gml:Point
The <gml:Point> tag contains information about a specific geographic location. Geographic point locations are defined in two dimensions using WGS 84. You can specify the geographic location where a video was taken in requests to upload or update that video's metadata. Note that if there is already a geographic location associated with a video, you must include that location information in subsequent requests to update that video's information or the geographic location will be deleted.
Example
<gml:Point>
Child of
Children
gml:pos
The <gml:pos> tag specifies the coordinate for a geographic point. Geographic point locations are defined in two dimensions using WGS 84. Note that if there is already a geographic location associated with a video, you must include that location information in subsequent requests to update that video's information or the geographic location will be deleted.
Example
<gml:pos>47.367 8.55</gml:pos>
Child of
Atom Publishing Protocol element reference
app:control
The <app:control> tag contains information about the publication state of a video. The tag's presence indicates that one of the following statements applies to a video:
- The video has not yet been published.
- The video is no longer publicly available.
- Access to view the video is restricted.
- The video is not available in the region where the user trying to watch the video is located.
- YouTube rejected the video during the video upload process.
- The request to upload the video failed.
Example
<app:control>
Child of
Children
app:draft
The <app:draft> tag indicates whether a video is in draft, or unpublished, status. Since this tag is only included for unpublished videos, it always has a value of yes.
Example
<app:draft>yes</app:draft>
Child of
app:edited
The <app:edited> tag specifies the time that a feed or feed entry was last updated.
Example
<app:edited>2007-10-15T15:39:34.000-07:00</app:edited>
Child of
Browser-based upload API response elements reference
response
The <response> tag encapsulates the API response that YouTube returns to an API request to upload metadata for a new video using browser-based uploading.
Example
<response>
Children
token
The <token> tag appears in the API response that YouTube returns to an API request to upload metadata for a new video using browser-based uploading. The token must be included on the page that allows the user to upload the new video directly to YouTube.
Example
<token>AEwbFAQEvf3xox...</token>
Child of
url
The <url> tag appears in the API response that YouTube returns to an API request to upload metadata for a new video using browser-based uploading. The form on your web page that lets the user upload the actual video file to YouTube will submit to this URL.
Example
<url>http://uploads.gdata.youtube.com/action/FormUpload/AEF3087AUD</url>
Child of
Batch processing element reference
batch:id
The <batch:id> tag contains a value that you define to uniquely identify an entry in a batch processing request. This tag is typically used for entries that correspond to insert operations. The API response to your batch processing request will echo the <batch:id> tag for each entry, enabling your application to correlate the entry in the response to the original request.
Note that the <batch:id> tag is different than the <id> tag.
The <id> specifies a value that the YouTube server assigns when creating a resource. This identifier is returned in the API response and permanently identifies the corresponding resource.
The <batch:id> tag is an identifier that you choose when creating a batch processing request. The identifier will be returned in the API response but will not be stored for future use.
When you submit a batch processing request to query (GET), update (PUT) or delete (DELETE) information, each entry in the request will contain an <id> element that identifies the resource that you are retrieving, updating or deleting. In the API response, each entry will contain an <id> tag, which will be the same as the <id> value in your request, and a <batch:status> tag, which indicates whether the operation was successful.
However, when you insert (POST) information, you are creating a new resource, which will be assigned its own unique ID. (For example, if you submit a batch processing request to add several videos to a playlist, YouTube will assign a unique playlist entry ID to each video that you add.) In the API response to your batch processing request, each entry for an insert operation will also include an <id> tag and a <batch:status>. Since the <id> tag contains a new value that did not exist when you made your API request, you may need to use the <batch:id> tag value to correlate the entry in the API response to the entry in your batch processing request. Please see the Developer's Guide for more information about insert operations in a batch processing request.
Example
<batch:id>PlaylistEntry3</batch:id>
Child of
batch:interrupted
The <batch:interrupted> tag indicates that processing of your API request was interrupted. This tag is returned if the XML of an entry is invalid. If the API response to your batch processing request contains this tag, then some entries in your request may have been successfully executed while other entries either failed or were not processed at all.
Attributes
Name | Format | Description |
---|---|---|
reason | Text | The reason attribute contains an explanation of the error that caused the batch processing request to be interrupted. |
parsed | Integer | The parsed attribute identifies the number of entries in the batch processing request that were attempted. The number of parsed entries equals the number of successful entries plus the number of error entries. |
success | Integer | The success attribute identifies the number of entries in the batch processing request that were successfully processed. |
error | Integer | The error attribute identifies the number of entries in the batch processing request that were attempted but that failed to process successfully. |
unprocessed | Integer | The unprocessed attribute identifies the number of entries that are known to exist in the batch processing request that were not processed. |
content-type | Text | The content-type attribute specifies the MIME type of the data returned in the element. This attribute is only returned if the element contains a text description. |
Example
<batch:interrupted reason="[Line 14, Column 34, element entry] Invalid type for batch:operation: 'PUT'" success="8" failures="3" parsed="14"/>
Child of
batch:operation
The <batch:operation> tag specifies the type of operation requested for a batch processing job.
In a batch processing request, the <batch:operation> tag can appear as a subtag of either <feed> or <entry>. If neither a feed nor an entry in that feed contain a <batch:operation> tag, then the default operation for that entry will be insert.
As a subtag of <feed>, the <batch:operation> tag specifies the default type of operation (query, insert, update or delete) that you are requesting for each entry in the feed. You can override this default value for specific entries by including the <batch:operation> tag in those entries.
As a subtag of <entry>, the <batch:operation> tag specifies the type of operation (query, insert, update or delete) that you want to perform on that entry in the batch feed.
In a response to a batch processing request, the <batch:operation> tag appears as a subtag of <entry> and specifies the type of operation performed on that entry.
Attributes
Name | Format | Description |
---|---|---|
type | Text | The type attribute specifies the type of operation being performed in a batch processing API request. Valid values for this attribute are query, insert, update and delete. |
Example
<batch:operation type="insert"/>
Child of
batch:status
The <batch:status> tag appears in the API response to a batch processing request. This tag indicates whether a specific operation in a batch processing request was successfully executed. The tag's attributes identify the HTTP response code that the API server returned when the specific operation was executed and a short description explaining the response code.
Attributes
Name | Format | Description |
---|---|---|
code | Integer | The code attribute specifies the HTTP response code for the entry. |
reason | Text | The reason attribute contains a text description that describes the HTTP response code. |
content-type | Text | The content-type attribute specifies the MIME type of the data returned in the element. This attribute is only returned if the element contains a text description. |
Example
<batch:status code="201" reason="Created"/>
Child of
Error response element reference
code
The <code> tag explains the reason that the API request failed. The following lists identify the possible values for the <code> tag based on the value of the corresponding <domain> tag:
yt:validation:
- required - This code indicates that a required field is missing or has an empty value.
- deprecated - This code indicates that an element's value has been deprecated and is no longer valid. For example, a video category name that has been retired may not be associated with newly added or updated videos.
- invalid_format - This code indicates that an XML element's value does not match an expected format. For example, you could receive this error if you specify invalid coordinates in the <gml:pos> tag.
- invalid_value - This code indicates that an XML field value contains an invalid value. This error code occurs when an element has an enumerated list of values and the element's value does not match one of the enumerated values. For example, the category list for uploaded videos identifies valid values for the <media:category> tag.
- invalid_character - This code indicates that an XML field value contains an invalid character. For example, video titles may not contain a less than (<) character.
- too_long - This code indicates that an XML element's value exceeds the maximum allowable length. For example, video titles must be 100 bytes or less.
- too_short - This code indicates that an XML element's value is shorter than the minimum allowable length. For example, keywords must be at least two characters long.
- yt:quota:
- too_many_recent_calls - This code indicates that the API servers have received too many calls from the same caller in a short amount of time. This error will not specify a location.
- too_many_entries - This code indicates that the user is attempting to exceed a storage limit on his account and must delete existing entries before inserting new entries.
- yt:authentication:
- InvalidToken - This code indicates that the token specified in the Authorization header is invalid.
- TokenExpired - This code indicates that the token specified in the Authorization header has expired.
- yt:service:
- disabled_in_maintenance_mode - This code indicates that POST, PUT and DELETE operations cannot be executed because the site is temporarily in maintenance mode. If you receive this error, wait a few minutes and try your request again.
Example
<code>required</code>
Child of
domain
The <domain> tag identifies the error that caused an API request to fail. The following list identifies the possible values of the <domain> tag:
A yt:validation error reports a problem related to an XML element value in a request to insert or update an entry. API functions that insert or update videos or other data can report yt:validation errors. Validation errors are typically reported with an HTTP 400 response code.
A yt:quota error identifies a problem related to irregular API usage.
A yt:authentication error identifies a problem related to an improperly authenticated or unauthorized request to execute an API function requiring user authentication or authorization. Such errors could be identified with HTTP 401 or 403 response codes.
A yt:service error identifies an authentication error that occurs when the YouTube site is undergoing temporary maintenance. A service error may occur if you are trying to execute insert (POST), update (PUT) or delete (DELETE) operations, but will not occur for read (GET) operations. Service errors are typically reported with an HTTP 503 response code.
Example
<domain>yt:validation</domain>
Child of
error
The <error> tag contains information about a single error that caused an API request to fail.
Example
<error>
Child of
Children
errors
The <errors> tag encapsulates an API response explaining the errors that caused the corresponding API request to fail.
Example
<errors>
Children
location
The <location> tag provides information about the element in the request that failed.
If the value of the <domain> tag is yt:validation, then the <location> tag defines the error location as an Xpath pointing to the XML tag that caused the request to fail. The Xpath location is specified relative to the <entry> tag in the request.
If the value of the <domain> tag is yt:quota and the <code> tag value is too_many_recent_calls, then the API response will not include a <location> tag.
If the value of the <domain> tag is yt:quota and the <code> tag value is too_many_entries, then the <location> tag identifies the feed that caused the error.
If the value of the <domain> tag is yt:authentication, then the <location> tag, if present, will identify the tag causing the error.
Attributes
Name | Format | Description |
---|---|---|
type | Text | The type attribute provides context for the <location> tag's value. The type attribute can have any of the following values:
|
Example
<location type='xpath'>media:group/media:title/text()</location>
Child of
Appendixes
Category list for uploaded videos
The YouTube category document, which can be downloaded from http://gdata.youtube.com/schemas/2007/categories.cat, identifies the categories that you can use to classify video content. The category document is an XML file that identifies the categories and indicates whether new videos can be assigned to each category. The document also identifies the countries where each category is browsable on YouTube.
The excerpt below shows the entries for the "Entertainment" and "Nonprofit & Activism" categories as they appear in the YouTube category document as of August 13, 2008. Please note that videos could be assigned to both categories. In addition, the document lists many countries where the "Entertainment" category is browsable but indicates that the "Nonprofit & Activism" category was only browsable in the United States at that time.
As shown in the example, the presence of the <yt:assignable> tag indicates that new videos may be assigned to that category. (New videos cannot be assigned to categories that are not marked as assignable using the <yt:assignable> tag.) In addition, the presence of the <yt:browsable> tag indicates that the corresponding category is browsable on YouTube in one or more countries. The <yt:browsable> tag's regions attribute contains a space-delimited list of two-letter regionIDs that identify the particular countries where the category is browsable. The Retrieving region-specific standard feeds section contains a list of countries for which YouTube supports localized feeds and the regionID associated with each country. Categories that are neither assignable or browsable are deprecated and are identified as such using the <yt:deprecated> tag.
<atom:category term='Entertainment' label='Entertainment' xml:lang='en-US'> <yt:browsable regions='AU BR CA FR DE GB NL HK IN IE IT JP MX NZ PL RU KR ES TW US'/> <yt:assignable/> </atom:category> <atom:category term='Nonprofit' label='Nonprofit & Activism' xml:lang='en-US'> <yt:assignable/> <yt:browsable regions='US'/> </atom:category> <atom:category term='Videoblog' label='Videoblogging' xml:lang='en-US'> <yt:deprecated/> </atom:category>
In your Upload API request, the value of the <media:category> tag must be set to the value of the <atom:category> tag's term attribute for the corresponding category. The following example demonstrates how you would use the <media:category> tag to assign a new video to the Nonprofit & Activism category, which appears in the schema excerpt above.
<media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">Nonprofit</media:category>
Localized category lists
You can also retrieve localized category lists that specify category labels for classifying video content in particular languages. You can download these lists from http://gdata.youtube.com/schemas/2007/categories.cat?hl=<LANGUAGE>, where you replace the term LANGUAGE in the URL with the appropriate language value from the following list. (Instead of appending the hl parameter value to the schema URL, you can also set the Accept-Language HTTP request header to the appropriate language value.)
|
|
The XML excerpt below shows the entries for the "Entertainment" and "Nonprofit & Activism" categories as they appear in the YouTube category document for the French language as of May 5, 2008:
<atom:category term='Entertainment' label='Divertissement' xml:lang='fr-FR'> <yt:assignable/> <yt:browsable/> </atom:category> <atom:category term='Nonprofit' label='Associations et organismes' xml:lang='fr-FR'> <yt:assignable/> </atom:category>
In your Upload API request, the value of the <media:category> tag must still be set to the value of the <atom:category> tag's term attribute for the corresponding category. (Note that the term attribute value may still be in English. However, you can modify the value of the <media:category> tag's scheme attribute to identify the language associated with category. The following example demonstrates how you would use the <media:category> tag to assign a new video to the Divertissement (Entertainment) category, which appears in the schema excerpt above.
<media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat?hl=fr-FR">Entertainment</media:category>
URL escaping
To make an HTTP search request, you must follow certain conventions so that Google can correctly translate your HTTP request and generate an appropriate response.
The HTTP URL schema specifies that an HTTP URL request may only contain certain characters:
- Alphanumeric characters: [a-z][A-Z][0-9]
- Special characters: $ - _ . | + ! * ' ( )
- Reserved characters: ; / ? : @ = & %
Google uses reserved characters to decode URLs and uses some special characters to request search features. Consequently, you should URL escape all nonalphanumeric characters that occur in search parameter values.
To URL escape a string, convert each sequence of whitespace characters to a single "+" (plus sign) and replace any other non-alphanumeric characters with the hexadecimal encoding that represents the value of that character. The hexadecimal encodings for the special and reserved characters listed above are shown in the following table. Each of these characters should be URL escaped in request parameter values.
Character | Hexadecimal Encoding |
---|---|
$ | %24 |
- | %2D |
_ | %5F |
. | %2E |
+ | %2B |
! | %21 |
* | %2A |
% | %25 |
" | %22 |
' | %27 |
( | %28 |
) | %29 |
; | %3B |
/ | %2F |
? | %3F |
: | %3A |
@ | %40 |
= | %3D |
& | %26 |
| | %7C |
Examples
Original String | URL Escaped String |
---|---|
punch&judy | punch%26judy |
O'Reilly | O%27Reilly |
You can find additional information on URL escaping in RFC 3986.
Revision History
March 4, 2014
This update contains the following changes:
-
This API has been officially deprecated. API functionality will continue to work as per our deprecation policy, but we encourage you to migrate to the new YouTube Data API (v3) as soon as possible.
While the v3 API offers the majority of functionality available in this API (and a lot of other functionality as well), there are still a couple of tasks that can only be completed with this API. Specifically, applications that manage captions or that work with video comments still need to use the v2 API until v3 API equivalents are available.
-
The API's support for retrieving and managing live events have also been deprecated. These features had been explicitly excluded from the list of API features subject to our deprecation policy and are therefore not supported under that policy.
API requests for retrieving live events are still working at this time. API requests to create, update, or delete live events return a 403 HTTP response code.
We recommend that you transition your application to use the YouTube Live Streaming API to create and manage live events and the YouTube Data API (v3) to search for live events. In the Data API, the
search.list
method'seventType
parameter lets you restrict a search to only return either active, upcoming, or completed broadcast events. That API supports other features to help you find and feature live broadcast content, which are explained in the API's release notes for October 24, 2013.
November 6, 2013
This update contains the following changes:
-
YouTube is switching to a new commenting system. As part of this change, you may need to modify some API calls related to comments. Please note the following changes:
-
The new
<yt:googlePlusUserId>
tag indicates that a comment feed entry represents a comment submitted through YouTube's new commenting system. The system, which is powered by Google+, supports threading for comments that are made through the system. When this new tag is present, you can retrieve replies to the comment using the Google+ API'scomments:list
method. See the article that explains changes to comments in the API for more details. -
The API no longer supports the ability to add a comment as a reply to an existing comment, though it does still support the ability to add a comment to a video.
-
The API no longer identifies comments that were originally submitted as replies to other comments. Comments that were submitted as replies to other comments now appear as regular comments in an API feed.
Please review the upcoming changes to comments for a complete explanation of the changes.
-
September 12, 2013
This update contains the following changes:
-
All standard video feeds except the
most_popular
feed have been deprecated. In response to requests for other feeds, the API will return themost_popular
feed with a defaulttime
parameter value oftoday
. Themost_popular
feed also supports atime
parameter value ofall_time
, so if you try to retrieve a deprecated feed for that time period, the API will return a feed of the most popular videos of all time. In addition, if your request for another feed specifies a region or category, the API will return themost_popular
feed for that region or category. -
YouTube's video responses feature has been retired as explained in this announcement.
May 10, 2013
This update contains the following changes:
-
YouTube no longer identifies experimental API features and services. Instead, we now provide a list of YouTube APIs that are subject to the deprecation policy.
April 15, 2013
This update contains the following changes:
-
The
location-radius
parameters have both been updated to reflect the fact that they are temporarily disabled. See the API issue tracker for more information about the status of both parameters. -
The definition of the
<yt:statistics>
tag'sviewCount
attribute has been updated to note that the attribute has been deprecated when the tag refers to a user profile (channel).The tag's
lastWebAccess
attribute, which had previously indicated the most recent time that a particular user used YouTube, has also been deprecated. That attribute will always contain a value of1970-01-01T00:00:00.000Z
. -
The
<yt:schedule>
tag's newbroadcaster
attribute identifies the network that broadcasts the show at the time that the tag specifies. This data may not be available for all shows. -
The
hint
parameter has been deprecated. The parameter had been used to retrieve a list of suggested YouTube channel names based on a user-provided hint. A new flow for upgrading unlinked Google Accounts makes this parameter unnecessary.
September 20, 2012
This update contains the following changes:
-
The new
<yt:contentType>
tag appears in a channel suggestions feed entry and identifies the type of resource that the entry describes. -
The
<entry>
element's definition has been updated to list the elements included in a show feed entry. The<yt:schedule>
element's definition has also been updated to indicate that it is a repeatable element in a show feed entry.
September 19, 2012
This update contains the following changes:
-
The definition of the
time
parameter has been updated to note that the only supported parameter values in requests for themost_popular
standard feed aretoday
andall_time
. -
The
<media:thumbnail>
tag definition has been updated to list new image sizes that may be included in show feed entries. With the new image sizes, a show entry can now include three sizes (150x150, 300x300, and 600x600) of a show's square artwork and two sizes (72x128 and 243x432) of a 16:9 image for the show. -
As noted on the YouTube API blog, video tags (also known as keywords) are no longer displayed to viewers of a video on YouTube's website. However, the owner of the video can still create tags for new videos and edit tags for existing videos, and video tags still provide an important signal for identifying relevant results to search queries.
With this in mind, API responses have also been modified so that a video entry does not identify the video's keywords unless the API request was authorized by that video's owner. If the video request was not authorized or was authorized by another user other than the video owner, the
<media:keywords>
element will be empty. Similarly, a video will only contain<category>
tags that identify the video's keywords if the request was authorized by the video's owner. The definitions of both of those tags have been updated accordingly.Important: If your application lets video owners update metadata for their videos, please ensure that you include the proper
Authorization
header for both read and write operations. If you don't use the properAuthorization
header to retrieve a video entry, you could accidentally return an empty list of video tags when retrieving an existing video and then overwrite the video's actual tags if you update the metadata. -
The
<media:keywords>
tag's definition has also been updated to reflect the fact that users are no longer required to specify at least one keyword when uploading a video.
September 12, 2012
This update contains the following changes:
-
The new
<yt:schedule>
tag may be included in show feed entries. The tag contains information about the show's broadcast schedule. -
The
<media:license>
tag's definition has been updated to reflect the fact that you can set the license for a video at upload time or you can update it later on.
August 23, 2012
This update contains the following changes:
-
The User's subscriptions feed section has been updated to explain that a subscription feed entry contains a
<yt:channelId>
tag, which identifies the channel associated with the subscription, and a<yt:username>
tag, which identifies the display name for the user or channel associated with the subscription. -
The
orderby
parameter now supports a value ofreversedPosition
for playlists, including watch later feeds, which are a type of playlist. -
The new
<yt:groupId>
tag identifies user events in an activity feed that are associated with the same user and resource. For example, if a user rates a video and marks the same video as a favorite, the entries for those events would have the same<yt:groupId>
value in the user's activity feed. In your user interface, you can avoid repetition by grouping events with the same<yt:groupId>
value. -
The new
<yt:unreadCount>
tag shows the amount of activity for the subscribed-to channel since the last time the user was logged in and filtered to that channel via the YouTube channel guide. The guide displays on the YouTube home page.
August 10, 2012
This update contains the following changes:
-
The standard video feeds section has been updated to reflect the fact that the deprecated
most_viewed
feed will now return the same content as themost_popular
feed. We recommend that you update your code to use themost_popular
feed instead of themost_viewed
feed.
August 1, 2012
This update contains the following changes:
-
The API now supports region-specific standard video feeds for Belgium (country code
BE
), Chile (CL
), Colombia (CO
), Egypt (EG
), Chile (CL
), Jordan (JO
), Malaysia (MY
), Morocco (MA
), Peru (PE
), Philippines (PH
), Saudi Arabia (SA
), Singapore (SG
), and the United Arab Emirates (AE
).
July 23, 2012
This update contains the following changes:
-
Channel search result entries now contain three additional tags:
-
The new
<yt:channelId>
tag appears in channel search result entries and contains a value that uniquely identifies the channel. -
The
<yt:channelStatistics>
tag specifies the channel's subscriber count and total view count. -
The
<media:thumbnail>
tag contains a thumbnail image for the channel.
-
-
The
most_viewed
standard video feed has been deprecated. We recommend that you use themost_popular
feed instead.Queries for the
most_viewed
feed may return an empty feed, and if the API does return a feed, the entries may not actually represent the most frequently viewed videos.
July 19, 2012
This update contains the following changes:
-
The
<yt:option>
tag appears in the newly supported branding options feed. Each<yt:option>
identifies a single branding setting and its value for the specified channel.
July 18, 2012
This update contains the following changes:
-
The documentation contains several changes to reflect the API's newly added support for retrieving information about lectures (videos), courses, and subjects that are accessible through YouTube EDU. Note that the YouTube EDU feeds are currently available as an experimental feature.
-
Parameter changes
-
XML element changes
-
In course and lecture feeds and entries,
<category>
and<media:category>
tags will identify any YouTube EDU categories associated with a course or lecture. -
The
<media:credit>
tag may now identify the lecturer for a course or lecture accessible via YouTube EDU. In that case, the tag'sscheme
attribute value will beurn:youtube
, and itsrole
attribute value will belecturer
. Previously, the only supported role for theurn:youtube
scheme wasuploader
. With this in mind, note that your code should not assume the value of the tag'srole
parameter based on the value of itsscheme
parameter. -
The new
<yt:material>
tag identifies additional or related material for a course or lecture. For example, it could identify lecture notes, sample exams, or supplemental reading.
-
-
-
Feed entries for movies and shows may now contain the following elements:
- The
<yt:audioTracks>
tag lists languages in which an audio track is available for the video content. - The
<yt:captionTracks>
tag lists languages in which captions are available for the video content.
- The
-
The definition of the
<media:rating>
tag'sscheme
attribute has been updated to reflect the fact that YouTube may return ratings for a number of additional country-specific rating systems. That definition also identifies the possible values for each rating scheme.
June 5, 2012
This update contains the following changes:
-
The definition of the
restriction
parameter now explains that the parameter enables the API server to identify the end user's location and apply geographic restrictions based on that location. The definition also notes that a failure to set this parameter's value could cause the API server to apply country restrictions incorrectly by, for example, basing restrictions on the location of your server rather than on the end user's actual location. Finally, the definition points out that YouTube API Terms of Service prohibit lying about an end user's location to circumvent these restrictions.
April 27, 2012
This update contains the following changes:
-
The API now supports region-specific standard video feeds for Hungary (country code
HU
). -
The user contacts feed section has been updated to reflect the fact that a user can only retrieve her own contacts feed and must be logged in to do so.
-
The new
<yt:favoriteId>
tag appears in favorite video entries and uniquely identifies the favorite video. -
The new
<yt:uploaderId>
tag, which is a child of the<media:group>
tag, uniquely identifies the user who uploaded a video. -
The definitions of the
<yt:username>
tag'sdisplay
attribute and the<media:credit>
tag'syt:display
attribute have both been updated to note that the attribute values are non-unique values that are intended for display as usernames.
April 19, 2012
This update contains the following changes:
-
These changes relate to the way that API requests and responses specify user IDs and user display names:
-
The new
yt:userId
tag contains a unique identifier for a user. The tag's value is not intended for display. -
The
<yt:username>
tag's newdisplay
attribute contains a meaningful, but non-unique, display value that can be used for a user.- For a YouTube account that is connected to a Google+ profile, the
display
value will be set to the user's full public display name. - For accounts that are not connected to Google+, the
display
value will be set to the YouTube account name.
- For a YouTube account that is connected to a Google+ profile, the
The
<media:credit>
tag also has a newyt:display
attribute that contains the same information. -
-
The
<media:thumbnail>
tag has been updated to reflect the fact that a new image type may now be returned in API responses. Themqdefault
image is 320 pixels wide and 180 pixels high (16:9).The tag's definition also now notes that your application should not make any assumptions about the order in which thumbnail images will be listed in API responses. Instead, your code should check the value of each
<media:thumbnail>
tag'syt:name
attribute to select the most appropriate image to display.
March 16, 2012
This update contains the following changes:
-
The new
hl
query parameter is now supported for retrieving movie charts. The parameter's value is an ISO 639-1 two-letter language code.
March 14, 2012
This update contains a few changes that reflect the fact that the API now supports feeds for shows and seasons:
-
The query parameter definitions section also now mentions that the
region
andgenre
parameters can be used to retrieve show charts. Thegenre
parameter is new and specifies the genre of shows in the feed. -
The new
<yt:season>
tag appears in season feed entries and identifies the season number for the corresponding season of a show. -
The
<media:thumbnail>
tag'syt:name
attribute may now contain a value ofposter
for shows in addition to movies. Show posters are 128px wide and 72px high. (Movie posters are 169px wide and 243px high.) Theyt:name
attribute may also contain a value ofmarket
, which refers to a 150x150px image for shows.
February 23, 2012
This update contains the following changes:
-
The
<yt:channelStatistics>
tag's new subscriberCount attribute specifies the number of users who have subscribed to the channel.
February 2, 2012
This update contains the following changes:
-
The definition of the
<yt:accessControl>
tag's action attribute has been updated to better explain the different settings of the list control. Specifically, the definition now explains what an unlisted video is and also notes that if you upload a video as an unlisted video and later update this control to allow the video to be listed in search results, then there may be a significant delay between the time that you update the control and the time that the video begins to appear in search results. -
The new
<yt:maxUploadDuration>
tag identifies the duration limit for uploaded videos from a particular user account.
December 14, 2011
This update contains the following changes:
-
The definition of the
<media:thumbnail>
tag has been updated to explain that the times given for the thumbnail images that haveyt:name
attribute values ofstart
,middle
, andend
do not necessarily reflect the times when those frames actually appear in the video. In addition, the relative ordering of thumbnails implied by theyt:name
values may also not be accurate. -
The list of languages and locales for which we have localized category lists has been updated to include Afrikaans (
af-ZA
), Amharic (am-ET
), Arabic (ar-EG
), Basque (eu-ES
), Bengali (bn-BD
), Bulgarian (bg-BG
), Catalan (ca-ES
), Croatian (hr-HR
), Danish (da-DK
), Estonian (et-EE
), Filipino (fil-PH
), Finnish (fi-FI
), Galician (gl-ES
), Greek (el-GR
), Hebrew (iw-IL
), Hindi (hi-IN
), Hungarian (hu-HU
), Icelandic (is-IS
), Indonesian (id-ID
), Latvian (lv-LV
), Lithuanian (lt-LT
), Malay (ms-MY
), Marathi (mr-IN
), Norwegian (nb-NO
), Persian (fa-IR
), Romanian (ro-RO
), Serbian (sr-RS
), Slovak (sk-SK
), Slovenian (sl-SI
), Swahili (sw-TZ
), Tamil (ta-IN
), Thai (th-TH
), Ukrainian (uk-UA
), Urdu (ur-PK
), Vietnamese (vi-VN
), and Zulu (zu-ZA
).
December 9, 2011
This update contains the following changes:
-
The guide now includes new and updated definitions for a number of tags that are used to create, update, or delete live events. Notably, the definitions of the
<content>
and<media:content>
tags have been updated, and new definitions have been added for the<yt:archived>
and<yt:cdn>
tags. -
The new
<media:price>
tag contains information about a particular offer for an item. An item can contain multiple<media:price>
tags, each containing a different offer. For example, a video rental might be available in different formats (standard vs. HD) for different prices.
November 30, 2011
This update contains the following changes:
-
The new
hint
parameter can be used to retrieve a list of available YouTube usernames similar to the parameter value. You would use this parameter if your application enabled a user with an unlinked Google Accounts to upgrade her account so that it would be associated with a YouTube username (and channel). -
The definition of the
<yt:username>
tag has been updated to explain that in a request to upgrade an unlinked Google Account to be associated with a YouTube username (and channel), that tag specifies the YouTube username that the user would like to have.
November 17, 2011
This update contains the following changes:
-
The
<yt:duration>
tag is now included in a playlist entry, where it specifies the total duration, in seconds, of all of the playlist's videos.
October 13, 2011
This update contains the following changes:
-
Video feed entries may now contain any of the following tags:
-
<yt:hd>
– This tag indicates that the video is HD content, meaning it is available for playback in at least 720p. -
<yt:threed>
– This tag indicates that the video is 3D content. Itssource
attribute identifies the reason that the video is labeled as containing 3D content. -
<media:license>
– This tag identifies the license that the video uploader chose for the video (or that was automatically associated with the video). Valid values arecc
andyoutube
.
-
October 7, 2011
This update contains the following changes:
-
The definition of the
<entry>
tag has been updated to list that tag's child elements in a user profile entry for a YouTube user with an unlinked Google Account. The API versioning section of the Developer's Guide explains the difference between YouTube accounts and unlinked Google Accounts.
October 6, 2011
This update contains the following changes:
-
The API query parameters section includes the following new parameters:
- The
duration
parameter lets you filter search results based on video length. - The
hd
parameter lets you restrict a search to only include HD videos, meaning videos that are available for playback in at least 720p. - The
license
parameter lets you filter search results to only include videos with a particular license.
- The
-
The
3d
parameter's definition has been updated to note thattrue
is the only supported parameter value and thatfalse
is not a valid parameter value. The API's default behavior, which occurs when the3d
parameter is omitted from a search request, is to include both 3D and non-3D videos in search results. -
The
format
parameter's definition has been updated to explain that the parameter value lets you specify multiple, comma-separated formats. The API will return videos available in at least one of the specified formats. For example,format=1,5
indicates that the API should return videos that are available in at least one of those two formats.
September 15, 2011
This update contains the following changes:
-
The definition of the
<yt:accessControl>
tag has been updated to note that access control settings are set by the video uploader. However, if a user has uploaded content, such as a music video, that is owned by another user, then the actual content owner may override the access control settings that the uploader provided. Known exceptions are listed in the tag definition.
August 2, 2011
This update contains the following changes:
-
The Paging through results section has two new subsections:
-
The Limits on result counts and accessible results section explains that the maximum value of the
<openSearch:totalResults>
tag is 1,000,000. This section also explains that you cannot retrieve greater than 1,000 results for a search query. -
The Pagination and total result counts section emphasizes that the total count expressed in the
<openSearch:totalResults>
tag represents an approximation of the number of total results rather than the exact count of results and that your application should not rely on the accuracy of the tag's value. The tag's definition already stated that the number is an approximation and not an exact count. Since the number is an approximation, you may see the total number of results change as you navigate through the result set.
-
July 21, 2011
This update contains the following changes:
-
The new
3d
parameter lets you restrict a search to only retrieve 3D videos. You can restrict a search to only retrieve 3D videos by setting the parameter value totrue
or by including the parameter in a request without specifying a parameter value. The parameter is also supported for related videos feeds and standard feeds.
July 19, 2011
This update contains the following changes:
-
The User's contacts feed section and the
<category>
tag definition have been updated to reflect the fact that contact groups have been deprecated on the YouTube website. Previously, an API request could contain a<category>
element, which could add a contact to a group, such as "Family" or "Friends." Now, if an API request uses a<category>
tag to specify a contact group, that tag will be ignored when the request is handled.
June 24, 2011
This update contains the following changes:
-
The API query parameters section has been updated to list five new parameters that can be used when retrieving live event feeds:
starts-before
,starts-after
,ends-before
,ends-after
, andstatus
. In addition, theinline
andtime
parameter definitions have been updated to explain how to use those parameters when retrieving live event feeds.Note: Live event feeds are experimental API features, which mean they may change unexpectedly.
-
The
<yt:status>
tag's definition has been updated to reflect the fact that the tag is included in live event feed entries. In a live event feed entry, the tag's possible values arepending
,active
,completed
,delayed
,cancelled
andrejected
. -
The new
<yt:when>
tag appears in live event feed entries. The tag specifies the time that an event started or is scheduled to start. If an end time is available, the tag specifies that time as well.
June 17, 2011
This update contains the following changes:
-
The API documentation has been updated to reflect the fact that the API supports HTTPS for nearly all API requests. If you send an API request to
https://gdata.youtube.com
, then the API response will also specify HTTPS URLs in element values that point to other API feeds.However, please note that HTTPS is not supported for the following requests:
- Requests to upload videos to the production API servers should still be sent to
http://uploads.gdata.youtube.com
. - Requests to upload videos to the staging server should still be sent to
http://uploads.stage.gdata.youtube.com
. - All other API requests to the staging server should still be sent to
http://stage.gdata.youtube.com
.
In addition, note that AuthSub and OAuth authorization tokens for the
http://gdata.youtube.com
andhttps://gdata.youtube.com
scopes are interchangeable. As such, if you have already obtained an AuthSub or OAuth token for thehttp://gdata.youtube.com
scope, you can use that same token to authorize requests tohttps://gdata.youtube.com
. - Requests to upload videos to the production API servers should still be sent to
June 10, 2011
This update contains the following changes:
-
The API supports several new query parameters, which are used for movie charts:
- The
movie-genre
parameter filters a chart to only include movies that are in a particular genre. - The
paid-content
parameter filters a chart to only include either paid content or free content. If the parameter is not set, a chart can include both paid and free content. - The
region
parameter filters a chart to only include movies that are viewable in a particular territory. The parameter value is an ISO 3166-1 alpha-2 code that identifies the country where videos must be viewable to be included in search results.
- The
-
Video entries now include enhanced metadata for videos that are movies, movie trailers, television show episodes or television clips provided by a YouTube partner. The
<yt:availability>
,<yt:episode>
, and<yt:firstReleased>
tags are all new tags that provide metadata for movies and television shows. The<media:category>
,<media:credit>
, and<media:rating>
tag definitions have also been updated. -
The
<media:thumbnail>
tag'syt:name
attribute may now contain a value ofposter
, which indicates that the associated thumbnail image is the poster art for a movie.
April 14, 2011
This update contains the following changes:
-
The
<gd:rating>
tag has been deprecated. Please use the<yt:rating>
tag instead.
February 28, 2011
This update contains the following changes:
-
The API now lets you retrieve two new standard feeds, both of which are available as experimental features:
- The
most_shared
feed lists the YouTube videos most frequently shared on Facebook and Twitter. - The
on_the_web
feed lists trending videos as seen on YouTube Trends, which surfaces popular videos as their popularity is increasing and also analyzes broader trends developing within the YouTube community.
- The
-
The
watch_on_mobile
feed has been removed from the list of supported standard feeds. -
The definition of the
fmt
parameter, which is used to specify the return format for a caption track retrieved via the API, has been updated. Previously, this parameter was required if you were retrieving a caption track generated using automatic speech recognition (ASR). Now, if you retrieve a track generated using ASR and do not set afmt
parameter value, the API will return the track in Subviewer-compatible format.
January 31, 2011
This update contains the following changes:
-
The Expected latency for data updates and Standard feeds sections have been updated to more accurately describe the frequency with which standard feeds are updated.
-
The
<media:thumbnail>
tag's newyt:name
attribute specifies a name that identifies a thumbnail image. For example, the<media:thumbnail>
tag that identifies the high-quality thumbnail image for a video will have ayt:name
value ofhqdefault
, providing a reliable mechanism for distinguishing between thumbnail images for a video. (Previously, the high-quality image could only be identified as the one that did not specify a timestamp.)
December 14, 2010
This update contains the following changes:
-
The default API version used on the staging server is now version
2
. The Developer's Guide discusses and explains how to use the staging server. -
The
caption
parameter's definition has been updated to note that you can restrict a search result set to only include videos that do not have caption tracks by setting the parameter value tofalse
. (To restrict a result set to only include videos that have caption tracks, set thecaption
parameter value totrue
or include thecaption
parameter in your request but do not specify a parameter value.) -
The new
<yt:spam>
tag can appear in a comment feed entry. The tag's presence indicates that the comment has been flagged as spam. -
The list of supported languages for localized category lists has been updated to include
zh-CN
(Simplified Chinese) andpt-PT
(Portuguese).
October 28, 2010
This update contains the following changes:
-
The
time
parameter's definition has been updated to note that the parameter can be used when retrieving standard channel feeds. (The API does not generate a feed of the most subscribed channels for the previous day, so the only supportedtime
parameter values for that feed arethis_week
,this_month
, andall_time
. -
The new
<yt:channelStatistics>
appears in standard channel feeds and specifies statistics like the number of videos uploaded to a channel and the total number of views for all of the videos in the channel.Note: Standard channel feeds are only supported in version
2
of the API.
October 26, 2010
This update contains the following changes:
-
The Retrieving region-specific standard video feeds section has been updated to note that region-specific feeds are now supported for Argentina (
AR
) and South Africa (ZA
).
October 20, 2010
This update contains the following changes:
-
The Projection values section has been updated to better explain what a projection is and, specifically, why the
mobile
projection is available. The section now explains that using themobile
projection does not ensure that an API response will only contain videos suitable for playback on mobile devices. The section does, however, explain how to only retrieve videos suitable for mobile playback.
September 16, 2010
This update contains the following changes:
-
The new
<yt:derived>
tag appears in a caption track feed entry with the valuespeechRecognition
if YouTube generated the caption track using automatic speech recognition (ASR). -
The
fmt
parameter definition has been updated to note that you must specify a value for that parameter if you are retrieving a caption track generated using ASR.
September 2, 2010
This update contains the following changes:
-
The document has been updated to reflect the fact that YouTube no longer supports subscriptions to playlists.
August 31, 2010
This update contains the following changes:
-
The new
fields-language
query parameter affects the way that the API determines whether to return the text content for a tag in a partial API response. The release notes for August 25, 2010, explain the changes to the syntax rules. -
The new
fmt
andlang
query parameters can be used when retrieving caption tracks:-
The
fmt
parameter lets you retrieve a caption track in a format other than the one that you originally uploaded. -
The
lang
lets you specify the language into which you would like the caption track returned in the API response to be translated.
See the Providing captions for a video section of the Developer's Guide for more information.
-
-
The
<yt:statistics>
tag's newtotalUploadViews
attribute specifies the total number of views for all of a user's videos. This attribute is only specified when the<yt:statistics>
tag appears within a user profile entry.
July 13, 2010
This update contains the following changes:
-
The yt:accessControl tag definition has been updated to reflect a new setting that indicates whether a video is unlisted. Unlisted videos are not included in search results or displayed in any other way, and a user can only reach an unlisted video by entering or linking directly to the video's watch page URL.
June 24, 2010
This update contains the following changes:
-
The Contacts section has been updated. Previously, this section stated that you do not need to submit an authenticated request to retrieve a user's contact list. While this statement is true, the API will only return the contact list for users who display the Friends module on their channel pages. If you submit an unauthenticated request to retrieve the contacts list for a user who does not display the Friends module on his channel page, the API will return a 403 (Forbidden) HTTP response.
- The Subscriptions section has been updated to reflect the fact that YouTube no longer supports subscriptions to a user's list of favorite videos or to a keyword search. XML tag definitions have also been updated to reflect this change.
May 12, 2010
This update contains the following changes:
-
The metadata requirements for newly uploaded videos have changed so that the only required fields for a new video are category and title.
In addition, you can include the new
<yt:incomplete>
element in your upload request to instruct YouTube to automatically generate certain metadata values if they are not otherwise specified in the upload request. If your request includes the<yt:incomplete>
element, YouTube will automatically generate a title for the video and associate the video with a category even if that information is not included in the video metadata. See the new Metadata requirements section for uploaded videos for more information.Finally, you can upload videos using the resumable uploading process and upload videos without any metadata. In such cases, YouTube will handle the request as if it contained an entry that only included a
<yt:incomplete>
element. -
The new
inline
query parameter lets you specify that an activity feed entries for events that involve videos, such asvideo_rated
andvideo_uploaded
events, should include an embedded video entry that contains information about that video. The default parameter value isfalse
. See the Using the inline parameter section for more details. -
The API changes announced on April 12, 2010, that support YouTube's new video rating system have been released to our production API servers.
April 12, 2010
This update contains the following changes:
-
The new
<yt:rating>
element provides rating information for the new video rating system released on YouTube in March 2010. In the new system, users rate a video by indicating whether they like it or dislike it. (In the old rating system, users rated a video on a 1-5 scale.)Note: The API changes that support the new rating system are currently released to our staging server but have not yet been released to our production API servers. As such, you should not yet update production applications to either require API responses to contain the
<yt:rating>
element or to submit ratings using that element. However, you can test the new functionality on the staging server and then update your applications once the feature is released to the API production servers.
March 22, 2010
This update contains the following changes:
-
The new Retrieving a partial response section of the Developer's Guide explains how to submit an API request in which you specify the fields that you want to be included in the API response. By only requesting the information that it will actually display, your application can more efficiently use network, CPU and memory resources. The new section explains how to use the fields parameter, which is also documented in this guide, to submit requests for partial feeds and also describes the format of the API responses to those requests.
-
The following XML element definitions have been updated to reflect minimum- and maximum-length restrictions:
- The <media:keywords> element value has a maximum length of 500 bytes, not 120 characters as previously reported. In addition, a keyword may not be longer than 30 bytes. Previously, a single keyword could not be longer than 25 characters. The element definition has also been updated to explain that when the API server calculates the length of a multi-word keyword, it counts spaces as well as quotes, which are inferred to surround any multi-word keyword.
- The <media:description> element's value has a maximum length of 5000 bytes. Previously, the documentation stated the maximum length was 5000 characters.
- The <media:title> element's value has a maximum length of 100 bytes. Previously, the documentation stated the maximum length was 60 characters or 100 bytes, whichever occurred first.
-
The key query parameter definition has been updated to correctly reflect that the key should uniquely identify a product submitting an API request.
-
The use of client IDs has been deprecated. As such, the X-GData-Client request header and the client request parameter have been deprecated. Examples throughout the documentation have also been updated to no longer provide client ID information. We will continue to support requests that submit client IDs in accordance with the deprecation policy explained in our Terms of Service.
February 17, 2010
This update contains the following changes:
-
The new
<yt:accessControl>
element identifies access control settings for a video. A user who is uploading or updating a video can also set (or update) the access control settings for that video.Access controls specify whether users are allowed to rate a video, add comments about the video, rate comments about the video, add a video response to the video, or embed the video on third-party websites. Another setting indicates whether YouTube can show the video on Youtube properties other than the YouTube.com website.
As a result of the new support for access controls, the
<yt:noembed>
element has been deprecated. However, requests to update a video that include this element will still be handled properly in accordance with the deprecation policy explained in our Terms of Service.
January 29, 2010
This update contains the following changes:
-
The YouTube API now supports JSON-C as a response format. The Developer's Guide for JSON-C/JavaScript explains the format of the JSON-C feeds and how to request and process those feeds. The API currently supports JSON-C responses for the following types of feeds:
- Video feeds . This category includes video search results, related videos, user uploads and video responses.
- Playlist feeds . This category includes playlist search results, feeds that list all of a user's playlists, and feeds that list the entries in a single playlist.
- Favorite video feeds . This category includes feeds that list a user's favorite videos.
-
The orderby parameter now supports a range of values for playlist feeds, allowing you to order playlist entries by playlist position, number of comments, duration, date added to playlist, title, or number of views.
-
Subscription feeds now contain user activity subscriptions. In a subscription entry, the <category> tag's term attribute can now have the value user, indicating that the entry is for a user activity subscription.
November 5, 2009
This update contains the following changes:
-
The new caption parameter lets you restrict a search result set to only include videos that have caption tracks. The parameter is specified without a value, and its presence indicates that all videos in the result set must have captions.
-
The prettyprint parameter, which is a standard Google Data API parameter, is now documented for the YouTube Data API. This parameter, which was already supported, may be useful for testing and debugging your application.
-
The HTTP response codes for YouTube Data API requests section has been updated to note that the FILE_MISSING error code is no longer returned to identify a failed upload. As such, your application should require the user to select a file before allowing the user to submit the form to upload the video. Please see the instructions for uploading a video file for browser-based uploads.
August 31, 2009
This update contains the following changes:
-
The time parameter is now supported for search queries as well as for standard feeds.
-
The definition of the author parameter has been updated to explain how this parameter functions in a request for a standard feed.
-
The definition of the <yt:state> tag's reasonCode attribute has been updated to better describe the meaning of the limitedSyndication code for a restricted video.
-
The sortorder parameter, which had enabled comments to be sorted in ascending or descending order, has been deprecated.
-
The most_linked standard feed has been deprecated. Queries for this feed will now return an empty feed.
July 21, 2009
This document contains the following changes:
-
The lr parameter definition has been updated to explain how that parameter affects requests to retrieve caption tracks for a video.
-
The link tag definition now explains the new yt:hasEntries attribute, which indicates whether there are caption tracks associated with a video entry. This attribute is only included in link tags for which the rel attribute value is http://gdata.youtube.com/schemas/2007#video.captionTracks. A value of true indicates that caption tracks are available for the video.
June 25, 2009
This document contains the following changes:
-
The new <yt:aspectratio> tag could be included in a video entry to identify the video's aspect ratio. The only valid value for this tag is currently widescreen, which indicates that the video has a 16:9 aspect ratio.
At the time of this documentation change, YouTube has recently begun to generate this tag, as appropriate, for newly uploaded videos. However, feed entries for older videos in the YouTube library may not include this tag even if those videos are widescreen. As such, the presence of this tag in a feed entry indicates that the video is a widescreen video, but the absence of the tag does not decisively indicate that the video is not a widescreen video.
-
The <app:control> tag definition has been updated to reflect the fact that that tag now appears within entries for any unpublished videos. For example, the tag could appear in playlist entries if the video was deleted or if the owner made the video private.
-
The definition of the <yt:state> tag's reasonCode attribute has been updated to reflect the introduction of two new codes for restricted videos:
-
If the attribute value is limitedSyndication, then the video is not and will not be available to play on mobile devices or other devices.
- If a video entry contains a <yt:state> tag that specifies this code, then the video's owner has specified that the video should not be syndicated outside of the YouTube website.
- If a video entry does not contain either a <yt:state> tag with this code or a <media:content> tag that has a video object in the format needed for the user's device, then YouTube is still transcoding the video to be available in that format.
-
If the attribute value is private, then the video has been made a private video by the video owner and is therefore unavailable.
-
April 8, 2009
This document contains the following changes:
-
The <media:keywords> tag definition has been updated to note that keywords may now contain spaces, meaning an individual keyword may actually contain more than one word. Prior to this change, you could have entered keywords like
<media:keywords>winter, snowball, fight</media:keywords>
. As a result of this change, you could make "snowball fight" a single keyword (<media:keywords>winter, snowball fight</media:keywords>
). -
The Custom parameters for the YouTube Data API section has been updated to contain a list of parameters used to request any type of feed. The section also now lists parameters that are only used to request a particular type of feed, such as video search results, standard feeds, video feeds or comment feeds. Finally, the API parameter definitions have been updated to highlight cases where a parameter is only supported for search requests.
-
The restriction parameter definition has been updated to note that 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.
-
The definitions of the <yt:state> tag's name attribute has been updated to reflect the addition of restricted as a video status. In addition, the reasonCode attribute definition has been updated to note the possible reasonCode values for restricted videos.
March 10, 2009
This document contains the following changes:
-
The <media:description> tag definition has been updated to note that in API responses, the description is truncated to 500 characters unless one of the following conditions is true:
-
You submitted an authenticated request for a single video entry on behalf of the video owner. In this case, you submitted the API request to the following URL:
http://gdata.youtube.com/feeds/api/users/default/uploads/VIDEO_ID
-
You submitted an authenticated request for the currently authenticated user's uploaded videos and your request did not specify search parameters other than start-index or max-results. In this case, you submitted the API request to the following URL:
http://gdata.youtube.com/feeds/api/users/default/uploads
-
February 24, 2009
This document contains the following changes:
-
The Expected latency for data updates section has been updated to note the expected delay before an event appears in an activity feed.
-
The definition of the author parameter has been updated to explain how the parameter is used in a request to retrieve a user activity feed.
-
The definitions of the <yt:username> and <yt:videoid> tags have been updated to explain how those tags are used in activity feeds.
January 27, 2009
This document contains the following changes:
-
The definition of the <media:thumbnail> tag has been updated to provide more detailed information about the high-quality thumbnail image that is returned in a feed entry that identifies a video. The <media:thumbnail> tag does not specify a timestamp for the high-quality thumbnail image, which enables you to distinguish the high-quality thumbnail from the other thumbnail images. In addition, the high-quality thumbnail image may be larger than the other thumbnails returned for a video.
-
The definitions of the <code> and <domain> tags have been updated to include information about service errors. Service errors were documented in the Developer's Guide in July 2008, so this update does not reflect a change in functionality.
January 13, 2009
This document contains the following changes:
-
The new <yt:uploaded> tag, which appears in a playlist feed entry, specifies the time that the entry was added to the playlist.
-
The <media:title> tag definition has been updated to note that the tag has a maximum length of 60 characters or 100 bytes, whichever is reached first. Previously, the tag stated a maximum length of 60 characters.
December 10, 2008
This document contains the following changes:
-
The new <yt:playlistId> and <yt:playlistTitle> tags are both associated with playlist subscriptions, which are now described in the developer's guide.
-
The <category> tag definition has been updated to note additional valid values for the tag's scheme and term attributes. These new, valid values are associated with two new features, friend activity feeds and playlist subscriptions.
-
The Retrieving region-specific standard feeds section has been updated to note that region-specific standard feeds are now available for the Czech Republic, India, Israel and Sweden.
-
The Localized category lists section has been updated to note the availability of category lists for Czech and Swedish. In addition, the following localized category lists have been retired:
- The list for Canada (
hl=en-CA
) has been retired. Please use the U.S. list (hl=en-US
) as an alternative. - The lists for Ireland (
hl=en-IE
, Australia (hl=en-AU
) and New Zealand (hl=en-NZ
) have been retired. Please use the Great Britain list (en-GB
) as an alternative. - The Chinese list for Hong Kong (
hl=zh-HK
) has been retired. Please use the list for traditional Chinese (hl=zh-TW
) as an alternative.
- The list for Canada (
November 13, 2008
This document contains the following changes:
The new Paging through results section explains how the API uses
<link>
tags to specify links to the previous and/or next pages of entries in an API response feed.
October 20, 2008
This update contains changes associated with the release of version 2 of the YouTube Data API. YouTube still supports API version 1. (See documentation for API version 1).
-
The values of <id> tags in feed entries no longer specify a URI. In API version 2, the <id> tag value is a URN in a format like tag:youtube,2008:videos or tag:youtube,2008:video:24Ryj1ywoqw or tag:youtube,2008:favorite:24Ryj1ywoqwji5_MqicxSo.
-
The Projection values section has been updated to note that all API requests must specify a projection. Prior to the release of API version 2, API requests did not need to specify a projection. Since the YouTube Data API documentation has always specified a projection for each sample request, none of the sample requests required an update due to this particular change.
-
The Navigating between feeds section has been updated to reflect the fact that the <link>, <content> and <gd:feedLink> tags are all used to navigate between feeds.
-
The following API parameters have been added or updated:
- The new v parameter can be used to specify the API version that YouTube will use to handle the API request.
- The new safeSearch parameter indicates whether YouTube should include restricted content as well as standard content. The safeSearch parameter replaces the racy parameter, which has been deprecated with this API release.
- The location parameter definition now explains how that parameter, in conjunction with the new location-radius parameter, can be used to request videos associated with a particular geographic area.
- The new strict parameter can be used to instruct YouTube to reject API requests that contain invalid request parameters.
- The new uploader parameter can be used to restrict search results to only contain partner videos.
- The name of the vq parameter has changed to q.
-
API responses specify that they use OpenSearch version 1.1, which has a different URI than OpenSearch version 1.0, which was used in previous API releases.
-
The <summary> tag is a new tag that replaces the <yt:description> tag, which has been deprecated with this API release.
-
The <content> tag has replaced the <gd:feedLink> tag in playlists feeds and subscriptions feeds.
-
The new <yt:videoid> tag appears in any feed entry that describes a video. The tag value specifies a unique ID that YouTube uses to identify that video.
-
The new <yt:countHint> tag, which appears in a playlists feed entry, identifies the number of videos in the corresponding playlist.
-
The new <yt:aboutMe> tag appears in a user profile and contains whatever information the user has entered in the "About Me" field of the user's YouTube personal profile.
-
The type attribute has been removed from the <title> and <content> tags.
-
The <media:credit> tag is a new tag in playlist and inbox feed entries that identifies the YouTube user who uploaded a video. The <author> tag definition has been updated to reflect the fact that in playlist and inbox feed entries, the <author> tag does not identify the user who uploaded the video.
-
The <media:rating> tag definition has been updated to explain the newly added country parameter, which identifies the country or countries where a video is considered to contain restricted content. The tag's definition has also been updated to explain how the safeSearch parameter value in an API request affects the <media:rating> tag in the API response.
-
The <yt:state> tag definition has been updated to note video entries that contain that tag are not playable. In addition, the definition now indicates that playlist and inbox feed entries that link to deleted or claimed videos will now include the <yt:state> tag, which will have a name attribute value of deleted. In these cases, the <yt:state> tag is only visible to the feed owner.
-
The value of the <openSearch:totalResults> tag has been capped at
1,000,000
. -
The value of the <published> tag is now always specified in UTC rather than PST.
-
The new <app:edited> tag identifies the date and time when a resource was last updated.
-
The Category list for uploaded videos section has been updated to note that categories that are neither assignable nor browsable are deprecated and identified as such by the <yt:deprecated> tag.
-
The <yt:racy> element has been deprecated with this API release.
October 3, 2008
This update contains the following changes:
-
The new sortorder parameter, which is only valid for comments feeds, lets you specify whether the API will return comments in ascending order (oldest to newest) or descending order (newest to oldest).
-
The new <media:restriction> tag identifies the country or countries where a video may or may not be played. The tag only appears in a feed entry if the corresponding video cannot be played in all countries.
August 18, 2008
This update contains the following changes:
-
The new Retrieving category-specific standard feeds section explains how to retrieve standard feeds for particular categories, such as the top-rated comedies or most popular sports videos.
-
The Category list for uploaded videos section has been updated to explain the <yt:browsable> tag's new regions attribute, which identifies the countries where a category is browsable. Note that the Retrieving region-specific standard feeds section already includes a table that lists the countries for which YouTube supports localized feeds and the regionID associated with each country.
-
The category parameter now provides an alternate way to search for videos that are in certain categories or are tagged with particular keywords or developer tags. The examples in the Category search in video feeds section have all been updated to demonstrate how to use either the category parameter or the standard URL notation for searching by category, keyword or developer tag.
-
India (regionID = "IN") has been added to the list of countries for which the YouTube Data API supports localized feeds.
-
The new Spelling suggestions in API responses section explains how YouTube identifies alternate suggested spellings for search query terms.
-
The definition of the <yt:state> tag has been updated to note that video entries that contain that tag are not playable. This change clarifies existing functionality and does not reflect any API changes.
July 16, 2008
This document contains the following changes:
The Batch processing element reference section, which was added in this update, defines XML elements that support the API's batch processing functions.
The definition of the <media:rating> tag has been updated to explain the meanings of the different tag values. A tag value of 1 identifies content that is restricted in all countries. A tag value of 2 identifies content that is only restricted in Hong Kong, Korea and Taiwan.
The time parameter is now supported for the most_popular standard feed.
June 11, 2008
This document contains the following changes:
The Standard feeds section has been updated to reflect the addition of a new feed, which is for YouTube's most popular videos. The section also now includes a short description of each feed.
The list of custom parameters for the YouTube Data API has been updated to reflect the addition of the location query parameter. This parameter lets you request videos that have a geographic location specified in their metadata. You do not need to specify a parameter value for this parameter.
The <media:keywords> tag definition has been updated to note that all keywords must be at least two characters long.
May 6, 2008
The Category list for uploaded videos section has been updated to explain how to download category lists for specific languages and locales.
May 2, 2008
This update contains the following changes:
The vq and orderby parameter definitions have been updated to clarify that these parameters are only supported for API requests for video feeds. [Note: The name of the vq parameter changed to q with the release of version 2 of the YouTube Data API.] Playlist feeds do not support the orderby parameter because playlist feed entries are always ordered based on the position of each entry in the playlist.
-
The racy parameter definition has been updated to note that feed entries for videos that contain restricted content will contain the <media:rating> element.
-
The restriction parameter definition has been updated with a recommendation that you always include this parameter in API requests, setting the parameter value to the end user's IP address.
The <media:rating> tag, a new subtag of <media:group>, replaces the <yt:racy> tag as the standard way to identify videos that contain restricted content. In addition, the <yt:racy> tag definition has been updated to note that this tag has been deprecated. [Note: The definition of this tag was removed from the API's version 2 documentation.] Although the tag may still be included in API responses to ensure backward compatibility with legacy applications, your application should check for the presence of the <media:rating> tag to determine whether a video contains restricted content.
April 7, 2008
This document contains the following changes:
The newly added Revision History highlights important changes to this document. The revision history will not mention minor changes such as spelling corrections.
The API now supports the client parameter, which provides an alternate way of identifying your application. You can also use the X-GData-Client header to identify your application.
The definition of the <media:keywords> tag has been updated to note that in the tag value, individual keywords may be separated by spaces but may not contain spaces.