YouTube

Reference Guide: Data API Protocol

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

  1. Overview
  2. Projection values
  3. Feed Types
    1. Video feeds
      1. Videos feed
      2. Related videos feed
      3. Standard feeds
        1. Retrieving region-specific standard video feeds
        2. Retrieving category-specific standard video feeds
        3. Using the time parameter with standard feeds
      4. User's favorites feed
      5. Playlist feed
    2. User's playlists feed
    3. User's subscriptions feed
    4. Video comments feed
    5. User profile entry
    6. User's contacts feed
  4. Navigating between feeds
    1. Paging through results
  5. HTTP response codes for YouTube Data API requests
    1. Retrieving feeds
    2. Uploading a video
    3. Adding information via HTTP POST
    4. Updating information via HTTP PUT
    5. Deleting resources via HTTP DELETE
    6. Additional response codes for unsuccessful requests
  6. Searching for videos
    1. Query parameter definitions
      1. Standard Google Data API parameters
      2. Custom parameters for the YouTube Data API
    2. Category search in video feeds
    3. Spelling suggestions in API responses
  7. XML element definitions
    1. Atom elements reference
      1. author
      2. category
      3. content
      4. entry
      5. feed
      6. generator
      7. id
      8. link
      9. logo
      10. name
      11. published
      12. subtitle
      13. summary
      14. title
      15. updated
      16. uri
    2. OpenSearch elements reference
      1. openSearch:itemsPerPage
      2. openSearch:startIndex
      3. openSearch:totalResults
    3. YouTube elements reference
      1. yt:aboutMe
      2. yt:accessControl
      3. yt:age
      4. yt:archived
      5. yt:aspectratio
      6. yt:audioTracks
      7. yt:availability
      8. yt:books
      9. yt:captionTracks
      10. yt:cdn
      11. yt:channelId
      12. yt:channelStatistics
      13. yt:company
      14. yt:contentType
      15. yt:countHint
      16. yt:derived
      17. yt:duration
      18. yt:episode
      19. yt:favoriteId
      20. yt:firstName
      21. yt:firstReleased
      22. yt:gender
      23. yt:googlePlusUserId
      24. yt:groupId
      25. yt:hd
      26. yt:hobbies
      27. yt:hometown
      28. yt:incomplete
      29. yt:lastName
      30. yt:location
      31. yt:material
      32. yt:maxUploadDuration
      33. yt:movies
      34. yt:music
      35. yt:noembed
      36. yt:occupation
      37. yt:option
      38. yt:playlistId
      39. yt:position
      40. yt:private
      41. yt:rating
      42. yt:recorded
      43. yt:relationship
      44. yt:schedule
      45. yt:school
      46. yt:season
      47. yt:spam
      48. yt:state
      49. yt:statistics
      50. yt:status
      51. yt:threed
      52. yt:unreadCount
      53. yt:uploaded
      54. yt:uploaderId
      55. yt:userId
      56. yt:username
      57. yt:videoid
      58. yt:when
    4. Media RSS elements reference
      1. media:category
      2. media:content
      3. media:credit
      4. media:description
      5. media:group
      6. media:keywords
      7. media:license
      8. media:player
      9. media:price
      10. media:rating
      11. media:restriction
      12. media:thumbnail
      13. media:title
    5. GData elements reference
      1. gd:comments
      2. gd:feedLink
      3. gd:rating
    6. GeoRSS elements reference
      1. georss:where
    7. GML elements reference
      1. gml:Point
      2. gml:pos
    8. Atom Publishing Protocol element reference
      1. app:control
      2. app:draft
      3. app:edited
    9. Browser-based upload API response elements reference
      1. response
      2. token
      3. url
    10. Batch processing element reference
      1. batch:id
      2. batch:interrupted
      3. batch:operation
      4. batch:status
    11. Error response element reference
      1. code
      2. domain
      3. error
      4. errors
      5. location
  8. Appendixes
    1. Category list for uploaded videos
      1. Localized category lists
    2. URL escaping
  9. 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:


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

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:

