YouTube Data API Developer's Guide: Protocol

  
 

The YouTube data API allows client applications to view YouTube content in the form of Google data API ("GData") feeds. Your client application can use the YouTube data API feeds to fetch video feeds, comments, responses, and playlists, as well as query for videos that match particular criteria.

Contents

Audience

This document is intended for programmers who want to write client applications that can interact with YouTube. It provides examples of basic operations using raw HTTP and XML, with explanations.

After reading this document, if you don't want to write code that interacts with the raw feeds, you may wish to learn more about interacting with the API using our client libraries by reading the language-specific examples found on the other tabs at the top of this document.

For YouTube data API reference information, see the reference guide.

This document assumes that you understand the general ideas behind the Google data APIs protocol.

Since none of the feeds described in this document require authentication, you can try them out using your favorite browser. If you're using a UNIX system and want to see the raw feeds, you may find the UNIX command-line utilities curl or wget useful. For more information, see the manual pages for these utilities.

Retrieving video feeds

The YouTube data API provides numerous feeds that return a list of videos, such as standard feeds, related videos, video responses, user's uploads, and user's favorites. For example, the user's-uploads feed returns all videos uploaded by a specific user. See the reference guide for a detailed list of all feeds. All the feeds described in this section are "video feeds"—feeds that return lists of videos.

The collection of elements (contained in an <entry> element) that together describe a video is called the Video "kind." An entry of the Video kind, also called a Video entry, has the following <category> element:

<category scheme="http://schemas.google.com/g/2005#kind"
  term="http://gdata.youtube.com/schemas/2007#video"/>

For more information about other GData kinds, see the "Common Elements" document. The YouTube data API reference guide includes a diagram that shows the relationships between the various video feeds, and lists their corresponding GData kinds.

To retrieve the list of videos uploaded by a user named "liz," send an HTTP GET to the following URL. Querying a YouTube feed does not require authentication.

GET http://gdata.youtube.com/feeds/users/liz/uploads

When you send that GET request, YouTube returns an HTTP 200 OK status code and a feed containing all the videos that match the request.

Each entry in the response feed represents a video uploaded by the user. Here is a typical entry:

<entry>
  <id>http://gdata.youtube.com/feeds/videos/ZTUVgYoeN_o</id>

  <published>2007-02-16T20:22:57.000Z</published>
  <updated>2007-02-16T20:22:57.000Z</updated>
 
  <category scheme="http://schemas.google.com/g/2005#kind"
    term="http://gdata.youtube.com/schemas/2007#video"/>

  <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat"
    term="Steventon"/>
  <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat"
    term="walk"/>
  <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat"
    term="Darcy"/>

  <category scheme="http://gdata.youtube.com/schemas/2007/categories.cat"
    term="Entertainment" label="Entertainment"/>

  <title type="text">My walk with Mr. Darcy</title>

  <content type="html"><div ... html content trimmed ... ></content>

  <link rel="self" type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/ZTUVgYoeN_o"/>
  <link rel="alternate" type="text/html"
    href="http://www.youtube.com/watch?v=ZTUVgYoeN_o"/>

  <link rel="http://gdata.youtube.com/schemas/2007#video.responses"
    type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/ZTUVgYoeN_o/responses"/>
  <link rel="http://gdata.youtube.com/schemas/2007#video.ratings"
    type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/ZTUVgYoeN_o/ratings"/>
  <link rel="http://gdata.youtube.com/schemas/2007#video.complaints"
    type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/ZTUVgYoeN_o/complaints"/>
  <link rel="http://gdata.youtube.com/schemas/2007#video.related"
    type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/ZTUVgYoeN_o/related"/>

  <author>
    <name>Elizabeth Bennet</name>
    <uri>http://gdata.youtube.com/feeds/users/liz</uri>
  </author>

  <media:group>
    <media:title type="plain">My walk with Mr. Darcy</media:title>
    <media:description
      type="plain">Walk in the beautiful gardens of Steventon</media:description>
    <media:keywords>Steventon, walk, Darcy</media:keywords>
    <yt:duration seconds="79"/>
    <media:category label="Entertainment"
      scheme="http://gdata.youtube.com/schemas/2007/categories.cat">Entertainment</media:category>
    <media:content
      url="rtsp://rtsp.youtube.com/youtube/videos/ZTUVgYoeN_o/video.3gp"
      type="video/3gpp" medium="video" isDefault="true" expression="full"
      duration="215" yt:format="1"/>
    <media:player url="http://www.youtube.com/watch?v=ZTUVgYoeN_o"/>
    <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_o/2.jpg"
      height="97" width="130" time="00:00:03.500"/>
    <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_o/1.jpg"
      height="97" width="130" time="00:00:01.750"/>
    <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_o/3.jpg"
      height="97" width="130" time="00:00:05.250"/>
    <media:thumbnail url="http://img.youtube.com/vi/ZTUVgYoeN_o/0.jpg"
      height="240" width="320" time="00:00:03.500"/>
  </media:group>

  <yt:statistics viewCount="93"/>

  <gd:feedLink rel="comments"
    href="http://gdata.youtube.com/feeds/videos/ZTUVgYoeN_o/comments"/>
