My favorites | English | Sign in

More personalization in Google Friend Connect New!

YouTube APIs and Tools

YouTube logo

Developer's Guide: Data API Protocol – Subscriptions

A subscription refers to an entity that notifies a user when new videos are uploaded. Users can subscribe to another user's channel, another user's list of favorites, a playlist or a keyword tag. A user can view and edit his list of subscriptions on his account page, and a user's subscriptions are also publicly visible to other YouTube users.

The YouTube Data API enables a user to create or delete subscriptions.

Retrieving a user's subscriptions
 
 Retrieving new subscription videos
 
 Adding a subscription
 
 Deleting a subscription
 

Retrieving a user's subscriptions

This section explains how to retrieve a feed listing a specific user's subscriptions. Note that some users may not have created any subscriptions.

  • To request a feed of the currently logged-in user's subscriptions, send an HTTP GET request to the following URL. Note: For this request, you must provide an authentication token in the Authorization HTTP request header. The authentication token enables YouTube to identify the user.

    http://gdata.youtube.com/feeds/api/users/default/subscriptions?v=2

  • To request a feed of another user's subscriptions, send an HTTP GET request to the following URL. Note that this request does not require authentication.

    http://gdata.youtube.com/feeds/api/users/username/subscriptions?v=2

    In the URL above, you must replace the text username with the user's YouTube username.

A subscriptions feed contains a series of <entry> tags, with each entry describing a subscription. Users can subscribe to YouTube channels, other users' lists of favorite videos, playlists, and keyword tags. Each entry in the subscription feed contains a <category> tag for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. The value of the term attribute for that <category> tag indicates whether the subscription is to a channel, a list of favorite videos, a playlist, or a keyword tag.

  • If the feed entry describes a channel subscription, the <category> tag's term attribute will have a value of channel. The entry will also contain the <yt:username> element, which specifies the owner of the channel.

  • If the feed entry describes a subscription to another user's list of favorite videos, the <category> tag's term attribute will have a value of favorites. The entry will also contain the <yt:username> element, which specifies the user whose favorite videos are being subscribed to.

  • If the feed entry describes a playlist subscription, the <category> tag's term attribute will have a value of playlist. The entry will also contain the <yt:playlistId> and <yt:playlistTitle> tags, which identify the playlist as well as the playlist's display title. In addition, the <yt:username> and <media:thumbnail> tags will identify the YouTube user who created the playlist and the thumbnail image for the playlist, respectively.

  • If the feed entry describes a keyword subscription, the <category> tag's term attribute will have a value of query. The entry will also contain the <yt:queryString> element, which specifies the keyword that is the subject of the subscription.

The following XML shows a sample API response containing a subscriptions feed. The response contains a series of four entries. The entries show a channel, keyword, playlist and favorite videos subscription. The <content> tag in each entry specifies the URL for retrieving videos in that subscription. 