Country Region ID
Argentina AR
Australia AU
Austria AT
Belgium BE
Brazil BR
Canada CA
Chile CL
Colombia CO
Czech Republic CZ
Egypt EG
France FR
Germany DE
Great Britain GB
Hong Kong HK
Hungary HU
India IN
Ireland IE
Israel IL
Italy IT
Japan JP
Country Region ID
Jordan JO
Malaysia MY
Mexico MX
Morocco MA
Netherlands NL
New Zealand NZ
Peru PE
Philippines PH
Poland PL
Russia RU
Saudi Arabia SA
Singapore SG
South Africa ZA
South Korea KR
Spain ES
Sweden SE
Switzerland CH
Taiwan TW
United Arab Emirates AE
United States US

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, the scheme attribute value will be http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. That tag's term 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 of previous.
  • If a feed contains a next page of results, the API response will contain a <link> tag with a rel attribute value of next.

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



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

Note: Following a testing period, the new syntax rules will apply to all requests for partial API responses, and the API server will ignore the fields-language parameter.
max-results The max-results parameter specifies the maximum number of results that should be included in the result set. This parameter works in conjunction with the start-index parameter to determine which results to return. For example, to request the second set of 10 results – i.e. results 11-20 – set the max-results parameter to 10 and the start-index parameter to 11. The default value of this parameter is 25, and the maximum value is 50. However, for displaying lists of videos, we recommend that you set the max-results parameter to 10.
prettyprint The prettyprint parameter lets you request an XML response formatted with indentations and line breaks. Set the parameter's value to true to have the response formatted as such. The default parameter value is false.
start-index The start-index parameter specifies the index of the first matching result that should be included in the result set. This parameter uses a one-based index, meaning the first result is 1, the second result is 2 and so forth. This parameter works in conjunction with the max-results parameter to determine which results to return. For example, to request the second set of 10 results – i.e. results 11-20 – set the start-index parameter to 11 and the max-results parameter to 10.
strict The strict parameter can be used to instruct YouTube to reject an API request if the request contains invalid request parameters. The default API behavior is to ignore invalid request parameters. If you want YouTube to reject API requests that contain invalid parameters, set the strict parameter value to true. For example, YouTube would reject the following request because "foo" is not a valid request parameter.
https://gdata.youtube.com/feeds/api/videos?foo=nonono&strict=true
v The v parameter specifies the version of the API that YouTube should use to handle the API request. Your request can specify the desired API version using either the v parameter or the GData-Version HTTP request header. All Google-provided client libraries always select a major API version. If your request does not specify an API version, YouTube will handle your request using API version 1. Please see the API versioning section for more information about specifying an API version.

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

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

Custom parameters for the YouTube Data API

In addition to the standard Google Data query parameters, the YouTube Data API defines the following API-specific query parameters:

Parameters for all API requests:
key

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

Additional parameters for all video feeds:
restriction

Additional parameters for caption track feeds:
fmt
lang

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

Additional parameters for show charts:
genre
region

Additional parameters for YouTube EDU feeds:
category
course

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

Additional parameters for username suggestion feeds:
hint

In general, parameters that are used for filtering and ordering results are only supported for search requests, though there are several exceptions listed above. The API also supports the time parameter for the most_popular standard video feed, the author parameter for user activity feeds, and the restriction parameter for video feeds. Please see the Testing and troubleshooting section for tips on how to filter API response feeds that do not support these parameters.

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

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

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

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

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

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

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

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

    https://gdata.youtube.com/feeds/api/videos?q=surfing&caption=false&v=2
    
Note: The API will return an HTTP 400 response if you specify the parameter with any value other than true or false.
category The category parameter has two uses:
  • In video search requests, it enables you to retrieve videos that are in a particular category or are tagged with a particular keyword or developer tag. You can also insert category names, keywords and developer tags into the request URL as described in the Category search in video feeds section. That section provides instructions for formatting the category parameter value for a variety of different types of queries.

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

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

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

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

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

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

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

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


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

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

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

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

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

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

    Set the parameter value to true to specify that video (or playlist) entries should be embedded in the event entries.
The default parameter value is false.
key The key parameter specifies your developer key, an alphanumeric string that uniquely identifies the application making an API request. You can also use the X-GData-Key request header to specify your developer key. Your application does not need to specify your developer key twice by using both the key parameter and the X-GData-Key request header, but it should provide your developer key using at least one of those two methods.
lang The lang parameter specifies the language into which you want a caption track to be translated. Set the parameter value to the ISO 639-1 two-letter language code that identifies the desired caption language.

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

