Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.
Overview
This document explains how to migrate your website or application to work with version 2 of the YouTube Data API. It touches on some of the new features available in version 2 of the API and explains other differences between version 2 and version 1.
Who needs to upgrade?
YouTube API version 1 has been deprecated. If your application is still using API version 1, you should upgrade to version 2.
Migrating from version 1 to version 2
The following sections describe some a few of the major 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
- Specify an API version in all API requests
- Specify a projection in all API requests
- Ensure you do not use <id> tag value to identify feed URLs
- Replace racy parameter with safeSearch parameter
- Update location parameter usage
- Update "vq" parameter to "q"
- Add support for uploader parameter
- Replace <yt:description> with <summary>* – this change also affects API responses
Handling API responses
- Replace <gd:feedLink> with <content> in playlists and subscriptions feeds
- <title> and <content> tags do not use type attribute
- Display the number of videos in playlists
- Replace <yt:racy> with <media:rating>
- Add support for <media:credit> tag in playlists and subscriptions feeds
Submitting API requests
Specify an API version in all API requests
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-VersionHTTP 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 theGData-VersionHTTP 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: https://gdata.youtube.com/feeds/api/users/default
Tags in API response:
<link rel='self' type='application/atom+xml'
href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers'/>
<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.favorites'
href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/favorites'
countHint='4'/>
<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.contacts'
href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/contacts'
countHint='1'/>
API version 2:
API request URL: https://gdata.youtube.com/feeds/api/users/default?v=2
Tags in API response:
<link rel='self' type='application/atom+xml'
href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers?v=2'/>
<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.favorites'
href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/favorites?v=2'
countHint='4'/>
<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#user.contacts'
href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/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.
The Java client library automatically sets the GData-Version request header for each API request.
The .NET client library automatically sets the GData-Version request header for each API request.
If you are using the PHP client library, use the setMajorProtocolVersion function to set a version for either a service class, a feed or an entry:
// Assuming that $yt is a valid Zend_Gdata_YouTube object $yt->setMajorProtocolVersion(2);
Please see the Setting the API version section of the PHP Developer's Guide for more information.
Specify a projection in all API requests
Every API request in version 2 must specify a projection. The following example shows how a projection appears in an API request URL:
https://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.
Ensure you do not use <id> tag value to identify feed URLs
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>https://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.
Replace racy parameter with safeSearch parameter
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 you do specify a value for the racy parameter, please follow the additional instructions below:
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.
- Change the racy parameter value include to the equivalent safeSearch parameter value, which is none.
- Change the racy parameter value exclude to either moderate or strict, which are comparable safeSearch parameter values.
-
Replace references to
getIncludeRacy()withgetSafeSearch(). -
Replace references to
setIncludeRacy(true)withsetSafeSearch(YouTubeQuery.SafeSearch.NONE). -
Replace references to
setIncludeRacy(false)with eithersetSafeSearch(YouTubeQuery.SafeSearch.MODERATE)orsetSafeSearch(YouTubeQuery.SafeSearch.STRICT). See the safeSearch parameter definition and the JavaDoc for the YouTubeQuery class for more information about these values.
-
Replace references to
query.Racywithquery.SafeSearch. -
Replace references to
query.Racy = "include"withquery.SafeSearch = YouTubeQuery.SafeSearchValues.None. -
Replace references to
query.Racy = "exclude"with eitherquery.SafeSearch = YouTubeQuery.SafeSearchValues.Moderateorquery.SafeSearch = YouTubeQuery.SafeSearchValues.Strict. See the safeSearch parameter definition for more information about these values.
-
Replace references to
$query->getRacy()with$query->getSafeSearch(). -
Replace references to
$query->setRacy('include')with$query->setSafeSearch('none'). -
Replace references to
$query->setRacy('exclude')with either$query->setSafeSearch('moderate')or$query->setSafeSearch('strict'). See the safeSearch parameter definition for more information about these values.
Update location parameter usage
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:
* https://gdata.youtube.com/feeds/api/videos?vq=dogs&location;=
* https://gdata.youtube.com/feeds/api/videos?vq=dogs&location;=!
API version 2
* https://gdata.youtube.com/feeds/api/videos?q=dogs&location;=
* https://gdata.youtube.com/feeds/api/videos?q=dogs&location;=!
* https://gdata.youtube.com/feeds/api/videos?
q=dogs&location;=37.42307,-122.08427&location-radius;=5km
* https://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.
If you are using the Java client library, use the setLocation(GeoRssWhere where) and setLocationRadius(java.lang.String locationRadius) methods to use this new functionality. Note that you still need to call setLocationRestrict(true), which was also available in API version 1, if you want to ensure that each video in the response has coordinates that can be plotted on a map.
If you are using the .NET client library, use the query.Location and query.LocationRadius methods to use this new functionality. Note that you still need to call query.LocationRestrict, which was also available in API version 1, if you want to ensure that each video in the response has coordinates that can be plotted on a map.
Update "vq" parameter to "q"
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: https://gdata.youtube.com/feeds/api/videos?vq=surfing API version 2: https://gdata.youtube.com/feeds/api/videos?q=surfing
Replace references to the setVideoQuery() method with references to the setFullTextQuery() method.
Replace references to the query.VQ method with the query.Query method.
If you are using the PHP client library, you do not need to make any updates for this change since version 2 of the client library uses the same method name for specifying the query term as version 1.
Add support for uploader parameter
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:
https://gdata.youtube.com/feeds/api/videos?q=surfing&uploader;=partner
If you are using the Java client library, use the setUploader() method to set the uploader parameter value.
query.setUploader(YouTubeQuery.Uploader.PARTNER);
If you are using the .NET client library, use the query.Uploader method to set the uploader parameter value.
query.Uploader = "partner";
If you are using the PHP client library, use the $query->setUploader method to set the uploader parameter value.
$query->setUploader('partner');
Replace <yt:description> with <summary>
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>
In addition, modify your code to check the value of the <summary> tag instead of the <yt:description> tag in playlist and inbox feed entries.
Replace references to the getDescription() method with getSummary().getPlainText(). In addition, note that the getSummary() method may return a null value, in which case you should call getMediaGroup().getDescription() to retrieve the description for a playlist entry.
In addition, replace references to setDescription("foo") method with the setSummary(new PlainTextConstruct("foo")) method.
Replace references to the entry.Description method with entry.Summary.Text. In addition, note that the entry.Summary.Text method may return a null value, in which case you should call entry.Media.Description.Value to retrieve the description for a playlist entry.
if (playlistEntry.Summary.Text == null)
{
Console.WriteLine("Description: " + playlistEntry.Media.Description.Value);
}
else
{
Console.WriteLine("Description: " + playlistEntry.Summary.Text);
}
In addition, replace references to entry.Description = "foo" with entry.Summary.Text = "foo".
Replace references to the getDescription()->text method with getSummary()->text. In addition, if the getSummary()->text method returns a null value for a playlist entry, you should call getMediaGroup()->getMediaDescription()->text to retrieve the description for that entry.
In addition, to send messages, replace $newEntry->description = $yt->newDescription('foo') with $newEntry->summary = $yt->newSummary('foo')
Handling API responses
Replace <gd:feedLink> with <content> in playlists and subscriptions feeds
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.
- In a playlists feed entry, the <content> tag specifies the feed URL from which you would request information about a specific playlist.
- In a subscriptions feed entry, the <content> tag specifies the feed URL from which you would retrieve videos associated with a particular subscription.
The following code snippet shows how the change affects the format of a playlists feed entry:
API version 1:
<entry>
<id>https://gdata.youtube.com/feeds/users/GoogleDevelopers/playlists/8BCDD04DE8F771B2</id>
...
<gd:feedLink rel='http://gdata.youtube.com/schemas/2007#playlist'
href='https://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2'/>
...
</entry>
API version 2:
<entry>
<id>tag:youtube.com,2008:user:GoogleDevelopers:playlist:8BCDF04DE8F771B2</id>
...
<content type='application/atom+xml;type=feed'
src='https://gdata.youtube.com/feeds/api/playlists/8BCDD04DE8F771B2?v=2'/>
</entry>
To retrieve a playlist feed URL from a playlists feed entry or to retrieve a list of subscription videos from a subscriptions feed entry, use the entry.getFeedUrl() method instead of the entry.getFeedLink().getHref() method.
To retrieve a playlist feed URL from a playlists feed entry or to retrieve a list of subscription videos from a subscriptions feed entry, use entry.Content.Src.Content instead of entry.FeedLink.Href.
If you are using the PHP client library, use the getContent->getSrc() method instead of the getFeedLink() method to retrieve either a playlist feed URL from a playlists feed entry or a list of subscription videos from a subscriptions feed entry.
<title> and <content> tags do not use type attribute
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.
Display the number of videos in playlists
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.
To retrieve the <yt:countHint> value using the Java client library, call the getCountHint() method on the playlist entry object:
entry.getCountHint();
To retrieve the <yt:countHint> value using the .NET client library, call entry.CountHint on the PlaylistsEntry object:
Console.WriteLine("Number of entries: " + entry.CountHint);
To retrieve the <yt:countHint> value using the PHP client library, call $playlistListEntry->getCountHint()->text on the PlaylistListEntry object:
echo "Number of entries: " . $playlistListEntry->getCountHint()->text;
Replace <yt:racy> with <media:rating>
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.
If you are using the Java client library, you can use the following code to determine whether a video contains restricted content:
for (YouTubeMediaRating mediaRating : mediaGroup.getYouTubeRatings()) {
System.out.println("Video restricted in the following countries: " +
mediaRating.getCountries().toString());
}
If you are using the .NET client library, you can use the following code to determine whether a video contains restricted content:
if (entry.Media.Rating != null)
{
Console.WriteLine("Restricted in: " + entry.Media.Rating.Country);
}
If you are using the PHP client library, you can use the following code to determine whether a video contains restricted content:
$mediaRating = $videoEntry->mediaGroup->getMediaRating();
if ($mediaRating) {
echo 'Video Restricted in: ' . $mediaRating->getCountry() . "\n";
}
Add support for <media:credit> tag for favorite videos, playlists and subscriptions feeds
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.
If you are using the Java client library, you can use the following code to identify the video owner for a video, favorite video, playlist entry, or video sent from one user to another:
entry.getMediaGroup().getUploader();
If you are using the .NET client library, you can use the following code to identify the video owner for a video, favorite video, playlist entry, or video sent from one user to another:
entry.Media.Credit.Value;
The following code demonstrates how to extract information from the <media:credit> tag's information from a PlaylistVideoEntry in the PHP client library:
// the <media:credit> element indicates whether a partner uploaded the video
$mediaCredit = $playlistVideoEntry->getMediaCredit();
if ($mediaCredit) {
// get the name of the partner
print 'Video originally uploaded by ' . $mediaCredit->text . "\n";
// currently, the only supported role is 'uploader'
print 'Media credit role: ' . $mediaCredit->getRole() . "\n";
// if the yt:type attribute is present, then the video was uploaded
// by a YouTube partner
print 'Media credit type: ' . $mediaCredit->getYTtype() . "\n";
}
The PHP client library does not yet provide helper methods to extract this information for videos, favorite videos, or videos sent from one user to another.
