This document explains how to migrate your website or application to work with version 2 of the YouTube Data API. It summarizes the new features available in version 2 of the API and explains other differences between version 2 and version 1.
By default, this document explains the changes in the API's XML protocol. To see how the changes affect specific client libraries in addition to the XML protocol changes, check the box(es) next to the additional migration instructions that you want to see displayed. (The client libraries for PHP and Python and have not yet been updated for API version 2.)
Java .NET PHP |
Since YouTube still supports API version 1, you only need to upgrade if you want to use one of the new features available in version 2. However, we recommend that you upgrade so that users of your website or application can access those new features.
The following sections describe the differences between API version 1 and API version 2. Each section also discusses the corresponding steps you need to take to migrate your website or application.
Submitting API requests
Handling API responses
To use API version 2, each API request that your website or application submits needs to specify the API version that you want to use. The API provides two ways to specify an API version.
You can append the v parameter to all API requests. The v parameter identifies the version of the API that YouTube should use to handle the API request. If a request does not specify a value for the v parameter, YouTube will handle the request using the oldest supported API version (1).
You can use the GData-Version
HTTP request header to identify the version of the API that YouTube should use to handle the corresponding request.
The Java and .NET client libraries for API version 2 use the GData-Version
HTTP request header.
If your API request uses the v parameter rather than the GData-Version
HTTP request header to specify an API version, any feed URLs in the API response will automatically specify the same version by using the v parameter value. The XML snippets below show the changes to API request URLs as well as to API response tags that contain feed URLs.
API version 1: API request URL: http://gdata.youtube.com/feeds/api/users/default Tags in API response: <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.favorites' href='http://gdata.youtube.com/feeds/api/users/andyland74/favorites' countHint='4'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.contacts' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts' countHint='1'/> API version 2: API request URL: http://gdata.youtube.com/feeds/api/users/default?v=2 Tags in API response: <link rel='self' type='application/atom+xml' href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.favorites' href='http://gdata.youtube.com/feeds/api/users/andyland74/favorites?v=2' countHint='4'/> <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.contacts' href='http://gdata.youtube.com/feeds/api/users/andyland74/contacts?v=2' countHint='1'/>
Steps to migrate
Add the GData-Version
HTTP request header to each API request or append the v parameter to all API requests. Set the value of the request header or parameter value to 2
.
Every API request in version 2 must specify a projection. The following example shows how a projection appears in an API request URL:
http://gdata.youtube.com/feeds/api/users/default
Steps to migrate
Confirm that all API requests specify a projection.
Ensure that your code uses the values of the <link>, <content> and <gd:feedLink> tags to navigate between feeds.
If you are using one of the client libraries, you do not need to do anything for this change. The client libraries automatically specify a projection for each request.
In API version 1, an <id> tag value specifies a URI that could be used to request a feed. In API version 2, however, an <id> tag value is a URN (uniform resource name) that is not a feed URL. The following example shows how the <id> tag for a video entry differs between API versions 1 and 2:
API version 1: <id>http://gdata.youtube.com/feeds/api/videos/ZTUVgYoeN_b</id> API version 2: <id>tag:youtube,2008:video:ZTUVgYoeN_b</id>
Steps to migrate
You should not need to take any action related to this change. However, if your application uses <id> tag values to identify feed URLs, which is not recommended, you should update your application so that it only identifies feed URLs from <link> tags, <content> tags and <gd:feedLink> tags. Please see the Navigating between feeds section of the reference guide for more information.
In API version 2, the safeSearch parameter indicates whether 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 safeSearch parameter replaces the racy parameter, which was used in version 1.
Steps to migrate
If your website or application does not specify a value for the racy parameter in API requests, you do not need to do anything for this change.
If your website or application does specify a value for the racy parameter, replace the parameter name racy with the new parameter name, which is safeSearch.
In API version 1, the location parameter restricts search results to videos that are identified with a geographic location, but it does not enable you to find videos near a particular location. In version 2, however, the location parameter can be used to request videos that are associated with a particular geographic area.
The examples below show valid uses of the location parameter in API versions 1 and 2. Some URLs are formatted on two lines to ensure a printer-friendly document.
API version 1: * http://gdata.youtube.com/feeds/api/videos?vq=dogs&location= * http://gdata.youtube.com/feeds/api/videos?vq=dogs&location=! API version 2 * http://gdata.youtube.com/feeds/api/videos?q=dogs&location= * http://gdata.youtube.com/feeds/api/videos?q=dogs&location=! * http://gdata.youtube.com/feeds/api/videos? q=dogs&location=37.42307,-122.08427&location-radius=5km * http://gdata.youtube.com/feeds/api/videos? q=dogs&location=37.42307,-122.08427!&location-radius=5km
Steps to migrate
If you implemented the location parameter according to the instructions in the protocol guide, then you do not need to do anything for this change.
However, if you would like to use the new location parameter functionality, then you need to modify your API requests so that the location parameter specifies geographic coordinates (latitude,longitude) that identify a particular location. Those requests will also need to specify a value for the location-radius parameter.
In API version 2, the vq parameter name has been changed to q. Your application uses this parameter to specify a search query term.
Steps to migrate
Change the vq parameter to q in any API requests that search for videos related to a specific search term. The example below shows this change in a request for videos related to the term "surfing."
API version 1: http://gdata.youtube.com/feeds/api/videos?vq=surfing API version 2: http://gdata.youtube.com/feeds/api/videos?q=surfing
The uploader parameter, which is new in API version 2, can be used to restrict search results to only include YouTube partner videos. A YouTube partner is a person or organization that has been accepted into and participates in the YouTube Partner Program.
Steps to migrate
Since you do not need to add support for the uploader parameter, you do not need to do anything for this change.
If you would like to use the uploader parameter, you may need to modify your search interface to allow users the option of only seeing results that include YouTube partner videos. You also need to add the uploader parameter to API requests when API responses should only contain partner videos.
As shown in the example below, the uploader parameter's value must be partner:
http://gdata.youtube.com/feeds/api/videos?q=surfing&uploader=partner
In API version 2, the <summary> tag replaces the <yt:description> tag, which has been deprecated. This change affects requests for sending messages.
This change also affects API responses, where the <summary> tag now appears in playlist feed entries and inbox (message) feed entries. In addition, in API version 1, the <yt:description> tag value for each playlist entry defaulted to the video's <media:description> value. However, in API version 2, the <summary> tag is only returned if the playlist entry has a custom description. Note that YouTube no longer enables playlist owners to set custom descriptions for playlist entries, but if a custom description already exists, the API response will specify it.
Steps to migrate
Change the <yt:description> tag to <summary> in all of the API requests listed above. The example below demonstrates how this change affects a request to add a playlist:
API version 1: <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <yt:description>A selection of sports highlights</yt:description> </entry> API version 2: <?xml version="1.0" encoding="UTF-8"?> <entry xmlns="http://www.w3.org/2005/Atom" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <title type="text">Sports Highlights Playlist</title> <summary>A selection of sports highlights</summary> </entry>
Modify your code to check the value of the <summary> tag instead of the <yt:description> tag in playlist and inbox feed entries.
In API version 2, the <content> tag replaces the <gd:feedLink> tag in playlists feeds and subscriptions feeds. This change affects API responses that contain playlist entries or subscription entries.
Steps to migrate
Modify your code to check the value of the <content> tag instead of the <gd:feedLink> tag in playlists feed entries and subscriptions feed entries.
The following code snippet shows how the change affects the format of a playlists feed entry:
API version 1: <entry> <id>http://gdata.youtube.com/feeds/users/andyland74/playlists/8BCDD04DE8F771B2</id> ... <gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist' href='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2'/> ... </entry> API version 2: <entry> <id>http://gdata.youtube.com/feeds/users/andyland74/playlists/8BCDD04DE8F771B2</id> ... <content type='application/atom+xml;type=feed' src='http://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2?v=2'/> </entry>
In API version 1, the <title> and <content> tags both used the type attribute. The <title> tag does not use this attribute in API version 2. In addition, the <content> tag, when it appears in an API version 2 comment feed, does not use this attribute.
Steps to migrate
Confirm that your code does not require the type attribute to be present or to have a particular value when processing the value of the <title> and <content> tags.
The <yt:countHint> tag, which is new in API version 2, appears in a playlists feed entry and identifies the number of videos in the corresponding playlist.
Steps to migrate
Since you do not need to add support for the <yt:countHint> tag, you do not need to do anything for this change.
The <yt:racy> tag has been fully deprecated in API version 2. Its replacement, the <media:rating> tag, was added to API version 1 in May 2008.
In API version 2, the <media:rating> tag also includes the country attribute, which identifies the country or countries where a video is considered to contain restricted content. Note that a feed will only include content that is restricted in all countries if your API request included the safeSearch parameter with a value of none (safeSearch=none).
Steps to migrate
If you have not already updated your application to check for the presence of the <media:rating> tag instead of the <yt:racy> tag, you will need to do so to migrate to API version 2.
You can also check the value of the <media:rating> tag's country attribute to determine whether a video contains content that is restricted in a particular country. If you know the user's location, you could choose to identify restricted content in search result lists or on pages where users watch videos.
The <media:credit> tag is a new tag that identifies the owner of a video. This tag appears in video, favorite video, playlist and inbox feed entries. In favorite video, playlist and inbox feed entries, the <media:credit> tag identifies a different user than the <author> tag.
Steps to migrate
When your website or application displays information about a favorite video, playlist feed entry or inbox message, it should not use the <author> tag value for that entry to identify the video owner. Instead, use the <media:credit> tag value to identify the video owner.