The location parameter restricts the search to videos that have a geographical location specified in their metadata. The parameter can be used in either of the following contexts:

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

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

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

    The following examples show sample uses of this parameter:

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

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

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


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

The location-radius parameter, in conjunction with the location parameter, defines a geographic area. If the geographic coordinates associated with a video fall within that area, then the video may be included in search results.

The location-radius parameter value must be a floating point number followed by a measurement unit. Valid measurement units are m, km, ft and mi. For example, valid parameter values include "1500m", "5km", "10000ft" and "0.75mi". The API will return an error if the radius is greater than 1000 kilometers.

YouTube supports this parameter for video search requests.
lr In a video search request, the lr parameter restricts the search to videos that have a title, description or keywords in a specific language. This parameter can be used when requesting any video feeds other than standard feeds.

In a request to retrieve a list of the caption tracks available for a video, the lr parameter filters the list of caption tracks to only include the specified language.

Valid values for the lr parameter are ISO 639-1 two-letter language codes. You can also use the values zh-Hans for simplified Chinese and zh-Hant for traditional Chinese.
movie-genre The movie-genre parameter restricts a movie chart to only include movies in a particular genre. The parameter value is an integer that corresponds to a particular genre. The following values are valid:

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

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

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

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

q The q parameter specifies a search query term. YouTube will search all video metadata for videos matching the term. Video metadata includes titles, keywords, descriptions, authors' usernames, and categories.

Note that any spaces, quotes or other punctuation in the parameter value must be URL-escaped.

To search for an exact phrase, enclose the phrase in quotation marks. For example, to search for videos matching the phrase "spy plane", set the q parameter to %22spy+plane%22.

Your request can also use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several search terms. For example, to search for videos matching either "boating" or "sailing", set the q parameter to boating%7Csailing. (Note that the pipe character must be URL-escaped.) Similarly, to search for videos matching either "boating" or "sailing" but not "fishing", set the q parameter to boating&7Csailing+-fishing.
region The region parameter restricts a movie or show chart to only list content that is viewable in a specified region. If set, the parameter value must be an ISO 3166-1 alpha-2 country code. The default behavior is to return content that is viewable worldwide.

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

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

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

There are two ways to use this parameter:
  • To request videos playable from a specific IP address, include the restriction parameter in your request and set the parameter value to the IP address of the computer where the videos will be played – e.g. restriction=255.255.255.255.
  • To request videos that are playable in a specific country, include the restriction parameter in your request and set the parameter value to the ISO 3166 two-letter country code of the country where the videos will be played – e.g. restriction=DE.
You should include this parameter in any request to retrieve a list of videos, including search results, playlists, favorite videos, and so forth. If a video in the API response is not playable in the location that you're using to restrict availability of the content, the <entry> for that tag will not contain a <media:content> tag. However, it will contain a <yt:state> tag that indicates that the video is restricted.
safeSearch The safeSearch parameter indicates whether the search results should include restricted content as well as standard content. YouTube will determine whether content is restricted based on the user's IP address or location, which you specify in your API request using the restriction parameter. If you do request restricted content, then feed entries for videos that contain restricted content will contain the <media:rating> element.

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

Note: The safeSearch parameter was introduced in version 2 of the YouTube Data API and replaced the racy parameter, which was used in version 1.

YouTube supports this parameter for video search requests.
starts-after
Note: The API's functionality for retrieving live events has been deprecated as of March 4, 2014. This functionality is not subject to the API's deprecation policy. We recommend you transition your application to use the YouTube Data API (v3) to retrieve live events.

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

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

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

    This parameter is supported for the following feeds and charts:
    • most_popular standard video feed – This feed only supports the parameter values today and all_time.
    • Standard channel feeds
      • most_subscribed – This feed only supports the parameter values this_week, this_month, and all_time.
      • most_viewed
uploader The uploader parameter, which is only supported for search requests, lets you restrict a query to YouTube partner videos. A YouTube partner is a person or organization that has been accepted into and participates in the YouTube Partner Program. The uploader parameter's value must be partner.

