Contents

1. Overview
2. Projection values
3. Feed Types
   1. Video feeds
      1. Videos feed
      2. Related videos feed
      3. Video responses feed
      4. Standard feeds
         1. Retrieving region-specific standard video feeds
         2. Retrieving category-specific standard video feeds
         3. Using the time parameter with standard feeds
      5. User's favorites feed
      6. 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:groupId
      24. yt:hd
      25. yt:hobbies
      26. yt:hometown
      27. yt:incomplete
      28. yt:lastName
      29. yt:location
      30. yt:material
      31. yt:maxUploadDuration
      32. yt:movies
      33. yt:music
      34. yt:noembed
      35. yt:occupation
      36. yt:option
      37. yt:playlistId
      38. yt:position
      39. yt:private
      40. yt:rating
      41. yt:recorded
      42. yt:relationship
      43. yt:schedule
      44. yt:school
      45. yt:season
      46. yt:spam
      47. yt:state
      48. yt:statistics
      49. yt:status
      50. yt:threed
      51. yt:unreadCount
      52. yt:uploaded
      53. yt:uploaderId
      54. yt:userId
      55. yt:username
      56. yt:videoid
      57. 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:

fields=entry[link/@rel='http://gdata.youtube.com/schemas/2007%23mobile']

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

Related videos feed

The related videos feed contains a list of videos that are related to another video. YouTube algorithmically selects the set of related videos.

Each video entry in an API response contains a series of <link> tags. The <link> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007/#video.related identifies the URL for retrieving other videos related to that video entry. (The <link> tag's href attribute identifies the URL.)

<link rel="http://gdata.youtube.com/schemas/2007#video.related"
     type="application/atom+xml"
     href="https://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/related?v=2"/>

Related videos feeds contain a maximum of 100 videos.

Video responses feed

A video responses feed contains videos that have been explicitly designated as a response to another video. A video can be designated as a video response to exactly one other video, and some videos may not have any video responses.

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.responses identifies the URL for retrieving video responses for that video entry. (The <link> tag's href attribute identifies the URL as shown in the following example.)

<link rel="http://gdata.youtube.com/schemas/2007#video.responses"
     type="application/atom+xml"
     href="http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b/responses?v=2"/>

Standard feeds

Standard feeds contain lists of videos that either reflect YouTube user behavior, such as top-rated and most viewed video feeds, or were selected by YouTube staff, such as recently featured and mobile video feeds. Many of these feeds are shown on the Videos tab of the YouTube website.

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.

To retrieve a standard feed, send a GET request to the URL associated with that feed. The following table identifies the URL associated with each standard feed:

Name	Feed Id	URL and Description
Top rated	top_rated	URL: https://gdata.youtube.com/feeds/api/standardfeeds/top_rated Description: This feed contains the most highly rated YouTube videos.
Top favorites	top_favorites	URL: https://gdata.youtube.com/feeds/api/standardfeeds/top_favorites Description: This feed contains videos most frequently flagged as favorite videos.
Most shared	most_shared	URL: https://gdata.youtube.com/feeds/api/standardfeeds/most_shared Description: This feed lists the YouTube videos most frequently shared on Facebook and Twitter. This feed is available as an experimental feature.
Most popular	most_popular	URL: https://gdata.youtube.com/feeds/api/standardfeeds/most_popular Description: This feed contains the most popular YouTube videos, selected using an algorithm that combines many different signals to determine overall popularity.
Most recent	most_recent	URL: https://gdata.youtube.com/feeds/api/standardfeeds/most_recent Description: This feed contains the videos most recently submitted to YouTube.
Most discussed	most_discussed	URL: https://gdata.youtube.com/feeds/api/standardfeeds/most_discussed Description: This feed contains the YouTube videos that have received the most comments.
Most responded	most_responded	URL: https://gdata.youtube.com/feeds/api/standardfeeds/most_responded Description: This feed contains YouTube videos that receive the most video responses.
Recently featured	recently_featured	URL: https://gdata.youtube.com/feeds/api/standardfeeds/recently_featured Description: This feed contains videos recently featured on the YouTube home page or featured videos tab.
Trending videos	on_the_web	URL: https://gdata.youtube.com/feeds/api/standardfeeds/on_the_web Description: This 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. This feed is available as an experimental feature.
Most viewed	most_viewed	URL: https://gdata.youtube.com/feeds/api/standardfeeds/most_viewed Description: Deprecated on July 23, 2012. This feed actually returns the same content as the most_popular feed. As such, we recommend that you update your code to use the most_popular feed instead.

In addition, please note that many of these 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 a GET request to the following URL:

https://gdata.youtube.com/feeds/api/standardfeeds/top_rated?time=today

Note: The top_rated, top_favorites, most_discussed, and most_responded standard feeds support the time parameter. The deprecated most_viewed feed also supported that parameter.

Retrieving region-specific standard video feeds

The API enables you to retrieve region-specific standard feeds by inserting a region ID in the feed URL. The following URL demonstrates the format of the URLs that you would use to retrieve region-specific standard feeds:

http://gdata.youtube.com/feeds/api/standardfeeds/regionID/feedID?v=2

For example, to retrieve a list of the top-rated videos in Japan, you would send a GET request to the following URL:

http://gdata.youtube.com/feeds/api/standardfeeds/JP/top_rated?v=2

The following tables identify the countries for which the YouTube Data API supports localized feeds and the regionID associated with each country:

Retrieving category-specific standard video feeds

The API also enables you to retrieve category-specific standard feeds by appending an underscore and a category name to the standard feed URL. The following URL demonstrates the format of the URLs that you would use to retrieve category-specific standard feeds:

https://gdata.youtube.com/feeds/api/standardfeeds/regionID/feedID_CATEGORY_NAME?v=2

For example, to retrieve a list of the top-rated comedies in Japan, you would send a GET request to the following URL:

https://gdata.youtube.com/feeds/api/standardfeeds/JP/top_rated_Comedy?v=2

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 top-rated entertainment videos in France:
  https://gdata.youtube.com/feeds/api/standardfeeds/FR/top_rated_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 standard 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 top-rated nonprofit videos in the United States because "Nonprofit" is a browsable category in the United States. However, you cannot request the top-rated 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 video responses for that entry.

  <link rel="http://gdata.youtube.com/schemas/2007#video.responses" 
      type="application/atom+xml" 
      href="http://gdata.youtube.com/feeds/api/videos/UwOA8H5Vaak/responses?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 26^th to 50^th 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, video responses, 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, video response, 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, video responses, 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 "Top Rated" feed for user GoogleDevelopers, the API will retrieve the top-rated feed and return a response containing videos in that feed uploaded by user GoogleDevelopers. The API will not return a list of that user's videos ordered by rating. In a request for a user activity feed, the author parameter contains a comma-separated list of up to 20 YouTube usernames. The API response will contain activities performed by any of those users.
callback	The callback parameter 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. The fields parameter is currently used for experimental features only.
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:

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 many standard feeds, the author parameter for user activity feeds, and the restriction parameter for video feeds. Please see the Testing and troubleshooting section for tips on how to filter API response feeds that do not support these parameters.

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	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. Note: The ends-after parameter is currently used for experimental features only.
ends-before	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. Note: The ends-before parameter is currently used for experimental features only.
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	The hint parameter is specified in a request to retrieve a list of unused YouTube usernames that are 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. Note: Live event feeds are an experimental API feature (). 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	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	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.
paid-content	The paid-content parameter can be used to restrict a search or a movie chart to only include either paid content or free content. By default, search results and movie charts include both paid and free content. 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, video responses and so forth. If a video in the API response is not playable in the location that you're using to restrict availability of the content, the <entry> for that tag will not contain a <media:content> tag. However, it will contain a <yt:state> tag that indicates that the video is restricted.
safeSearch	The safeSearch parameter indicates whether the search results should include restricted content as well as standard content. YouTube will determine whether content is restricted based on the user's IP address or location, which you specify in your API request using the restriction parameter. If you do request restricted content, then feed entries for videos that contain restricted content will contain the <media:rating> element. The following values are valid for this parameter: 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	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. Note: The starts-after parameter is currently used for experimental features only.
starts-before	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. Note: The starts-before parameter is currently used for experimental features only.
status	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. Note: The status parameter is currently used for experimental features only.
time	The time parameter is supported for search feeds and for a number of standard feeds and live event charts as well. 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 or live event chart, 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 this_week in a request for the top_rated standard video feed, the feed will contain the videos that received the highest ratings over the previous one-week period. This parameter is supported for the following feeds and charts: Standard video feeds top_rated top_favorites most_popular (only supported values are today and all_time) most_discussed most_responded most_viewed (deprecated) Standard channel feeds most_subscribed – This feed only supports the parameter values this_week, this_month, and all_time. most_viewed Live event charts ( experimental feature) upcoming – This feed only supports the parameter values today and this_week.
uploader	The uploader parameter, which is only supported for search requests, lets you restrict a query to YouTube partner videos. A YouTube partner is a person or organization that has been accepted into and participates in the YouTube Partner Program. The uploader parameter's value must be partner. In an API response, a feed entry contains a partner video if the entry contains a <media:credit> tag for which the value of the yt:type attribute is partner. <media:credit role='uploader' scheme='urn:youtube' yt:display='partner_name' yt:type='partner'>partner_name</media:credit> YouTube supports this parameter for video search requests.

Category search in video feeds

YouTube videos can be categorized in the following ways:

• Each video can be associated with one predefined YouTube category, such as Comedy, Music, News or Sports. A video's category is identified by the <media:category> tag and by the <category> tag for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/categories.cat.

• Each video can be associated with an arbitrary number of keywords, which are also known as tags. A video's tags are identified using the <media:keywords> tag in API requests and responses. Keyword tags are also identified by <category> tags for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/keywords.cat.

• Each video can also be associated with an arbitrary number of developer tags. You can search for videos using developer tags. However, developer tags are not displayed on YouTube's website and you should not display them in your application. A video's developer tags are identified in <media:category> and <category> tags for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/developertags.cat.

  Please see the developer's guide for more information about assigning developer tags.

The YouTube Data API supports two different methods for retrieving videos that are in a particular category or that are labeled with a specific keyword or developer tag.

• Use the following URL to retrieve videos that are in a specific category or that are labeled with a specific keyword or developer tag. The hyphen (-) in the URL is a standard Google Data API notation that indicates that the rest of the URL consists of a series of one or more tags.

  http://gdata.youtube.com/feeds/api/videos/-/category_or_tag?v=2
  

  The following example shows the URL that you would use to request videos in the "Comedy" category:

  http://gdata.youtube.com/feeds/api/videos/-/Comedy?v=2

• Specify the category, keyword or developer tags using the category parameter in the request URL. The following example shows the URL that you would use to request videos in the "Comedy" category:

  http://gdata.youtube.com/feeds/api/videos?category=Comedy&v=2

  
  

The following guidelines provide more detail about requesting videos associated with particular categories or tags:

• If your request specifies a category and one or more keywords or if your request does not specify a category but does specify multiple keywords, separate each individual category and keyword name with a forward slash. (If you are using the category parameter, separate the different category and tag names with a comma. (The comma must be URL-encoded in your request.) For example, you could use either of the following URLs to request videos related to the keywords "bass" and "fishing":

  URL notation:
  https://gdata.youtube.com/feeds/api/videos/-/bass/fishing?v=2
  
  category parameter:
  https://gdata.youtube.com/feeds/api/videos?category=bass%2Cfishing&v=2
  

• Your request can use the Boolean NOT (-) and OR (|) operators to exclude videos or to find videos that are associated with one of several keywords or categories. For example, if you wanted to display videos related to "bass" and "music", the most effective search might be for videos associated with the keyword "bass" but not associated with the keywords "fish" or "fishing" as shown in the example below. (Searching for videos associated with the "Music" category and the keyword "bass" might exclude instructional videos about how to play bass.)

  URL notation:
  https://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing?v=2
  
  category parameter:
  https://gdata.youtube.com/feeds/api/videos?
  category=bass%2C%2Dfish%2Dfishing&v=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.

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:

Atom elements reference

author

<author>

category

<category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat' term='channel'/>

content

<content type="text">Video comments are cool.</content>

entry

<entry>

feed

<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'>

generator

<generator version='beta' uri='http://gdata.youtube.com/'>YouTube data API</generator>

id

<id>tag:youtube,2008:video:24Ryj1ywosw</id>

link

<link rel='http://gdata.youtube.com/schemas/2007#video.related' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/videos/AlPqL7IUT6M/related'/>

logo

<logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>

name

<name>GoogleDevelopers</name>

published

<published>2007-10-15T15:39:34.000-07:00</published>

subtitle

<subtitle>My playlist description</subtitle>

summary

<summary>Dan is getting ready for the game.</summary>

title

<title>GoogleDeveloper's Subscriptions</title>

updated

<updated>2007-10-15T15:39:34.000-07:00</updated>

uri

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

OpenSearch elements reference

openSearch:itemsPerPage

<openSearch:itemsPerPage>25</openSearch:itemsPerPage>

openSearch:startIndex

<openSearch:startIndex>1</openSearch:startIndex>

openSearch:totalResults

<openSearch:totalResults>36</openSearch:totalResults>

YouTube elements reference

yt:aboutMe

<yt:aboutMe>I am very funny.</yt:aboutMe>

yt:accessControl

<yt:accessControl action='comment' permission='allowed'/>

yt:age

<yt:age>33</yt:age>

yt:archived

<yt:archived>true</yt:archived>

yt:aspectratio

<yt:aspectratio>widescreen</yt:aspectratio>

yt:audioTracks

<yt:audioTracks>en</yt:audioTracks>

yt:availability

<yt:availability start=2009-06-04T15:00:00.000Z' end='2019-06-15T23:59:00.000Z'/>

yt:books

<yt:books>Catch-22</yt:books>

yt:captionTracks

<yt:captionTracks>de, en, fr</yt:captionTracks>

yt:cdn

<yt:cdn name="primary">

yt:channelId

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

yt:channelStatistics

<yt:channelStatistics commentCount='34' totalUploadViewCount='8623741' videoCount='71' viewCount='716912'/>

yt:company

<yt:company>Google</yt:company>

yt:contentType

<yt:contentType>channel</yt:contentType>

yt:countHint

<yt:countHint>9</yt:countHint>

yt:derived

<yt:derived>speechRecognition</yt:derived>

yt:duration

<yt:duration seconds='344'/>

yt:episode

<yt:episode number='12'/>

yt:favoriteId

<yt:favoriteId>vjVQa1PpcFP9NzIof2dlerfluOcvDpkm8zDBp7uuzOo</yt:favoriteId>

yt:firstName

<yt:firstName>John</yt:firstName>

yt:firstReleased

<yt:firstReleased>2009-06-04T00:00:00.000Z</yt:firstReleased>

yt:gender

<yt:gender>m</yt:gender>

yt:groupId

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

yt:hd

<yt:hd/>

yt:hobbies

<yt:hobbies>Testing YouTube APIs</yt:hobbies>

yt:hometown

<yt:hometown>Albany, GA</yt:hometown>

yt:incomplete

<yt:incomplete/>

yt:lastName

<yt:lastName>Smith</yt:lastName>

yt:location

<yt:location>US</yt:location>

yt:material

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

yt:maxUploadDuration

<yt:maxUploadDuration seconds="930"/>

yt:movies

<yt:movies>Aqua Teen Hungerforce</yt:movies>

yt:music

<yt:music>Elliott Smith, the Kooks</yt:music>

yt:noembed

<yt:noembed/>

yt:occupation

<yt:occupation>Technical writer</yt:occupation>

yt:option

<yt:option name='channel.featured_video_module.video_id.string'>3jNiR8pY7XI</yt:option>

yt:playlistId

<yt:playlistId>C344114E1E41B2FA</yt:playlistId>

yt:position

<yt:position>4</yt:position>

yt:private

<yt:private/>

yt:rating

In an API response:
<yt:rating numDislikes='28' numLikes='141'/>

In a request to add a rating:
<yt:rating value="like"/>

yt:recorded

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

yt:relationship

<yt:relationship>taken</yt:relationship>

yt:schedule

<yt:schedule country="US" dayOfWeek="1" hour="22" minute="0" second="0" timezone="EST" type="weekly"/>

yt:school

<yt:school>University of North Carolina</yt:school>

yt:season

<yt:season number='2'/>

yt:spam

<yt:spam/>

yt:state

<yt:state name="rejected" reasonCode="tooLong" helpUrl="http://www.youtube.com/t/community_guidelines">Video is too long</yt:state>

yt:statistics

<yt:statistics viewCount='9' videoWatchCount='24' subscriberCount='1' lastWebAccess='2008-02-29T13:09:48.000-08:00'/>

yt:status

In a contact feed entry:
    <yt:status>accepted</yt:status>

In a live events feed entry:
    <yt:status>pending</yt:status>

yt:threed

<yt:threed source='declared'/>

yt:unreadCount

<yt:unreadCount>5</yt:unreadCount>

yt:uploaded

<yt:uploaded>2007-10-15T15:39:34.000-07:00</yt:uploaded>

yt:uploaderId

<yt:uploaderId>WBw1PCAJfWtqaNpsFIOeiA</yt:uploaderId>

yt:userId

<yt:userId>ZxF-foo3h3B3mb4cuiBcKA</yt:userId>

yt:username

<yt:username display="GoogleDevelopers">googledevelopers</yt:username>

yt:videoid

<yt:videoid>QbEwKcs-8Hc</yt:videoid>

yt:when

<yt:when end="2011-06-14T14:37:24.000Z" start="2011-06-14T13:00:00.000Z"/>

Media RSS elements reference

media:category

<media:category label='Sports' scheme='http://gdata.youtube.com/schemas/2007/categories.cat'>Sports</media:category>

media:content

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?...'/>

media:credit

<media:credit role="uploader" scheme="urn:youtube">scenarioIAM</media:credit><br/><media:credit role='Writer' scheme='urn:ebu'>Dennis Johnson</media:credit>

media:description

<media:description type="plain">Granny takes crocheting to the extreme during a rodeo and while surfing.</media:description>

media:group

<media:group>

media:keywords

<media:keywords>winter, snowball fight, snowman, corncob pipe</media:keywords>

media:license

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

media:player

<media:player url='http://www.youtube.com/watch?v=8aYQ_wjmriQ'/>

media:price

<media:price type='rent' price='1.99' currency='USD' yt:duration='PT86400S'/>

media:rating

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

media:restriction

<media:restriction type='country' relationship='deny'>US</media:restriction>

media:thumbnail

<media:thumbnail url='http://img.youtube.com/vi/8aYQ_wjmriQ/2.jpg' height='90' width='120' time='00:01:23' yt:name='default'/>

media:title

<media:title type="plain">Extreme crocheting in high surf, rodeo</media:title>

GData elements reference

gd:comments

<gd:comments>

gd:feedLink

<gd:feedLink href='http://gdata.youtube.com/feeds/api/videos/8aYQ_wjmxiQ/comments' countHint='0'/>

gd:rating

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

GeoRSS elements reference

georss:where

<georss:where>

GML elements reference

gml:Point

<gml:Point>

gml:pos

<gml:pos>47.367 8.55</gml:pos>

Atom Publishing Protocol element reference

app:control

<app:control>

app:draft

<app:draft>yes</app:draft>

app:edited

<app:edited>2007-10-15T15:39:34.000-07:00</app:edited>

Browser-based upload API response elements reference

response

<response>

token

<token>AEwbFAQEvf3xox...</token>

url

<url>http://uploads.gdata.youtube.com/action/FormUpload/AEF3087AUD</url>

Batch processing element reference

batch:id

<batch:id>PlaylistEntry3</batch:id>

batch:interrupted

<batch:interrupted reason="[Line 14, Column 34, element entry] Invalid type for batch:operation: 'PUT'" success="8" failures="3" parsed="14"/>

batch:operation

<batch:operation type="insert"/>

batch:status

<batch:status code="201" reason="Created"/>

Error response element reference

code

<code>required</code>

domain

<domain>yt:validation</domain>

error

<error>

errors

<errors>

location

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

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.)

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.

Examples

You can find additional information on URL escaping in RFC 3986.

Revision History

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:

• The <yt:option> tag appears in the newly supported branding options feed. Each <yt:option> identifies a single branding setting and its value for the specified channel.

July 18, 2012

This update contains the following changes:

• The documentation contains several changes to reflect the API's newly added support for retrieving information about lectures (videos), courses, and subjects that are accessible through YouTube EDU. Note that the YouTube EDU feeds are currently available as an experimental feature.

  • Parameter changes

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

• The new hl query parameter is now supported for retrieving movie charts. The parameter's value is an ISO 639-1 two-letter language code.

March 14, 2012

This update contains a few changes that reflect the fact that the API now supports feeds for shows and seasons:

• The query parameter definitions section also now mentions that the region 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:

• The <gd:rating> tag has been deprecated. Please use the <yt:rating> tag instead.

February 28, 2011

This update contains the following changes:

• The API now lets you retrieve two new standard feeds, both of which are available as experimental features:

  • The most_shared feed lists the YouTube videos most frequently shared on Facebook and Twitter.
  • The on_the_web feed lists trending videos as seen on YouTube Trends, which surfaces popular videos as their popularity is increasing and also analyzes broader trends developing within the YouTube community.

• The 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:

• The Retrieving region-specific standard video feeds section has been updated to note that region-specific feeds are now supported for Argentina (AR) and South Africa (ZA).

October 20, 2010

This update contains the following changes:

• The Projection values section has been updated to better explain what a projection is and, specifically, why the mobile projection is available. The section now explains that using 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

• The Category list for uploaded videos section has been updated to explain how to download category lists for specific languages and locales.

May 2, 2008

This update contains the following changes:

• The vq and orderby parameter definitions have been updated to clarify that these parameters are only supported for API requests for video feeds. [Note: The name of the vq parameter changed to q with the release of version 2 of the YouTube Data API.] Playlist feeds do not support the orderby parameter because playlist feed entries are always ordered based on the position of each entry in the playlist.

• The racy parameter definition has been updated to note that feed entries for videos that contain restricted content will contain the <media:rating> element.

• The restriction parameter definition has been updated with a recommendation that you always include this parameter in API requests, setting the parameter value to the end user's IP address.

• The <media:rating> tag, a new subtag of <media:group>, replaces the <yt:racy> tag as the standard way to identify videos that contain restricted content. In addition, the <yt:racy> tag definition has been updated to note that this tag has been deprecated. [Note: The definition of this tag was removed from the API's version 2 documentation.] Although the tag may still be included in API responses to ensure backward compatibility with legacy applications, your application should check for the presence of the <media:rating> tag to determine whether a video contains restricted content.

April 7, 2008

This document contains the following changes:

• The newly added Revision History highlights important changes to this document. The revision history will not mention minor changes such as spelling corrections.

• The API now supports the client parameter, which provides an alternate way of identifying your application. You can also use the X-GData-Client header to identify your application.

• The definition of the <media:keywords> tag has been updated to note that in the tag value, individual keywords may be separated by spaces but may not contain spaces.