</entry>

Searching for videos

The Google data APIs let you request a set of entries that match specified criteria, such as requesting entries in a specific category, or published by a particular author. You search for videos using the videos feed:

GET http://gdata.youtube.com/feeds/videos

The following is a list of the most common query parameters used in searches:

alt
The format of feed to return, such as atom (the default), rss, or json.
orderby
The order in which to list entries, such as relevance (the default for the videos feed) or viewCount.
start-index
The 1-based index of the first result to be retrieved (for paging).
max-results
The maximum number of entries to return at one time.
/-/categories
The categories and/or tags to use in filtering the feed results. For example, feedURL/-/fritz/laurie returns all entries that are tagged with both of the user-defined tags fritz and laurie.
vq
A search query term. Searches for the specified string in all video metadata, such as titles, tags, and descriptions.
format
A specific video format. For example, format=1 restricts search results to videos for mobile devices.

For example, the following request returns all mobile videos (format=1) that contain the word "cat" in their metadata, starting with the 10th video, displaying 20 videos per page, ordered in decreasing order by view count, in RSS format:

http://gdata.youtube.com/feeds/videos?format=1&vq=cat&start-index=10&max-results=20&orderby=viewCount&alt=rss

For more information about query parameters, see the YouTube Data API Reference Guide and the Google Data APIs Reference Guide.

Note: By default, the entries in the videos feed are ordered by relevance, with the most relevant results appearing first in the feed. The default order for the other feeds is arbitrary.

Searching for videos using categories and keywords

To get videos in a specific category, and/or videos that have specific user-defined tags (also known as "keywords"), send a request of the following form:

GET http://gdata.youtube.com/feeds/videos/-/categories_or_tags

For example, to get all Comedy videos that have the keyword "dog", send the following request:

GET http://gdata.youtube.com/feeds/videos/-/Comedy/dog

The returned entries look like the following:

<entry>
  <id>http://dev.gdata.youtube.com/feeds/videos/ClBli0YWnCs</id>

  <published>2006-11-10T15:30:35.000Z</published>
  <updated>2006-11-10T15:30:35.000Z</updated>

  <category scheme="http://gdata.youtube.com/schemas/2007/categories.cat"
    term="Comedy" label="Comedy"/>
  <category scheme="http://gdata.youtube.com/schemas/2007/keywords.cat"
    term="dog"/>
  <category scheme="http://schemas.google.com/g/2005#kind"
    term="http://gdata.youtube.com/schemas/2007#video"/>

  ...

</entry>

Note that each returned video is a "Comedy" from the perspective of the categories.cat category, and is also a "dog" from the perspective of the keywords.cat category .

For more details on category search, see the reference guide examples.

