Reference Guide: Data API Protocol

Contents

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 every few minutes.
• 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. 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:

Feed Types

You can retrieve the following types of feeds from the YouTube Data API:

The API allows you to retrieve any of these feeds without authentication. However, in some cases, an authenticated request may retrieve additional information. For example, if you submit an authenticated 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 unauthenticated 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 authenticate all requests, including GET requests, using a developer key and either AuthSub or ClientLogin authentication.

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="http://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 every few minutes.

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

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 an HTTP GET request to the following URL:

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

Note: The top_rated, top_favorites, most_viewed, most_discussed and most_responded standard feeds support the time parameter.

Retrieving region-specific standard feeds

The API enables you to retrieve region-specific standard feeds by inserting a region ID in the standard 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 an HTTP GET request to the following URL:

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

Note: Region-specific versions of the watch_on_mobile standard feed are not available.

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

Retrieving category-specific standard 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. inserting a region ID in the standard 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_CATEGORY_NAME?v=2

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

http://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:
  http://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 authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.

  http://gdata.youtube.com/feeds/api/users/default/favorites?v=2

• To request a feed of another user's favorite videos, send an HTTP GET request to the following URL. Note that this request does not require authentication.

  http://gdata.youtube.com/feeds/api/users/username/favorites?v=2

  In the URL above, you must replace the text username with the user's YouTube username.

The favorites feed returns a maximum of 50 entries. 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. The recommended value for max-results is 10, yielding a response that contains about 60KB of data.

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 authentication. 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 unauthenticated 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 an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.

  http://gdata.youtube.com/feeds/api/users/default/playlists?v=2

• To request a feed of another user's playlists, send an HTTP GET request to the following URL. Note that this request does not require authentication.

  http://gdata.youtube.com/feeds/api/users/username/playlists?v=2

  In the URL above, you must replace the text username with the user's YouTube username.

User's subscriptions feed

A user's subscriptions feed contains a list of the channels, favorite video lists and search queries to which the user has subscribed.

• To request a feed of the currently logged-in user's subscriptions, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.

  http://gdata.youtube.com/feeds/api/users/default/subscriptions?v=2

• To request a feed of another user's subscriptions, send an HTTP GET request to the following URL. Note that this request does not require authentication.

  http://gdata.youtube.com/feeds/api/users/username/subscriptions?v=2

  In the URL above, you must replace the text username with the user's YouTube username.

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"), another user's favorite videos list (term="favorites"), or to videos that match specific keywords (term="query").

• If the subscription is to another user's channel or list of favorite videos, the <yt:username> tag will identify the user who owns the channel or favorite video list.

  If the subscription is to a keyword query, the <yt:queryString> element will contain the subscribed-to query term.

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 authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.

  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. Note that this request does not require authentication.

  http://gdata.youtube.com/feeds/api/users/username?v=2

  In the URL above, you must replace the text username with the user's YouTube username. Depending on the type of YouTube API response you are working with, usernames will appear in either the <name> tag or the <yt:username> tag.

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

A user's contacts feed lists all of the contacts for a specified user.

• To request the currently logged-in user's contact list, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.

  http://gdata.youtube.com/feeds/api/users/default/contacts?v=2

• To request another user's contact list, send an HTTP GET request to the following URL. Note that this request does not require authentication.

  http://gdata.youtube.com/feeds/api/users/username/contacts?v=2

  In the URL above, you must replace the text username with the user's YouTube username.

Contacts can be classified as either Friends or Family.

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

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 wny 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 wny 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 wny 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 authentication 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 authentication 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, submit an HTTP GET request to the following URL, appending the appropriate query parameters to your request:

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

http://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.

http://gdata.youtube.com/feeds/api/videos?foo=nonono&strict=true

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

The following table defines each of these parameters:

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

<media:credit role="uploader" scheme="urn:youtube
  yt:type="partner">partner_name</media:credit>

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:
  http://gdata.youtube.com/feeds/api/videos/-/bass/fishing?v=2
  
  category parameter:
  http://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:
  http://gdata.youtube.com/feeds/api/videos/-/bass/-fish/-fishing?v=2
  
  category parameter:
  http://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:
  http://gdata.youtube.com/feeds/api/videos/-/jesse/ventura/News%7CSports?v=2
  
  category parameter:
  http://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:
  http://gdata.youtube.com/feeds/api/videos/-/comedy/-Comedy?v=2
  
  category parameter:
  http://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:
    http://gdata.youtube.com/feeds/api/videos/-/
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fcategories.cat%7DNews?v=2
  
    category parameter:
    http://gdata.youtube.com/feeds/api/videos?category=
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fcategories.cat%7DNews&v=2
  
  Keywords:
    URL notation:
    http://gdata.youtube.com/feeds/api/videos/-/
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fkeywords.cat%7Ddog?v=2
  
    category parameter:
    http://gdata.youtube.com/feeds/api/videos?category=
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fkeywords.cat%7Ddog&v=2
  
  Developer tags:
    URL notation:
    http://gdata.youtube.com/feeds/api/videos/-/
      %7Bhttp%3A%2F%2Fgdata.youtube.com%2Fschemas%2F2007
      %2Fdevelopertags.cat%7Dexample.com?v=2
  
    category parameter:
    http://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 tables define the XML tags from each of these schemas that appear in YouTube Data API requests and responses. Each table contains the definition for a single tag, and tags are listed in alphabetical order by schema.

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>andyland74</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>andyland74's Subscriptions</title>

updated

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

uri

<uri>http://gdata.youtube.com/feeds/api/users/andyland74</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:age

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

yt:aspectratio

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

yt:books

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

yt:company

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

yt:countHint

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

yt:duration

<yt:duration seconds='344'/>

yt:firstName

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

yt:gender

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

yt:hobbies

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

yt:hometown

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

yt:lastName

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

yt:location

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

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

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

yt:playlistTitle

<yt:playlistTitle>Doritos You Make It We Play It</yt:playlistTitle>

yt:position

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

yt:private

<yt:private/>

yt:queryString

<yt:queryString>Dog skateboarding</yt:queryString>

yt:recorded

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

yt:relationship

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

yt:school

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

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

<yt:status>accepted</yt:status>

yt:uploaded

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

yt:username

<yt:username>andyland74</yt:username>

yt:videoid

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

Media RSS elements reference

media:category

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

media:content

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

media:credit

<media:credit role="uploader" scheme="urn:youtube">scenarioIAM</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:player

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

media:rating

<media:rating scheme="http://gdata.youtube.com/schemas/2007#mediarating" country="HK,TW">1</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='97' width='130' time='00:01:23'/>

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 nonalphanumeric 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 at RFC 2396 and W3C.

Revision History

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.