YouTube

YouTube API v2.0 – Simple Update Protocol (SUP)

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

Warning: If you are using SUP for monitoring comments, you will be impacted by the change to the new commenting system. Please read this article for details.

This section explains how to use the Simple Update Protocol (SUP) to monitor user activity feeds for YouTube users. This functionality will likely be most appealing to sites that maintain their own friend graphs or that want to monitor the activities of many users.

At a general level, SUP enables an API provider (such as YouTube) to notify API users when a feed is updated. SUP is particularly useful for API users that want to monitor many different feeds at once. With SUP, an API user can issue a single query to identify all updated resources, which is a much more efficient way to monitor changes than frequent polling. The API user can then retrieve data only for the modified resources, eliminating the need to ever issue polling requests on unchanged resources.

The following sections explain how to use SUP to monitor user activity feeds:

  1. Understanding the SUP feed format
  2. Retrieving YouTube's SUP feed
  3. Discovering hash keys for activity feeds
  4. SUP in action

Understanding the SUP feed format

An SUP feed consists of a JSON object that maps the keys in the list below to their corresponding values:

  • The since_time field specifies the earliest time that a resource could have changed and still have been included in the SUP feed.

  • The updated_time field specifies the latest time that a resource could have changed and still have been included in the SUP feed. As such, the feed identifies resources that were updated within the inclusive time range beginning at the since_time and ending at the updated_time.

  • The period field specifies the duration of the time interval for which the SUP feed includes updates. As defined in the SUP specification, the number of seconds between between the since_time and the updated time must be equal to or greater than the interval that the period field specifies.

  • The available_periods field contains a map that identifies the different SUP available for a feed. The map key contains a number that specifies the length of time (period) for which the corresponding feed contains updates. The value associated with the map key specifies the feed URL.

  • The updates field contains an array of two-element lists, where the first element identifies an updated resource and the second element is a string used to distinguish between updates. In YouTube's SUP feed, this field identifies updated user activity feeds.

The sample SUP feed below contains updates for a five-minute (300 second) period and indicates that feeds are also available covering updates that occurred within 10-minute or 15-minute periods.

{ "updated_time": "2009-04-28T21:29:20Z",
  "since_time": "2009-04-28T21:24:19Z",
  "period": 300,
  "available_periods": {
    "300": "http://gdata/youtube.com/sup?seconds=300",
    "600": "http://gdata/youtube.com/sup?seconds=600",
    "900": "http://gdata/youtube.com/sup?seconds=900"
  },
  "updates": [
    ["159aa827", "6e19"],
    ["9559d1d", "6e19"],
    ["159aa827", "6f22"],
    ...
  ]
}

Retrieving YouTube's SUP feed

To retrieve YouTube's SUP feed, send a GET request to the following URL. Note that you can also use the seconds parameter to retrieve a feed that identifies all of the activity feeds that changed within a specific time interval. The SUP feed's available_periods field identifies the supported time intervals and their associated feed URLs.

http://gdata.youtube.com/sup

In YouTube's SUP feed, each item in the updates array is a two-element list that identifies an updated user activity feed:

  • The first element in the list is the key that YouTube uses to uniquely identify a user activity feed.
  • The second element distinguishes between updates. (For example, an SUP feed could indicate that the same activity feed changed several times during a given interval.) The value is required in the SUP specification but does not serve a practical purpose in this feed.

Discovering hash keys for activity feeds

To use the SUP feed, you also need to discover the hash keys that YouTube has assigned to the user activity feeds that you want to monitor. You can then determine whether any of those feeds were updated by matching the hash keys in your database to the hash keys in the SUP feed.

To locate the hash key for a particular user's user activity feed, you need to retrieve the user's activity feed from the following URL. (Replace the text userId with the user's YouTube user ID or YouTube username.)

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

You can also retrieve the user activity feed for the currently logged-in user by sending an authenticated GET request to the following URL:

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

In the API response, the <feed> tag will contain a <link> tag for which the rel attribute value is updates. That href attribute contains a link to YouTube's SUP feed, and the link embeds the hash key that uniquely identifies the activity feed.

<link rel='updates' type='application/json'
  href='http://gdata.youtube.com/sup?seconds=300#47677e0a'/>

SUP in action

The Über Activity Viewer, a sample application demonstrated at Google I/O 2009, uses SUP to monitor the activities of participating YouTube users.

The application has two main components:

  • A Java daemon periodically fetches YouTube's SUP feed and checks to see whether any participating users (members) are identified in the feed. The daemon creates multiple threads to retrieve updated activity feeds and store the updates in a database.

  • A PHP website retrieves a list of activities from the database and then sends API requests to retrieve additional metadata about each activity. For example, the Java daemon records that an event occurred, such as a user adding a favorite video, and the PHP application retrieves metadata about that video. The PHP application also lets new users join the Über Activity Viewer user list, retrieving the SUP user hash for each new user and storing the hash and YouTube username in the database.

You can download sample code for the Über Activity Viewer at http://code.google.com/p/gdata-samples/source/browse/#svn/trunk/uberviewer.

Watch a video of Jeff Fisher and Jochen Hartmann explaining SUP and presenting the Über Activity Viewer at Google I/O 2009. (The part of the presentation that covers SUP begins at the 23:38 mark of the video.)

Screenshot of SUP presentation video

pagination links

« Previous
Activity Feeds
Next »
Using Batch Processing

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.