Phrase search

A text search (using the vq query parameter) for Elizabeth Bennet returns all videos that contain the words "Elizabeth" or "Bennet" anywhere in the metadata (title, tags, description, and so on). To search for a multi-word phrase, enclose the words in double quotes (and URL-encode the quotation marks). The following example returns all videos that contain the phrase "Elizabeth Bennet":

GET http://gdata.youtube.com/feeds/videos?vq=%22Elizabeth+Bennet%22

Retrieving standard feeds

The YouTube data API currently provides four standard feeds: "Most Viewed", "Top Rated", "Recently Featured", and "Watch On Mobile". These feeds are site-wide, not user specific. The URLs of all standard feeds start with http://gdata.youtube.com/feeds/standardfeeds/, followed by the feed's identifier:

Standard feeds support the time query parameter. For example, you can retrieve today's top rated videos using:

GET http://gdata.youtube.com/feeds/standardfeeds/top_rated?time=today

Retrieving videos uploaded by a user

To query all videos uploaded by a specific user, add the author parameter to the request URL:

GET feedURL?author=liz

For example, to get all videos uploaded by user liz, send the following HTTP request:

GET http://gdata.youtube.com/feeds/videos?author=liz

The above request returns the same results as the following:

GET http://gdata.youtube.com/feeds/users/liz/uploads

Retrieving a user's favorite videos

YouTube users can choose to mark videos they watch as favorites. The list of these videos for each user is given by the user's favorites feed. The following request displays liz's favorites:

GET http://gdata.youtube.com/feeds/users/liz/favorites

Retrieving video responses for a video

YouTube users may choose to respond to a video with another video. The list of all video responses for a specific video is given by that video's responses feed:

GET http://gdata.youtube.com/feeds/videos/03YbknYlJK0/responses

Note that the URL contains the identifier of the video for which the responses are requested.

Retrieving video comments

Most of the video entries have comments, some of them a considerably large number of comments. In order to keep the size of the videos feed reasonably small, the comments are not returned directly inside the video entries, but rather as a feed link:

<gd:comments>
  <gd:feedLink
    href="http://gdata.youtube.com/feeds/videos/2cdgTWitj_o/comments"/>
</gd:comments>

Each video has a comment feed, with entries of the Comment kind:

GET http://gdata.youtube.com/feeds/videos/2cdgTWitj_o/comments

Each comment has an author, a title, and content. YouTube users may respond to a comment with another comment. This hierarchical structure is preseverd by adding an optional in-reply-to link, pointing to the comment that is being replied to:

<link rel="http://gdata.youtube.com/schemas/2007#in-reply-to"
type="application/atom+xml" href="http://gdata.youtube.com/feeds/videos/2cdgTWitj_o/comments/978A9E10911314AC"/>

Playlist feeds

Besides the feeds that return videos, the YouTube data API provides feeds that return information about users (profile, playlists, subscriptions, friends, and so on.). The complete list of feeds is enumerated in the reference guide. These feeds are also accessed using a GET request, and they also don't require authentication.

Retrieving the playlists of a user

To retrieve a list of a user's playlists, send a GET request to the user's playlists feed:

GET http://gdata.youtube.com/feeds/users/liz/playlists

The response contains entries of the Playlist Link kind, with each entry describing a public playlist (title, description, author, and so on), and providing a feed link to the actual list of videos:

<entry>
  <id>http://gdata.youtube.com/feeds/users/liz/playlists/ABCDEFABCDEFABCDEF</id>
  <published>2007-07-08T09:48:28.000-07:00</published>
  <updated>2007-07-08T09:48:30.000-07:00</updated>
  <category scheme="http://gdata.youtube.com/schemas/2007/tags.cat" term="ballroom"/>
  <category scheme="http://gdata.youtube.com/schemas/2007/tags.cat" term="dance"/>
  <category scheme="http://schemas.google.com/g/2005#kind"
    term="http://gdata.youtube.com/schemas/2007#playlistLink"/>
  <title type="text">Dance</title>
  <content type="text">Dance routines, shows.</content>
  <link rel="alternate" type="text/html"
    href="http://www.youtube.com/view_play_list?p=45C563323B344971"/>
  <link rel="self" type="application/atom+xml"
    href="http://dev.gdata.youtube.com/feeds/users/liz/playlists/45C563323B344971"/>
  <author>
    <name>liz</name>
    <uri>http://dev.gdata.youtube.com/feeds/users/liz</uri>
  </author>
  <yt:description>Dance routines, shows.</yt:description>
  <gd:feedLink rel="http://gdata.youtube.com/schemas/2007#playlist"
    href="http://dev.gdata.youtube.com/feeds/playlists/45C563323B344971"/>
</entry>

Note that, like videos, playlists can have tags (keywords) attached to them, so you can search playlists by tag.

Retrieving a playlist

To retrieve a specific playlist that appears in a list of playlists, follow the href link supplied in the playlist entry's <gd:feedLink> element. The playlist itself consists of a list of videos, each with an optionally modified title or description:

GET http://gdata.youtube.com/feeds/playlists/45C563323B344971

Even though the entries in the playlists are videos, they are of the Playlist kind, rather than the Video kind, because the owner of the playlist may choose to define their own title and description for each video in the playlist. If available, the user-selected title appears in the <atom:title> element, replacing the original video's title. The video's original title appears in the <media:title> element. The description of the video in the playlist (if changed) appears inside a <yt:description> tag. The entry below shows an example of a Playlist entry with both its title and description altered by the user who defined the playlist:

<entry>
  <id>http://gdata.youtube.com/feeds/playlists/45C563323B344971/f8bcc0d63a08ada4</id>
  <updated>2007-08-23T20:11:41.252Z</updated>

  <category scheme="http://schemas.google.com/g/2005#kind"
    term="http://gdata.youtube.com/schemas/2007#playlist"/>

  <title type="text">Customized title</title>

  <content type="html">...</content>

  <link rel="alternate" type="text/html"
    href="http://www.youtube.com/watch?v=i2xMvKOLzYM"/>
  <link rel="http://gdata.youtube.com/schemas/2007#video.responses"
    type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/i2xMvKOLzYM/responses"/>
  <link rel="http://gdata.youtube.com/schemas/2007#video.ratings"
    type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/i2xMvKOLzYM/ratings"/>
  <link rel="http://gdata.youtube.com/schemas/2007#video.complaints"
    type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/i2xMvKOLzYM/complaints"/>
  <link rel="http://gdata.youtube.com/schemas/2007#video.related"
    type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/i2xMvKOLzYM/related"/>
  <link rel="related" type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/videos/i2xMvKOLzYM"/>
  <link rel="self" type="application/atom+xml"
    href="http://gdata.youtube.com/feeds/playlists/45C563323B344971/f8bcc0d63a08ada4"/>

  <author>
    <name>Fitzwilliam Darcy</name>
    <uri>http://gdata.youtube.com/feeds/users/darcy</uri>
  </author>

  <media:group>
    <media:title type="plain">Original title</media:title>
    <media:description type="plain">Original description</media:description>
    <media:keywords>Dance</media:keywords>
    <yt:duration seconds="243"/>
    <media:category label="Entertainment"
      scheme="http://gdata.youtube.com/schemas/2007/categories.cat">Entertainment</media:category>
    <media:content url="http://www.youtube.com/v/i2xMvKOLzYM"
      type="application/x-shockwave-flash" medium="video" isDefault="true"
      expression="full" duration="243" yt:format="5"/>
    <media:player url="http://www.youtube.com/watch?v=i2xMvKOLzYM"/>
    <media:thumbnail url="http://img.youtube.com/vi/i2xMvKOLzYM/2.jpg"
      height="97" width="130" time="00:02:01.500"/>
  </media:group>

  <yt:statistics viewCount="4533"/>

  <gd:rating min="1" max="5" numRaters="7" average="5.00"/>

  <gd:comments>
    <gd:feedLink href="http://gdata.youtube.com/feeds/videos/i2xMvKOLzYM/comments"/>
  </gd:comments>

  <yt:description>Customized description</yt:description>

  <yt:position>1</yt:position>
