YouTube

YouTube API v2.0 – Activity Feeds

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

Activity feeds list actions that a particular user or set of users has taken on the YouTube site. The API enables you to retrieve two types of activity feeds:

  • A subscription activity feed identifies actions associated with the authenticated user's subscriptions.
  • A user activity feed identifies actions taken by one or more users who are specified in the API request.

In addition, the API previously supported a third type of activity feed, the friend activity feed. This feed type has been deprecated, and requests to retrieve a friend activity feed will instead return the authenticated user's subscription activity feed.

User events in activity feeds

Activity feeds list the following events:

  • Rating a video
  • Sharing a video
  • Marking a video as a favorite
  • Commenting on a video
  • Uploading a video
  • Creating a subscription to a channel

The following sections explain how to retrieve and process activity feeds:

  1. Retrieving an activity feed
  2. Sample activity feed
  3. Subscription activity (subtivity) feeds
  4. User activity feeds
  5. Retrieving additional metadata for activity feed entries

Retrieving an activity feed

An activity feed contains a series of <entry> tags, with each entry describing a particular event, like someone rating a video or creating a subscription. An event should appear in activity feeds within 30 minutes and may show up much sooner than that. Each feed entry contains the following elements that combine to identify the event:

  • Each entry contains an <author> tag, which encapsulates information about the user associated with the event. Within that tag, the <yt:userId> contains a value that uniquely identifies the user. The <name> tag identifies either the user's YouTube username or, if the user's YouTube account is connected to a Google+ profile, the user's public display name.

  • Each entry contains a <category> tag for which the value of the scheme attribute is http://gdata.youtube.com/schemas/2007/userevents.cat. That tag's term attribute identifies the type of event that the entry describes. The following list identifies possible values for the term attribute. The list also identifies additional tags that will appear for each type to identify the specific event associated with the entry.

    • video_rated – A user rated a video. For this type of event, an entry will also contain the following tags:

      • The <yt:videoid> tag identifies the rated video.
      • The <yt:rating> tag specifies the rating given to the video. Activity feeds only identify videos that were given positive ('like') ratings.
      • The <gd:rating> tag identifies a numeric rating given to the video.

    • video_shared – A user shared a video. For this type of event, an entry will also contain the following tag:

    • video_favorited – A user marked a video as a favorite. For this type of event, an entry will also contain the following tag:

      • The <yt:videoid> tag identifies the video that was marked as a favorite.

    • video_commented – A user commented on a video. For this type of event, an entry will also contain the following tags:

      • The <yt:videoid> tag identifies the video to which the comment was added.
      • The <link> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007#comments contains a link to the feed URL for the comment that was added.
      • The <link> tag that has a rel attribute value of http://gdata.youtube.com/schemas/2007#video contains a link to the feed URL for the video to which the comment was added.

    • video_uploaded – A user uploaded a video. For this type of event, an entry will also contain the following tag:

    • user_subscription_added – A user added a subscription. For this type of event, an entry will also contain the following tag:

      • The <yt:username> tag identifies the user who owns the channel that was subscribed to. Only channel subscriptions are included in activity feeds.

    An activity feed entry may contain a <yt:groupId> tag, which, if present, indicates that the event is closely related to another event in the same feed. Generally, events with the same <yt:groupId> value are associated with the same user and video (or other resource). For example, if a user positively rates a video and marks the same video as a favorite, those two events will have the same <yt:groupId> value in activity feeds. Your application can avoid repetition by grouping events with the same <yt:groupId> value as shown in the image below.

    Image showing single UI entry for a video that was marked as a favorite and positively rated by the same user.

If you set the inline parameter value to true when retrieving an activity feed, then any event that involves a video – video_rated, video_shared, video_favorited, video_commented and video_uploaded – will include a video entry that contains all of the metadata for that video. The video entry will be encapsulated inside the <link> element that has a rel attribute value of http://gdata.youtube.com/schemas/2007#video. This feature is discussed in more detail in the Retrieving additional metadata for activity feed entries section.

Sample activity feed

Activity feeds all have the same structure, though the tags included within each feed entry varies slightly as described in the Retrieving an activity feed section.

The XML below shows a sample subscription activity feed for the following API request.

https://gdata.youtube.com/feeds/api/users/default/subtivity?v=2

The XML contains one entry, which identifies an instance of a video being uploaded.


<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  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/"D0EGSH47eCp7ImA9WxRVGEg.&quot;'>
  <id>tag:youtube.com,2008:user:GoogleDevelopers:subtivity</id>
  <updated>2012-03-20T09:13:49.000Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#userEvent'/>
  <title>Subtivity for GoogleDevelopers</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity?v=2'/>
  <link rel='http://schemas.google.com/g/2005#batch' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity/batch?v=2'/>
  <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity?start-index=1&max-results=25&v=2'/>
  <link rel='service' type='application/atomsvc+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity?alt=atom-service&v=2'/>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>12</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/"D0EGSH47eCp7ImA9WxRQQEg."'>
    <id>tag:youtube.com,2008:user:GoogleDevelopers:event:VGF5Wm9uZNzQ5MzM%3D</id>
    <updated>2009-01-16T09:13:49.000Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#userEvent'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
      term='video_uploaded'/>
    <title>GoogleTechTalks has uploaded a video</title>
    <link rel='alternate' type='text/html' href='https://www.youtube.com'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/_gZK0tW8EhQ?v=2'/>
    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity/VGF5Wm9uZGF5MzEy%3D%3D?v=2'/>
    <author>
      <name>GoogleTechTalks</name>
      <uri>https://gdata.youtube.com/feeds/api/users/tXKDgv1AVoG88PLl8nGXmw</uri>
      <yt:userId>tXKDgv1AVoG88PLl8nGXmw<</yt:userId>
    </author>
    <yt:videoid>_gZK0tW8EhQ</yt:videoid>
  </entry>
</feed>

Subscription activity (subtivity) feeds

To retrieve a subscription activity feed for the currently logged-in user, send a GET request to the following URL. You must provide an authentication token with this request, which ensures that a user can only retrieve her own subscription activity feed. Your request must also specify your developer key.

https://gdata.youtube.com/feeds/api/users/default/subtivity

Subscription activity feeds contain the most recent events associated with the authenticated user's subscriptions. Events must have occurred within the previous 14 days to be included in the feed, and the total number of events included in the feed may be limited.

User activity feeds

User activity feeds list user events that occurred within the last 60 days. You can request a user activity feed for a single user or you can retrieve a single feed that lists actions from multiple users.

The YouTube API provides several ways to retrieve a user activity feed. All requests must specify your developer key.

  • To retrieve the user activity feed for the currently authenticated user, send a GET request to the following URL:

    https://gdata.youtube.com/feeds/api/users/default/events?v=2
  • To retrieve another user's activity feed, send a request to the following URL. Replace the text username with either the user's YouTube user ID or YouTube username.

    https://gdata.youtube.com/feeds/api/users/userId/events?v=2
  • To retrieve a user activity feed that lists the actions of one or more users, send a request to the following URL. In the request, set the author parameter value to a comma-separated list of up to 20 YouTube user IDs or YouTube usernames, and the API response will list actions performed by any of those users.

    https://gdata.youtube.com/feeds/api/events?author=userIds
    

    Note that this feed URL does not support the Simple Update Protocol.

Note: If you need to track updates for a large number of user activity feeds, consider using the Simple Update Protocol, which is supported if you use the first of the two retrieval methods described below.

Retrieving additional metadata for activity feed entries

Even though an activity feed identifies the video or user associated with a particular event, the feed does not necessarily contain metadata about that video or user. For example, a feed entry that identifies a video_rated event contains the YouTube video ID for the video and the rating that the user gave to that video. However, the entry does not contain other metadata like the video's title, description or owner.

  • To retrieve additional metadata about videos associated with particular events, you can either use the inline parameter or you can submit a batch processing request. Both of these options are explained below.
  • To retrieve additional metadata about users associated with particular events, you can submit a batch processing request.

Using the inline parameter

If you set the inline parameter value to true when retrieving an activity feed, then any event that involves a video – video_rated, video_shared, video_favorited, video_commented and video_uploaded – will include a video entry that contains all of the metadata for that video. The video entry will be encapsulated inside the <link> element that has a rel attribute value of http://gdata.youtube.com/schemas/2007#video.

The sample feed below shows how an inlined video entry appears in an activity feed. The video entry appears in italics in the sample feed, and the event entry in the XML is the same one that appears in the Sample activity feed section. Several child tags of both the <feed> and the inlined <entry> tags have been omitted in an effort to make the sample more readable.


<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
  xmlns:gml='http://www.opengis.net/gml'
  xmlns:georss='http://www.georss.org/georss'
  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/"D0EGSH47eCp7ImA9WxRVGEg.&quot;'>
  <updated>2012-03-20T09:13:49.000Z</updated>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://gdata.youtube.com/schemas/2007#userEvent'/>
  <title>Subtivity for GoogleDevelopers</title>
  <logo>http://www.youtube.com/img/pic_youtubelogo_123x63.gif</logo>
  <author>
    <name>YouTube</name>
    <uri>http://www.youtube.com/</uri>
  </author>
  <generator version='2.0' uri='http://gdata.youtube.com/'>YouTube data API</generator>
  <openSearch:totalResults>12</openSearch:totalResults>
  <openSearch:startIndex>1</openSearch:startIndex>
  <openSearch:itemsPerPage>25</openSearch:itemsPerPage>
  <entry gd:etag='W/"D0EGSH47eCp7ImA9WxRQQEg."'>
    <updated>2009-01-16T09:13:49.000Z</updated>
    <category scheme='http://schemas.google.com/g/2005#kind'
      term='http://gdata.youtube.com/schemas/2007#userEvent'/>
    <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
      term='video_uploaded'/>
    <title>GoogleTechTalks has uploaded a video</title>
    <link rel='alternate' type='text/html' href='https://www.youtube.com'/>
    <link rel='http://gdata.youtube.com/schemas/2007#video'
      type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/videos/_gZK0tW8EhQ?v=2'/>

      <entry gd:etag='W/"CUECRX47eCp7ImA9WxBbF0g."'>
        <id>_gZK0tW8EhQ</id>
        <published>2010-03-13T22:45:09.000Z</published>
        <updated>2010-03-16T15:34:24.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/categories.cat'
          term='People' label='People & Blogs'/>
        ...
      </entry>

    <link rel='self' type='application/atom+xml'
      href='https://gdata.youtube.com/feeds/api/users/GoogleDevelopers/subtivity/VGF5Wm9uZGF5MzEy%3D%3D?v=2'/>
    <author>
      <name>GoogleTechTalks</name>
      <uri>https://gdata.youtube.com/feeds/api/users/tXKDgv1AVoG88PLl8nGXmw</uri>
      <yt:userId>tXKDgv1AVoG88PLl8nGXmw<</yt:userId>
    </author>
    <yt:videoid>_gZK0tW8EhQ</yt:videoid>
  </entry>
</feed>

Submitting a batch processing request

You can submit a batch processing request to retrieve additional information about the videos or users identified in an activity feed. A batch processing request can retrieve up to 50 video entries or user profile entries.

  • To retrieve a list of video entries in a batch processing request, send a POST request to the following URL:

    https://gdata.youtube.com/feeds/api/videos/batch

    Each entry in the request will use the <id> tag to identify a video for which you want to retrieve additional information. Use the <yt:videoid> values from the activity feed entries to construct the <id> tag values for the batch processing request.

    Activity feed:
    
        <entry>
          ...
          <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
            term='video_favorited'/>
          <yt:videoid>5EDAB37EA1823E58</yt:videoid>
        </entry>
    
    Batch processing request:
    
        <entry>
          <id>http://gdata.youtube.com/feeds/api/videos/<yt:videoid></id>
        </entry>
    
  • To retrieve a list of user profiles in a batch processing request, send a POST request to the following URL:

    https://gdata.youtube.com/feeds/api/users/batch

    Each entry in the request will use the <id> tag to identify a user whose profile you want to retrieve. Use the <yt:username> values from the activity feed entries to construct the <id> tag values for the batch processing request.

    Activity feed:
    
        <entry>
          ...
          <category scheme='http://gdata.youtube.com/schemas/2007/userevents.cat'
            term='user_subscription_added'/>
          <yt:username>GoogleDevelopers</yt:username>
        </entry>
    
    Batch processing request:
    
        <entry>
          <id>http://gdata.youtube.com/feeds/api/users/<yt:username></id>
        </entry>
    

Note: You cannot retrieve video entries and user profile entries in the same batch processing request, so you would need to submit separate requests (to different URLs) to retrieve video entries as well as user profile entries.

Sample batch processing request for additional metadata

For example, the following batch processing request retrieves entries for three videos:


<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:media='http://search.yahoo.com/mrss/'
  xmlns:batch='http://schemas.google.com/gdata/batch'
  xmlns:yt='http://gdata.youtube.com/schemas/2007'>
  <batch:operation type='query'/>
  <entry>
    <id>https://gdata.youtube.com/feeds/api/videos/ADos_xW4_J0</id>
  </entry>
  <entry>
    <id>https://gdata.youtube.com/feeds/api/videos/iIp7OnHXBlo</id>
  </entry>
  <entry>
    <id>https://gdata.youtube.com/feeds/api/videos/cBPzPdcMj1s</id>
  </entry>
</feed>

Please see the batch processing documentation for additional information, including a sample response to a batch processing request.

pagination links

« Previous
User Profiles and Accounts
Next »
Using the Simple Update Protocol (SUP)

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.