In an API response, a feed entry contains a partner video if the entry contains a <media:credit> tag for which the value of the yt:type attribute is partner.
<media:credit role='uploader' scheme='urn:youtube' yt:display='partner_name'
  yt:type='partner'>partner_name</media:credit>

YouTube supports this parameter for video search requests.

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=2

    The 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&amp;oi=spell&amp;spell=1&amp;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.

  1. Atom elements reference
  2. OpenSearch elements reference
  3. YouTube elements reference
  4. Media RSS elements reference
  5. GData elements reference
  6. GeoRSS elements reference
  7. GML elements reference
  8. Atom Publishing Protocol element reference
  9. Browser-based upload API response elements reference
  10. Batch processing element reference
  11. Error response element reference

Certain symbols may be displayed next to some child tags in the definitions below. These symbols, and their meanings, are:

? = optional child tag
* = 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.
In all of these cases, the <media:credit> tag identifies the video owner.

Example

<author>

Child of

feed, entry

Children

name, uri?, yt:userId?

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

NameFormatDescription
scheme Text (URI) The scheme attribute specifies a URI that identifies the categorization scheme associated with the label.
  • In a request to add a subscription, set the value of the scheme attribute to http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat.
  • If the <category> tag identifies the YouTube category associated with the video, the value of the scheme attribute will be http://gdata.youtube.com/schemas/2007/categories.cat.
  • If the <category> tag identifies a keyword associated with the video, the value of the scheme attribute will be http://gdata.youtube.com/schemas/2007/keywords.cat.
  • If the <category> tag identifies a YouTube EDU category associated with a course or lecture, the value of the scheme attribute will be http://gdata.youtube.com/schemas/2007/educategories.cat.
term Text The term attribute identifies the type of entity contained in a feed entry or a category or keyword associated with a video.
  • In a subscription entry, the value of the term attribute may be user or channel.
  • In an activity feed, the value of the term attribute may be user_favorited, user_rated, user_shared or user_uploaded.
  • In a course or lecture feed or entry, the value of the term attribute will identify a YouTube EDU category associated with the course or lecture.
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

feed, entry

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 to false or did not include the inline 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's type and src attributes will both appear in the response.
    • If your API request set the inline parameter to true, 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's type attribute will be set, and its src attribute will not be set.

Attributes

NameFormatDescription
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

entry

Children

entry?

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

feed

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

POST and PUT operations

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

NameFormatDescription
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

feed

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

feed, entry

The <link> tag contains an IRI reference that is relevant to a feed or a feed entry.

Attributes

NameFormatDescription
rel Text The rel attribute indicates how the URI specified in the href attribute is related to the current result set:

  • If the rel attribute value is self, then the link identifies the URL that you would use to retrieve information about the feed or a particular entry in the feed.

  • If the rel attribute value is edit, then the link identifies the URL that you would use to modify a feed entry.

  • If the rel attribute value is alternate, then the link identifies a URL that presents a different representation of the feed, such as a link to the HTML representation of that feed entry.

  • If the rel attribute value is previous, then the link points to the previous page of the feed's result set.

  • If the rel attribute value is next, then the link points to the next page of the feed's result set.

  • If the rel attribute value is related, then the link identifies another feed that is related to the current feed. For example, if the feed contains a list of contact entries, then the related link for a contact might point to the feed for that contact's profile.

  • The rel attribute may also contain a link to a schema that identifies the type of entity related to the corresponding link. For example, a video entry contains <link> tags that point to caption tracks, responses, ratings, complaints and related videos for that video. Some of these <link> tags can be used to retrieve additional feeds, such as related videos, while others can be used to post data, such as a rating or complaint.

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

feed, entry

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

feed

name

The <name> tag contains the author's YouTube username.

Example

<name>GoogleDevelopers</name>

Child of

author

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

entry

subtitle

The <subtitle> tag contains a description of a playlist.

Example

<subtitle>My playlist description</subtitle>

Child of

feed

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

entry

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

feed, entry

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

feed, entry

uri

The <uri> tag contains a URL related to the author.

Example

<uri>http://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>

Child of

author

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

feed

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

feed

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:

<link rel="next" type="application/atom+xml" href="http://gdata.youtube.com/feeds/videos?start-index=26&max-results=25"/>


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

feed

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

entry

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 its name and reasonCode attributes set to restricted and limitedSyndication, 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 the syndicate access control.

Attributes

NameFormatDescription
action Text The action attribute identifies the type of access control being set. The list below identifies valid values for this attribute:
  • The rate control indicates whether users can rate the video.
  • The comment control indicates whether users can add comments about a video.
  • The commentVote control indicates whether users can rate other users' comments about a video.
  • The embed control indicates whether users can embed the video on third-party websites
  • The syndicate control indicates whether YouTube can show the video on mobile phones and televisions.
  • The list control indicates whether a video can be listed in YouTube search results or displayed in any other way unless the user has a URL that links directly to the video. The permission attribute for this control will automatically be set to denied for private videos.

    In addition, if you set the permission attribute to denied for this control but do not make the video a private video, then the video will be unlisted. Unlisted videos can be viewed by anyone who has a link to the video's watch page URL but they do not appear in search results. However, note 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.
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

entry

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

entry

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

entry

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

media:group

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

media:group

yt:availability

The <yt:availability> tag specifies the date range when a movie will be available on YouTube.

Attributes

NameFormatDescription
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

entry

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

entry

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

media:group

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

NameFormatDescription
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

entry

Children

media:content+

yt:channelId

The <yt:channelId> tag contains a value that uniquely identifies a YouTube channel.

Example

<yt:channelId>UCoUrIeCQbjRzAObg1lSS-uw</yt:channelId>

Child of

entry

yt:channelStatistics

The <yt:channelStatistics> tag provides statistics about a YouTube channel, and it only appears in channel entries.

Attributes

NameFormatDescription
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

entry

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

entry

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

entry

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

entry

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

entry

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

NameFormatDescription
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

media:group

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

NameFormatDescription
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

entry

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

entry

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

entry

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

entry

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

entry

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

entry

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:

Image showing single UI entry for a video that was marked as a favorite and positively rated by the same user.

Example

<yt:groupId>WnhFLWZvbzNoM0IzbWI0Y3VpQmNLQTMxMjcwMTQ5MTI0NTc</yt:groupId>

Child of

entry

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

entry

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

entry

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

entry

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 to People.

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

entry

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

entry

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

entry

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

NameFormatDescription
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

feed, entry

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

NameFormatDescription
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

entry

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

entry

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

entry

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

entry

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

entry

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

NameFormatDescription
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

entry

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

entry

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

entry

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

media:group

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

NameFormatDescription
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

entry

yt:recorded

The <yt:recorded> tag specifies the date that a video was recorded.

Example

<yt:recorded>2003-08-03</yt:recorded>

Child of

entry

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

entry

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

NameFormatDescription
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

entry

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

entry

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

NameFormatDescription

Example

<yt:season number='2'/>

Child of

entry

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

entry

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

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

  • restricted

    • requesterRegion - The video is not available in the user's region.
    • limitedSyndication - The video is not and, based on the content owner's current preferences, will not be available to play in non-browser devices, such as mobile phones.
      • 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 to mobile phones or other non-browser devices.
      • 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.
    • private - The video owner has restricted access to the video. This reasonCode signals that a video in a feed, such as a playlist or favorite videos feed, has been made a private video by the video's owner and is therefore unavailable.

  • rejected

    • copyright - The video commits a copyright infringement.
    • inappropriate - The video contains inappropriate content.
    • duplicate - The video is a duplicate of another uploaded video.
    • termsOfUse - The video commits a terms of use violate.
    • suspended - The account associated with the video has been suspended.
    • tooLong - The video exceeds the maximum duration of 10 minutes.
    • blocked - The video has been blocked by the content owner.

  • failed

    • cantProcess - YouTube is unable to convert the video file.
    • invalidFormat - The uploaded video is in an invalid file format.
    • unsupportedCodec - The video uses an unsupported codec.
    • empty - The uploaded file is empty.
    • tooSmall - The uploaded file is too small.

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

app:control

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

