My favorites ▼ | English ▼ | Sign in

Sign up for Google I/O 2010 today!

YouTube APIs and Tools

YouTube logo

Migration Guide

The newest iteration of the YouTube API is based on the Google Data protocol. This document is intended to help developers migrate their website or application to the new YouTube API.

Contents

  1. Introduction
    1. Overview
    2. Who needs to upgrade?
    3. What's the upgrade timeline?
  2. What's the difference between the old API and the new API?
  3. What's next?

Introduction

Overview

YouTube has become the internet's most popular destination for online video. With the release of the original REST/XML-RPC API in 2005, thousands of developers helped spread YouTube videos, uploaded from users all around the world, to even more computer screens. Now that the site is more mature, we want to provide a robust, full featured API to developers. We decided to rewrite the API and standardize on the existing Google Data protocol. There are many reasons for this move, including better scalability and more developer resources. This document will help you get an idea of what's new, and what you need to do to migrate your website or application. The reference guide and the language-specific developer guides are also excellent resources.

Who needs to upgrade?

Everyone that uses the Legacy API should upgrade to the Google Data-based API. New features will no longer be integrated into the Legacy API, and only critical bugs will receive attention.

What's the upgrade timeline?

The Legacy API will continue to be functional through August 30th, 2008. After that, its existence is not guaranteed. We encourage you to switch earlier rather than later, as issues that come up with the Legacy API will be low priority.

What's the difference between the old API and the new API?

The tables below lay out the differences in common operations, and are not meant to be exhaustive. In particular, new functionality like uploading videos won't be covered at all, since it wasn't available in the Legacy API. Please see the protocol guide for detailed information.

Video Feeds

Operation Legacy API YouTube Data API Notes/Comments
Search through YouTube's index videos.list_by_tag&tag="SEARCH TERMS" /feeds/api/videos?vq="SEARCH TERMS"
  • The Legacy API returns a relevance search
  • The new API supports filters like sort by relevance, upload time, rating, and view count.
    		•
    Search through a particular category videos.list_by_category_and_tag&tag="SEARCH TERMS"&category_id=CATEGORY_ID /feeds/api/videos/-/CATEGORY_NAME
  • The Legacy API does not allow for unrestricted category listing of videos.
  • The new category feeds support this, as well as multiple category restrictions.
    		•
    Get a video's metadata videos.get_details&video_id=VIDEO_ID /feeds/api/videos/VIDEO_ID
    Get a video's video responses N/A /feeds/api/videos/VIDEO_ID/responses
    Get a video's comments videos.get_details&video_id=VIDEO_ID /feeds/api/VIDEO_ID/comments
  • The Legacy API returns only 10 comments with get_details.
  • The new API returns a maximum of 1000 comments and preserves the parent/child relationship.
    		•

    The YouTube Data API requires a developer key for authenticated calls, but not for unauthenticated calls. The Legacy API requires a developer ID for all calls. Discussion of additional functionality in the form of parameters and filters follows.

    Paging is available in both the Legacy API and the new API. The new paging parameters are detailed below.

    • start-index - indicates which entry to start listing results; this does not correspond to the Legacy API's page parameter, which indicates which page of results to show
    • max-results - indicates maximum number of entries to show; this corresponds to the Legacy API's per_page parameter

    For example, if you were to parse 1000 results 50 at a time, the beginning start-index would equal 1, and the max-results would equal 50. The next iteration, your start-index would equal start-index + max-results, 51. In the Legacy API, the page parameter would start at 1, and the per_page would equal 50. The page parameter then increments to 2, and so on, for all subsequent iterations.

    The YouTube Data API adds support for the following query parameters:

    • vq - full text search query (searches content such as video title, description, tags, etc.)
    • format - restricts search to videos available in specific formats, (for example, format=0 is Flash, which all videos are available in); see the reference guide for available formats
    • alt - controls output format (RSS, Atom, JSON), as described in http://code.google.com/apis/gdata/reference.html#Queries
    • author - restricts search to videos uploaded by a specific YouTube user, as described in http://code.google.com/apis/gdata/reference.html#Queries
    • orderby - order in which items should be returned, can be relevance (default), published, viewCount, rating
    • racy - add racy=include to include restricted content as flagged by the community; defaults to exclude

    A search for videos related to the word "monkey," with paging, would look like this in the Legacy API and YouTube Data API, respectively.

    http://www.youtube.com/api2_rest?method=youtube.videos.list_by_tag&dev_id=DEV_ID&tag=monkey&page=1&per_page=50
    http://gdata.youtube.com/feeds/api/videos?vq=monkey&start-index=1&max-results=50

    A common feature request has been to sort a video feed by the most recent videos. To do this with the YouTube Data API, add orderby=published as a parameter.

    http://gdata.youtube.com/feeds/api/videos?vq=monkey&orderby=published&start-index=1&max-results=50

    User Feeds

    Operation Legacy API YouTube Data API Notes/Comments
    Get a user's profile users.get_profile&user=USERNAME /feeds/api/users/USERNAME
    Get a user's videos videos.list_by_user&user=USERNAME /feeds/api/users/USERNAME/uploads
    Get a user's favorites users.list_favorite_videos&user=USERNAME /feeds/api/users/USERNAME/favorites
  • The Legacy API returns a maximum of 10 of the user's favorites
  • The new API returns all videos in a user's favorites with paging.
    		•
    Get a user's playlists N/A /feeds/api/users/USERNAME/playlists
    Get a user's subscriptions N/A /feeds/api/users/USERNAME/subscriptions

    Listing a particular user's videos using the Legacy API and new API:

    http://www.youtube.com/api2_rest?method=youtube.videos.list_by_user&dev_id=DEV_ID&user=USERNAME
    http://gdata.youtube.com/feeds/api/users/USERNAME/uploads

    Many of the filters that apply to the new video feeds can be applied to user feeds. For example, you can perform a text search through a user's uploaded videos.

    http://gdata.youtube.com/feeds/api/users/USERNAME/uploads?vq="dogs on bicycles"

    Please see the reference guide for more details on which query parameters apply to each of the feeds.

    Playlist Feeds

    Operation Legacy API YouTube data API Notes/Comments
    Get videos in a playlist videos.list_by_playlist&id=PLAYLIST_ID /feeds/api/playlists/PLAYLIST_ID
    Get a user's playlists N/A /feeds/api/users/USERNAME/playlists

    Listing the videos in a particular playlist using the Legacy API would look like this:

    http://youtube.com/api2_rest?method=youtube.videos.list_by_playlist&dev_id=DEV_ID&id=PLAYLIST_ID

    Using the YouTube Data API, the call would look like this:

    http://gdata.youtube.com/feeds/api/playlists/PLAYLIST_ID

    Please see the reference guide for more details on which query parameters apply to each of the feeds.

    What's next?

    We're committed to continued development of the new Google Data-based API, and we recently released expanded functionality, including upload and other write calls. The developer resources that are available continue to grow — for a current list of supported libraries and sample code, see here. If you have any questions, feedback, or bug reports, post them in the discussion forum. Happy coding!

    Back to top