My favorites | English | Sign in

Sign up for Google I/O 2010 today!

YouTube APIs and Tools

YouTube logo

YouTube Data API Migration Guide

Overview

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

Who needs to upgrade?

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.

Migrating from version 1 to version 2

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

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

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:

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.

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

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

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:
  * 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.

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:
    http://gdata.youtube.com/feeds/api/videos?vq=surfing
    
    API version 2:
    http://gdata.youtube.com/feeds/api/videos?q=surfing
    

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:

    http://gdata.youtube.com/feeds/api/videos?q=surfing&uploader=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>
    
  • Modify your code to check the value of the <summary> tag instead of the <yt:description> tag in playlist and inbox feed entries.

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

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

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.

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.