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.

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.

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), updated, 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/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.

What's next?

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!

YouTube Data API