NameFormatDescription
viewCount Integer The viewCount attribute appears in statistics for videos and channels.
  • When the viewCount attribute refers to a video entry, the attribute specifies the number of times that the video has been viewed.
  • Deprecated. When the viewCount attribute refers to a user profile (channel), the attribute specifies the number of times that the user's profile has been viewed.
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

entry

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

entry

yt:threed

The <yt:threed> tag indicates, by its presence, that a video contains 3D content.

Attributes

NameFormatDescription
source Text The source attribute explains why the video is labeled as 3D content. Possible attribute values are:
  • uploaded – YouTube identified the original video stream as a 3D format.
  • converted – The video was converted to 3D.
  • declared – The video uploader indicated that the video contains 3D content. For example, a non-3D video might contain some 3D imagery that could be viewed with 3D glasses.
  • unknown – The source that identified the video as 3D content is unknown.

Example

<yt:threed source='declared'/>

Child of

entry

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

entry

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

media:group

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

media:group

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

entry, author

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

NameFormatDescription
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

entry

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

media:group

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

NameFormatDescription
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

entry

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 scheme http://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 are

      • 1 – Feature-length film
      • 2 – Short film
      • 3 – Full episode
      • 4 – Show clip
      • 5 – 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 & Adventure
      • 2 – Animation & Cartoons
      • 3 – Classics
      • 4 – Comedy
      • 5 – Crime
      • 6 – Drama
      • 7 – Documentary & Biography
      • 8 – Family
      • 9 – Foreign
      • 10 – Horror
      • 11 – Mystery & Suspense
      • 12 – Romance
      • 13 – Science Fiction
      • 15 – Sports
      • 18 – Indian Cinema
      • 19 – Nigerian Cinema


    • 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 are

      • 1 – Theatrical or festival film releases
      • 2 – Premium cable or satellite subscription channels, such as HBO
      • 3 – Basic cable and satellite channels, such as Comedy Central or MTV
      • 4 – Broadcast TV networks and local TV stations
      • 5 – Promotional clips and trailers
      • 6 – Original web content
      • 7 – Direct-to-video release


  • For courses and lectures, the <media:category> tag can use the category scheme http://gdata.youtube.com/schemas/2007/educategories.cat, in which case the tag identifies a YouTube EDU category associated with the course or lecture.

Attributes

NameFormatDescription
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:group

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

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

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

  • 19 – 480p FLV
  • 18 – 360p FLV
  • 17 – 240p FLV
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:group

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

NameFormatDescription
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.)
  • If the scheme is urn:youtube, then the attribute could have the following values:
    • uploader – The tag value identifies the YouTube partner who uploaded the video.
    • lecturer – The tag value identifies the lecturer for a course or lecture accessible via YouTube EDU.
  • If the scheme is urn:ebu, then the attribute's value will be a European Broadcasting Union role, such as Actor, Director, Producer, or Writer. In this case, the tag value identifies a contributor to a movie or television show episode.
scheme Text The scheme attribute identifies the role scheme.
  • The value will be urn:youtube if the tag identifies the YouTube partner that uploaded the video.
  • The value will be urn:ebu if the tag identifies a contributor to a movie or television show episode. In this case, the role attribute will specify the contributor's role.
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:group

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

NameFormatDescription
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

media:group

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

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

NameFormatDescription
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:group

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

NameFormatDescription
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:group

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

NameFormatDescription
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:group

media:rating

The <media:rating> tag serves one of the following purposes:

  • If the scheme attribute value is either urn:mpaa or urn:v-chip, then the tag specifies the rating that a movie received under that rating scheme.
  • If the scheme attribute value is http://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

