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.
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.
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>
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:
atom (the
default), rss, or json.relevance (the
default for the videos feed) or viewCount.feedURL/-/fritz/laurie returns all entries
that are tagged with both of the user-defined tags fritz and laurie.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.
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.
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
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:
most_viewedtop_ratedrecently_featuredwatch_on_mobileStandard 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
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
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
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.
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"/>
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.
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.
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.
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
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>
© Google Inc. 2007 - Privacy Policy - Terms and Conditions - About Google
Last modified: