YouTube

YouTube API v2.0 – Subscriptions

Note: The YouTube Data API (v2) has been officially deprecated as of March 4, 2014. Please refer to our deprecation policy for more information.

A subscription notifies a user when new videos are added to a channel or when another user takes one of several actions on YouTube, such as uploading a video, rating a video, or commenting on a video. 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 retrieve, create or delete subscriptions as described in the following sections:

  1. Retrieving a user's subscriptions
  2. Retrieving new subscription videos
  3. Adding a subscription
  4. 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 a GET request to the following URL. Note: For this request, you must provide an authorization token, which enables YouTube to verify that the user authorized access to the resource.

    https://gdata.youtube.com/feeds/api/users/default/subscriptions?v=2
  • To request a feed of another user's subscriptions, send a GET request to the following URL. Note that this request does not require user authorization.

    https://gdata.youtube.com/feeds/api/users/userId/subscriptions?v=2

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

A subscriptions feed contains a series of <entry> tags, with each entry describing a subscription. Each entry contains a <category> tag for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat. The value of that tag's term attribute identifies the type of subscription that the entry represents.

  • If the feed entry describes a subscription to another user's activities, the <category> tag's term attribute will have a value of user.

  • If the feed entry describes a channel subscription, the <category> tag's term attribute will have a value of channel.

The <entry> contains the following tags to identify the channel (or user) associated with the subscription:

  • The <yt:channelId> tag identifies the channel associated with the subscription.

  • The <yt:username> identifies the display name for the user or channel associated with the subscription.

The following XML shows a sample API response containing a subscriptions feed. The entries in the response show a user activity subscription, followed by a channel subscription. The <content> tag in each entry specifies the URL for retrieving videos for the subscription. Note that an entry for a user activity subscription will only contain the <content> tag if your request to retrieve subscriptions specifies a developer key.


<?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.com,2008:user:_x5XG1OV2P6uZZ5FSM9Ttw: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 GoogleDevelopers</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='related' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw?v=2'/>
  <link rel='alternate' type='text/html'
    href='https://www.youtube.com'/>
  <link rel='hub' href='http://pubsubhubbub.appspot.com'/>
  <link rel='http://schemas.google.com/g/2005#feed'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#post'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch'
    type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions?...'/>
  <link rel='service' type='application/atomsvc+xml'
    href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions?alt=...'/>
  <author>
    <name>_x5XG1OV2P6uZZ5FSM9Ttw</name>
    <uri>https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw</uri>
    <yt:userId>_x5XG1OV2P6uZZ5FSM9Ttw</yt:userId>
  </author>
  <generator version='2.1'
    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/"CEAHQX47eCp7ImA9WxBSEUQ."'>
    <id>tag:youtube.com,2008:user:_x5XG1OV2P6uZZ5FSM9Ttw:subscription:ps2fD3tG7-s</id>
    <published>2009-12-18T19:18:50.000-08:00</published>
    <updated>2009-12-18T19:18:50.000-08:00</updated>
    <app:edited>2009-12-18T19:18:50.000-08:00</app:edited>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#subscription'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/subscriptiontypes.cat'
      term='user'/>
    <title>Activity of : GoogleTechTalks</title>
    <content type='application/atom+xml;type=feed'
      src='https://gdata.youtube.com/feeds/api/users/googletechtalks/events?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/googletechtalks/events?v=2'/>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/channel/UCtXKDgv1AVoG88PLl8nGXmw'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/default/subscriptions/ps2fD3tG8-s?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions/MpajmvGNexIkHC?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
      <yt:userId>_x5XG1OV2P6uZZ5FSM9Ttw</yt:userId>
    </author>
    <yt:channelId>UCtXKDgv1AVoG88PLl8nGXmw</yt:channelId>
    <yt:countHint>1688</yt:countHint>
    <media:thumbnail url='https://s.ytimg.com/yt/img/no_videos_140-vfl5AhOQY.png'/>
    <yt:unreadCount>5</yt:unreadCount>
    <yt:username display='GoogleTechTalks'>googletechtalks</yt:username>
  </entry>

  <entry gd:etag='W/&quot;DU4DRX47eCp7ImA9WB9RFEU.&quot;'>
    <id>tag:youtube.com,2008:user:_x5XG1OV2P6uZZ5FSM9Ttw:subscription:MpajmvGNex</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 : OpenSocialFoundation</title>
    <content type='application/atom+xml;type=feed'
      src='https://gdata.youtube.com/feeds/api/users/opensocialfoundation/uploads?v=2'/>
    <link rel='related' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/opensocialfoundation?v=2'/>
    <link rel='alternate' type='text/html'
      href='https://www.youtube.com/channel/UCFVAu1vssbJ_M7ydX3JxrEA/videos'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions/MpajmvGNex?v=2'/>
    <link rel='edit' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/_x5XG1OV2P6uZZ5FSM9Ttw/subscriptions/MpajmvGNex?v=2'/>
    <author>
      <name>GoogleDevelopers</name>
      <uri>https://gdata.youtube.com/feeds/api/users/GoogleDevelopers</uri>
      <yt:userId>_x5XG1OV2P6uZZ5FSM9Ttw</yt:userId>
    </author>
    <yt:channelId>UCFVAu1vssbJ_M7ydX3JxrEA</yt:channelId>
    <yt:countHint>25</yt:countHint>
    <media:thumbnail url='https://s.ytimg.com/yt/img/no_videos_140-vfl5AhOQY.png'/>
    <yt:unreadCount>5</yt:unreadCount>
    <yt:username display='OpenSocialFoundation'>opensocialfoundation</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 GET request to the following URL:

    https://gdata.youtube.com/feeds/api/users/default/newsubscriptionvideos
  • To request a feed of another user's subscriptions, send a GET request to the following URL. Note that this request does not require authentication.

    https://gdata.youtube.com/feeds/api/users/userId/newsubscriptionvideos

    In the URL above, you should replace the text userId with the user's YouTube user ID. For backward compatibility purposes, the API also supports having the user's YouTube username specified instead.

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='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/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 send a POST request that identifies the YouTube user name for the authenticated user who is creating the subscription. The body of the request is an XML entry that contains the following elements:

  • The <category> tag identifies the type of subscription that the user is creating. Set the tag's term attribute value to user to indicate that the user is subscribing to another user's activities (uploading videos, ratings, marking videos as favorites, etc.), or set the term attribute value to channel to indicate that the user is subscribing to a channel.

  • The <yt:username> tag identifies the channel or the user whose activity is being subscribed to.

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

Subscribing to a user's activities
POST /feeds/api/users/default/subscriptions HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Content-Length: CONTENT_LENGTH
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
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="user"/>
    <yt:username>GoogleDevelopers</yt:username>
</entry>

If a user creates a subscription to another user's activities and already has a subscription to the other user's channel, the user activity subscription will replace the channel subscription.

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: Bearer ACCESS_TOKEN
GData-Version: 2
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>GoogleDevelopers</yt:username>
</entry>

If a user creates a subscription to another user's channel and already has a subscription to the other user's activities, the channel subscription will replace the user activity subscription.

The following steps explain a common use case for creating subscriptions, in which a user watches a video and subscribes to the video owner's activity or 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 activity or to the video owner's channel.

  3. Your application sends an API request to https://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 user if you are creating a user activity subscription or channel if you are creating a channel subscription.

Deleting a subscription

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

DELETE /feeds/api/users/default/subscriptions/SUBSCRIPTION_ID HTTP/1.1
Host: gdata.youtube.com
Content-Type: application/atom+xml
Authorization: Bearer ACCESS_TOKEN
GData-Version: 2
X-GData-Key: key=DEVELOPER_KEY

The following steps explain a common use case for deleting a subscription, in which a user looks at his list of subscriptions and removes one or more subscriptions 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 a 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.

pagination links

« Previous
Playlists
Next »
Channel Suggestions

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.