NameFormatDescription
scheme Text The scheme attribute identifies the categorization scheme associated with the rating. Valid values are:
  • urn:mpaa – The <media:rating> tag specifies a Motion Picture Association of America (MPAA) rating. Valid MPAA ratings are g, pg, pg-13, r, and nc-17.
  • urn:v-chip – The <media:rating> tag specifies a V-Chip rating. Valid V-Chip ratings are tv-y, tv-y7, tv-y7-fv, tv-g, tv-pg, tv-14, and tv-ma.
  • urn:acb – The <media:rating> tag specifies an Australian Classification Board (ACB) rating. Valid ACB ratings are E, G, PG, M, MA15+, and R18+.
  • urn:bbfc – The <media:rating> tag specifies a British Board of Film Classification (BBFC) rating. Valid BBFC ratings are U, PG, 12, 12, 15, 18,and R18.
  • urn:cbfc – The <media:rating> tag specifies a Central Board of Film Certification (CBFC - India) rating. Valid CBFC ratings are U, U/A, A, and S.
  • urn:chvrs – The <media:rating> tag specifies a Canadian Home Video Rating System (CHVRS) rating. Valid CHVRS ratings are G, PG, 14A, 18A, R, and E.
  • urn:eirin – The <media:rating> tag specifies a 映倫管理委員会 (EIRIN - Japan) rating. Valid EIRIN ratings are G, PG-12, R15+, and R18+.
  • urn:fmoc – The <media:rating> tag specifies a Centre national du cinéma et de l'image animé (FMOC - France) rating. Valid FMOC ratings are E, U, 10, 12, 16, and 18.
  • urn:fsk – The <media:rating> tag specifies a Freiwillige Selbstkontrolle der Filmwirtschaft (FSK - Germany) rating. Valid FSK ratings are FSK 0, FSK 6, FSK 12, FSK 16, FSK 18.
  • urn:icaa – The <media:rating> tag specifies an Instituto de la Cinematografía y de las Artes Audiovisuales (ICAA - Spain) rating. Valid ICAA ratings are E, G, PG, M, MA15+, and R18+.
  • urn:kmrb – The <media:rating> tag specifies a Korea Media Rating Board (영상물등급위원회) (KMRB) rating. Valid KMRB ratings are All, 12+, 15+, Teenager restricted, and Restricted.
  • urn:oflc – The <media:rating> tag specifies an Office of Film and Literature Classification (OFLC - New Zealand) rating. Valid OFLC ratings are G, PG, R13, R15, R16, M, and R18.
  • http://gdata.youtube.com/schemas/2007#mediarating – The <media:rating> tag identifies content that is restricted in some countries.
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:group

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

NameFormatDescription
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:group

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 of hqdefault 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 of mqdefault 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, and end 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 the yt:name values may also not be accurate.
  • Movies uploaded by YouTube partners can also have a thumbnail image with a yt:name attribute value of poster, which identifies the poster art for the movie. A movie poster is typically 169px wide and 243px high.
A show entry can contain any or all of the following thumbnails:
  • Different sizes of the poster art for the show are identified by the tags with yt:name attribute values of poster (150px by 150px), hqposter (300px by 300px), or hqposterlarge (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 of market (72px by 128px) or hqmarket (243px by 432px).

Attributes

NameFormatDescription
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

entry, media:group

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

NameFormatDescription
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

media:group

GData elements reference

gd:comments

The <gd:comments> tag encapsulates a link to the comments feed for a video.

Example

<gd:comments>

Child of

entry

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

NameFormatDescription
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

entry, gd:comments

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

NameFormatDescription
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

entry

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

entry

Children

gml:Point

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

georss:where

Children

gml:pos

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

gml:Point

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

entry

Children

app:draft, yt:state

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

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

entry

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

url, token

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

response

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

response

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

entry

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

NameFormatDescription
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

entry

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

NameFormatDescription
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

feed, entry

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

NameFormatDescription
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

entry

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

error

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

error

The <error> tag contains information about a single error that caused an API request to fail.

Example

<error>

Child of

errors

Children

domain, code, location

errors

The <errors> tag encapsulates an API response explaining the errors that caused the corresponding API request to fail.

Example

<errors>

Children

error+

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

NameFormatDescription
type Text The type attribute provides context for the <location> tag's value. The type attribute can have any of the following values:
  • xpath - The XML request contains an error at the specified path, which is relative to the <entry> tag in the request.
  • parameter - The API request contains an error in the parameter specified in the <location> tag.
  • header - The API request contains an error in the specified HTTP request header.
  • other - The API request contains another type of error. This value is used to identify quota errors that have a code of too_many_entries.

Example

<location type='xpath'>media:group/media:title/text()</location>

Child of

error

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 &amp; 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.)

Language/Locale hl Parameter Value
Afrikaansaf-ZA
Amharicam-ET
Arabicar-EG
Basqueeu-ES
Bengalibn-BD
Bulgarianbg-BG
Catalanca-ES
Chinese (Traditional)zh-TW
Croatianhr-HR
Czechcs-CZ
Danishda-DK
Dutchnl-NL
English (Great Britain, Ireland, Australia and New Zealand)en-GB
English (United States and Canada)
* default value
en-US
Estonianet-EE
Filipinofil-PH
Finnishfi-FI
Frenchfr-FR
Galiciangl-ES
Germande-DE
Greekel-GR
Hebrewiw-IL
Hindihi-IN
Hungarianhu-HU
Icelandicis-IS
Indonesianid-ID
Language/Locale hl Parameter Value
Italianit-IT
Japaneseja-JP
Koreanko-KR
Latvianlv-LV
Lithuanianlt-LT
Malayms-MY
Marathimr-IN
Norwegiannb-NO
Persianfa-IR
Polishpl-PL
Portuguesept-BR or pt-PT
Romanianro-RO
Russianru-RU
Serbiansr-RS
Slovaksk-SK
Sloveniansl-SI
Spanish (Spain)es-ES
Spanish (Mexico)es-MX
Swahilisw-TZ
Swedishsv-SE
Tamilta-IN
Thaith-TH
Ukrainianuk-UA
Urduur-PK
Vietnamesevi-VN
Zuluzu-ZA

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's eventType 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's comments: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 the most_popular feed with a default time parameter value of today. The most_popular feed also supports a time parameter value of all_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 the most_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:

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's viewCount 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 of 1970-01-01T00:00:00.000Z.

  • The <yt:schedule> tag's new broadcaster 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 the most_popular standard feed are today and all_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 proper Authorization 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 of reversedPosition 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 the most_popular feed. We recommend that you update your code to use the most_popular feed instead of the most_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 the most_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:

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

      • The definition of the category parameter has been updated to explain how to retrieve a list of courses or lectures associated with a particular YouTube EDU category.

      • The new course parameter can be used to retrieve lectures associated with a particular course that is accessible via YouTube EDU.

    • 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's scheme attribute value will be urn:youtube, and its role attribute value will be lecturer. Previously, the only supported role for the urn:youtube scheme was uploader. With this in mind, note that your code should not assume the value of the tag's role parameter based on the value of its scheme 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 definition of the <media:rating> tag's scheme 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's display attribute and the <media:credit> tag's yt: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 new display 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.

    The <media:credit> tag also has a new yt: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. The mqdefault 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's yt:name attribute to select the most appropriate image to display.

March 16, 2012

This update contains the following changes:

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 and genre parameters can be used to retrieve show charts. The genre 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's yt:name attribute may now contain a value of poster for shows in addition to movies. Show posters are 128px wide and 72px high. (Movie posters are 169px wide and 243px high.) The yt:name attribute may also contain a value of market, 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 have yt:name attribute values of start, middle, and end do not necessarily reflect the times when those frames actually appear in the video. In addition, the relative ordering of thumbnails implied by the yt: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. Its source 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 are cc and youtube.

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 3d parameter's definition has been updated to note that true is the only supported parameter value and that false is not a valid parameter value. The API's default behavior, which occurs when the 3d 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 to true 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, and status. In addition, the inline and time 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 are pending, active, completed, delayed, cancelled and rejected.

  • 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 and https://gdata.youtube.com scopes are interchangeable. As such, if you have already obtained an AuthSub or OAuth token for the http://gdata.youtube.com scope, you can use that same token to authorize requests to https://gdata.youtube.com.

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.
  • 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's yt:name attribute may now contain a value of poster, which indicates that the associated thumbnail image is the poster art for a movie.

April 14, 2011

This update contains the following changes:

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 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 a fmt 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 new yt: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 a yt:name value of hqdefault, 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 to false. (To restrict a result set to only include videos that have caption tracks, set the caption parameter value to true or include the caption 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) and pt-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 supported time parameter values for that feed are this_week, this_month, and all_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:

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 the mobile 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 value speechRecognition 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 and lang 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 new totalUploadViews 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 as video_rated and video_uploaded events, should include an embedded video entry that contains information about that video. The default parameter value is false. 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.

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

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.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.