<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/&quot;DU4DRX47eCp7ImA9WB9RFEU.&quot;'>
  <id>tag:youtube,2008:user:andyland74:subscriptions</id>
  <updated>2008-07-21T17:10:32.855Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#subscription'/>
  <title>Subscriptions of andyland74</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='related' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
  <link rel='alternate' type='text/html'
    href='http://www.youtube.com/profile_subscriptions?user=andyland74'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions?alt=...'/>
  <author>
    <name>andyland74</name>
    <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
  </author>
  <generator version='2.0'
    uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>3</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/&quot;DU4DRX47eCp7ImA9WB9RFEU.&quot;'>
    <id>tag:youtube,2008:user:andyland74:subscription:1BF1kEXir4w</id>
    <published>2007-10-15T15:39:34.000-07:00</published>
    <updated>2007-10-15T15:39:34.000-07:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2007-10-15T15:39:34.000-07:00</app:edited>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='channel'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <title>Videos published by : littlet2009</title>
    <content type='application/atom+xml;type=feed'
      src='http://gdata.youtube.com/feeds/api/users/littlet2009/uploads?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/profile_videos?user=littlet2009'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/1BF1kEXir4w?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/1BF1kEXir4w?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:username>littlet2009</yt:username>
  </entry>
  <entry gd:etag='W/&quot;AkQFRH47eCp7ImA9WxZQF00.&quot;'>
    <id>tag:youtube,2008:user:andyland74:subscription:XFb0XbMIERw</id>
    <published>2008-02-29T10:40:27.000-08:00</published>
    <updated>2008-02-29T10:40:27.000-08:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2008-02-29T10:40:27.000-08:00</app:edited>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='query'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <title>Videos matching : Dog skateboarding</title>
    <content type='application/atom+xml;type=feed'
      src='http://gdata.youtube.com/feeds/api/videos?q=Dog+skateboarding&amp;v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/results?search_query=Dog+skateboarding'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/XFb0XbMIERw?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/XFb0XbMIERw?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:queryString>Dog skateboarding</yt:queryString>
  </entry>
  <entry gd:etag='W/&quot;CkYNRH47eCp7ImA9WxRVGUg.&quot;'>
    <id>tag:youtube,2008:user:andyland74:subscription:Y6FAbqUmEsX</id>
    <published>2008-02-29T11:40:27.000-08:00</published>
    <updated>2008-02-29T11:40:27.000-08:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2008-02-29T11:40:27.000-08:00</app:edited>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='playlist'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <title>Doritos You Make It We Play It</title>
    <content type='application/atom+xml;type=feed'
      src='http://gdata.youtube.com/feeds/api/playlists/C344114E1E41B2FA?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/view_play_list?p=C344114E1E41B2FA'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/Y6FAbqUmEsX?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/Y6FAbqUmEsX?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:playlistTitle>Doritos You Make It We Play It</yt:playlistTitle>
    <yt:username>DoritosYouMakeIt</yt:username>
    <yt:playlistId>C344114E1E41B2FA</yt:playlistId>
    <media:thumbnail url='http://i4.ytimg.com/vi/s_J2ww-ZAzw/default.jpg'/>
  </entry>
  <entry gd:etag='W/&quot;C08FRn47eCp7ImA9WxZXEEg.&quot;'>
    <id>tag:youtube,2008:user:andyland74:subscription:OsaQBQ7TbqY</id>
    <published>2008-02-26T10:50:17.000-08:00</published>
    <updated>2008-02-26T10:50:17.000-08:00</updated>
    <app:edited xmlns:app='http://www.w3.org/2007/app'>
      2008-02-26T10:50:17.000-08:00</app:edited>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='favorites'/>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <title>Favorites of : kemlye1</title>
    <content type='application/atom+xml;type=feed'
      src='http://gdata.youtube.com/feeds/api/users/kemlye1/favorites?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74?v=2'/>
    <link rel='alternate' type='text/html'
      href='http://www.youtube.com/profile_favorites?user=kemlye1'/>
    <link rel='self' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/OsaQBQ7TbqY?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='http://gdata.youtube.com/feeds/api/users/andyland74/subscriptions/OsaQBQ7TbqY?v=2'/>
    <author>
      <name>andyland74</name>
      <uri>http://gdata.youtube.com/feeds/api/users/andyland74</uri>
    </author>
    <yt:username>kemlye1</yt:username>
  </entry>
</feed>

Retrieving new subscription videos

This section explains how to retrieve a feed listing a specific user's new subscription videos. The feed returns the same list of videos that appears on the user's Subscriptions page under the New Videos subheading.

  • To request a feed of the currently logged-in user's new subscription videos, send an authenticated HTTP GET request to the following URL:

    http://gdata.youtube.com/feeds/api/users/default/newsubscriptionvideos

  • To request a feed of another user's subscriptions, send an HTTP GET request to the following URL. Note that this request does not require authentication.

    http://gdata.youtube.com/feeds/api/users/username/newsubscriptionvideos

    In the URL above, you must replace the text username with the user's YouTube username.

In addition, a user profile entry contains a <gd:feedLink> tag that contains the URL you would use to retrieve a user's new subscription videos feed as shown in the following sample tag:

<gd:feedLink
  rel='http://gdata.youtube.com/schemas/2007#user.newsubscriptionvideos'
  href='http://gdata.youtube.com/feeds/api/users/andyland74/newsubscriptionvideos'/>

The API response for this query is a videos feed that has the same format as the sample response in the Understanding video feeds and entries section of this document.

Adding a subscription

To create a subscription, you must identify the YouTube user name for the authenticated user who is creating the subscription. You must also use the <category> tag to indicate whether the user is subscribing to a channel, list of favorites, playlist or keyword.

  • For a channel subscription or favorite videos subscription, the <yt:username> tag identifies the username associated with the channel or favorites list to which the authenticated user is subscribing.
  • For a playlist subscription, the <yt:playlistId> tag identifies the playlist to which the user is subscribing.
  • For a keyword search subscription, the <yt:queryString> tag identifies the keyword associated with the new subscription.

The following requests illustrate the XML format for creating different types of subscriptions:

Subscribing to a channel:
POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="channel"/>
    <yt:username>andyland74</yt:username>
</entry>
Subscribing to another user's list of favorites:
POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="favorites"/>
    <yt:username>andyland74</yt:username>
</entry>
Subscribing to a playlist:
POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="playlist"/>
    <yt:playlistId>D8AE0D634D86A94F</yt:playlistId>
</entry>
Subscribing to a keyword:
POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

<?xml version="1.0" encoding="UTF-8"?>
<entry xmlns="http://www.w3.org/2005/Atom"
  xmlns:yt="http://gdata.youtube.com/schemas/2007">
    <category scheme="http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat"
      term="query"/>
    <yt:queryString>Dog Skateboarding</yt:queryString>
</entry>

The following list identifies common use cases for creating subscriptions and describes the API calls associated with each use case:

  • A user watches a video and subscribes to the video owner's channel.

    1. This use case begins with an API request to retrieve information about a specific video.

    2. After watching the video, the user clicks a link to subscribe to the video owner's channel.

    3. Your application sends an API request to http://gdata.youtube.com/feeds/api/users/default/subscriptions to create the subscription. In the XML entry in your request, the <yt:username> tag value specifies the video owner's YouTube username and the <category> tag's term attribute has a value of channel.

  • A user watches a video and then subscribes to all videos matching a keyword associated with that video.

    1. This use case begins with an API request to search for videos or to retrieve a particular video feed.

    2. The user clicks on a video in the result set from step 1, prompting a second API request to retrieve information about that specific video. In this step, the user links to a page to watch the selected video.

    3. The page where the user watches the video displays a list of keywords associated with the video and allows the user to subscribe to individual keywords. The user clicks a link to subscribe to a keyword.

    4. Your application sends an API request to http://gdata.youtube.com/feeds/api/users/default/subscriptions to create the subscription. In the XML entry in your request, the <yt:queryString> tag's value is the keyword. The <category> tag's term attribute has a value of query.

Deleting a subscription

The following sample API request demonstrates how to delete a subscription:

DELETE /feeds/api/users/USER_ID/subscriptions/SUBSCRIPTION_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: AuthSub token="AUTHORIZATION_TOKEN"
GData-Version: 2
X-GData-Client: CLIENT_ID
X-GData-Key: key=DEVELOPER_KEY

The following list identifies a common use case for deleting a subscription:

A user looks at his list of subscriptions and removes one or more from the list.

  1. This use case begins with a request to retrieve a feed of the user's subscriptions.

  2. Your application displays a list of the user's subscriptions, and the user selects one or more subscriptions to delete.

  3. Your application loops through the selected subscriptions and sends an HTTP DELETE request to delete each one from the user's list of subscriptions. Each API request is sent to the edit URL for the subscription.