</entry>

You can think of Playlist entries as an extension of Video entries that may additionally contain a <yt:position> and a <yt:description> tag.

Retrieving a list of a user's subscriptions

To retrieve a list of a the subscriptions belonging to user liz, send a GET request to the following URL:

http://gdata.youtube.com/feeds/users/liz/subscriptions

As described in the reference guide, subscriptions can be of three types: channel subscription, tag subscription, or favorites subscription. Entries in the subscriptions feed are of the Subscription kind, with the type of subscription being subscriptiontypes.cat:

http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat

Retrieving a user's profile

You can view user darcy's profile by sending the following GET request:

GET http://gdata.youtube.com/feeds/users/darcy

The response is an entry of the User Profile kind:

<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:gd="http://schemas.google.com/g/2005" 
    xmlns:yt="http://gdata.youtube.com/schemas/2007">

  <id>http://dev.gdata.youtube.com/feeds/users/darcy</id>

  <published>2006-03-19T11:35:56.000-08:00</published>
  <updated>2007-08-13T12:37:03.000-07:00</updated>

  <category scheme="http://schemas.google.com/g/2005#kind"
    term="http://gdata.youtube.com/schemas/2007#userProfile"/>

  <title type="text">Darcy</title>

  <link rel="alternate" type="text/html"
    href="http://www.youtube.com/profile?user=darcy"/>
  <link rel="self" type="application/atom+xml"
    href="http://dev.gdata.youtube.com/feeds/users/darcy"/>

  <author>
    <name>Fitzwilliam Darcy</name>
    <uri>http://dev.gdata.youtube.com/feeds/users/darcy</uri>
  </author>

  <yt:age>32</yt:age>
  <yt:username>darcy</yt:username>
  <yt:books>Pride and Prejudice</yt:books>
  <yt:company>Self employed</yt:company>
  <yt:hobbies>Reading, arguing with Liz</yt:hobbies>
  <yt:hometown>Steventon</yt:hometown>
  <yt:location>Longbourn in Hertfordshire, Pemberley in Derbyshire</yt:location>
  <yt:movies>Pride and Prejudice, 2005</yt:movies>
  <yt:music>Air Con Varizzioni, The Pleasure of the Town</yt:music>
  <yt:occupation>Gentleman</yt:occupation>
  <yt:school>Home schooling</yt:school>
  <yt:gender>m</yt:gender>
  <yt:relationship>taken</yt:relationship>

  <gd:feedLink rel="http://gdata.youtube.com/schemas/2007#user.favorites"
    href="http://dev.gdata.youtube.com/feeds/users/liz/favorites"/>
  <gd:feedLink rel="http://gdata.youtube.com/schemas/2007#user.contacts"
    href="http://dev.gdata.youtube.com/feeds/users/liz/contacts"/>
  <gd:feedLink rel="http://gdata.youtube.com/schemas/2007#user.inbox"
    href="http://dev.gdata.youtube.com/feeds/users/liz/inbox"/>
  <gd:feedLink rel="http://gdata.youtube.com/schemas/2007#user.playlists"
    href="http://dev.gdata.youtube.com/feeds/users/liz/playlists"/>
  <gd:feedLink rel="http://gdata.youtube.com/schemas/2007#user.subscriptions"
    href="http://dev.gdata.youtube.com/feeds/users/liz/subscriptions"/>
  <gd:feedLink rel="http://gdata.youtube.com/schemas/2007#user.uploads"
    href="http://dev.gdata.youtube.com/feeds/users/liz/uploads"/>
</entry>

Back to top

Last modified: