YouTube API Migration Guide

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

Contents

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 GData 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 GData-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. Please see the reference 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/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/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/videos/VIDEO_ID
    Get a video's video responses N/A /feeds/videos/VIDEO_ID/responses
    Get a video's comments videos.get_details&video_id=VIDEO_ID /feeds/VIDEO_ID/comments
  • The Legacy API returns only 10 comments with get_details.
  • The new API returns all comments and preserves parent/child relationship.
  • The YouTube data API currently does not require a developer ID, which is required for all Legacy API 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.

    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:

    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/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=updated as a parameter.

    http://gdata.youtube.com/feeds/videos?vq=monkey&orderby=updated&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/users/USERNAME
    Get a user's videos videos.list_by_user&user=USERNAME /feeds/users/USERNAME/uploads
    Get a user's favorites users.list_favorite_videos&user=USERNAME /feeds/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/users/USERNAME/playlists
  • The Legacy API returns only 10 comments with get_details.
  • The new API returns all comments and preserves parent/child relationship.
  • Get a user's subscriptions N/A /feeds/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/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/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/playlists/PLAYLIST_ID
    Get a user's playlists N/A /feeds/users/USERNAME/playlists

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

    http://youtube.com/dev_api_ref?m=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/playlists/PLAYLIST_ID

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

    We're committed to continued development of the new GData-based API, including adding new features like upload and other write calls. If you have any feature requests or bug reports, feel free to file them in the GData issue tracker. We're also adding support for the YouTube API in the GData client libraries. Java is already supported, and PHP and Python are on their way. If you have any more questions, post them in the discussion forum. Happy coding!

    Back to top

    Last modified: