Martin Doms

Google Reader API series

• Part 1 – Programming to the API
• Part 2 – Listing API
• Part 3 – Editing API

In this post I will discuss the listing API for Google reader. This encapsulates all of the calls you’ll need to list items and feeds in various ways. The table below summarizes the API URLs you’ll be using. Simply follow the table from left to right to find your target API handle. Click on a terminal item to see a summary of what it does and how to use it.

Note that for the user items I have found that substituting a dash for the user number works in every case I’ve tested, because a user needs to be logged in with a valid token to use these calls anyway.

If this is your first foray into using the Google Reader API then you’ll want to read my previous post which describes how to acquire a valid token and cookie, and make calls to the API. Unlike part 1 of this series, this part is totally language agnostic.

URL structure: http://www.google.com/…

unread-count

Gets a list of feeds for the current user and the number of unread items in each feed. Also returns a list of labels that the user has created.
Parameters

• allcomments=[true|false] : I’m not sure what this parameter does, please leave a comment if you figure this one out.
• output=[json|xml] : Determines the format of the response. Default: xml
• ck=[unix timestamp] : Use the current Unix time here, helps Google with caching
• client=[your client] : You can use the default Google client (scroll), but it doesn’t seem to make a difference. Google probably uses this field to gather data on who is accessing the API, so I’d advise using your own unique string to identify your software.

Sample Output (XML)

Sample Output (JSON)

user-info

Gets information on the current user
Parameters

• ck=[unix timestamp] : Use the current Unix time here, helps Google with caching
• client=[your client] : You can use the default Google client (scroll), but it doesn’t seem to make a difference. Google probably uses this field to gather data on who is accessing the API, so I’d advise using your own unique string to identify your software.

Sample Output

feed/[feedurl]

Gets items belonging to a particular feed.
Parameters

• ot=[unix timestamp] : The time from which you want to retrieve items. Only items that have been crawled by Google Reader after this time will be returned.
• r=[d|n|o] : Sort order of item results. d or n gives items in descending date order, o in ascending order.
• xt=[exclude target] : Used to exclude certain items from the feed. For example, using xt=user/-/state/com.google/read will exclude items that the current user has marked as read, or xt=feed/[feedurl] will exclude items from a particular feed (obviously not useful in this request, but xt appears in other listing requests).
• n=[integer] : The maximum number of results to return.
• ck=[unix timestamp] : Use the current Unix time here, helps Google with caching.
• client=[your client] : You can use the default Google client (scroll), but it doesn't seem to make a difference. Google probably uses this field to gather data on who is accessing the API, so I'd advise using your own unique string to identify your software.

Sample Output

Output summary
This request returns an object that contains:

• Feed id string
• Feed title string
• Continuation string - what is this? Leave a comment if you know
• Self - an array of objects which contain a link to this list
• Alternate - an array of objects which contain non-Google links to the feed (usually the author's RSS)
• Updated timestamp
• Items - an array of item objects which contain
  • Crawl time - when the item was crawled by Google Reader
  • Id - a unique identifier for the item
  • Categories - an array of categories to which this item belongs. These appear to be user-specific
  • Item title string
  • Updated timestamp
  • Enclosure - an array of enclosure objects. These are used mostly for podcasts/videocasts, they contain media items enclosed in the feed item. Enclosure items are composed of
    • A link to the media file
    • An internet media type
    • Length, in bytes
  • An array of alternate links to the item
  • Media Group - appears to be an object storing an array of direct links to the enclosure media
  • Summary - an object containing a description of the feed item and a direction (ltr or rtl) for reading. Is this direction a byte ordering hack? Someone let me know in the comments.
  • Author string
  • An array of users who "like" the item
  • An array of comments on the item
  • An array of annotations on the item
  • An origin object which stores
    • The stream id - this is the feed/[feedurl] that Google uses to identify the feed
    • The feed title string
    • The HTML url to the feed's homepage

label/[labelName]

Lists all items from a given label.
Parameters

• See feed list

Sample Output - See feed list

reading-list

List all items in the user's reading list. This is a list of all of the items from all of the user's feeds, excluding items depending on the xt (exclude target) parameter.
Parameters

• See feed list

Sample Output - See feed list

starred

List all items that the user has marked as "starred"
Parameters

• n=[integer] : The maximum number of results to return.
• ck=[unix timestamp] : Use the current Unix time here, helps Google with caching.
• client=[your client] : You can use the default Google client (scroll), but it doesn't seem to make a difference. Google probably uses this field to gather data on who is accessing the API, so I'd advise using your own unique string to identify your software.

Sample Output - See feed list

broadcast

List all items that the user has chosen to share publicly.
Parameters

• n=[integer] : The maximum number of results to return.
• ck=[unix timestamp] : Use the current Unix time here, helps Google with caching.
• client=[your client] : You can use the default Google client (scroll), but it doesn't seem to make a difference. Google probably uses this field to gather data on who is accessing the API, so I'd advise using your own unique string to identify your software.

Sample Output - See feed list

created

List all notes that the user has created.
Parameters

• n=[integer] : The maximum number of results to return.
• ck=[unix timestamp] : Use the current Unix time here, helps Google with caching.
• client=[your client] : You can use the default Google client (scroll), but it doesn't seem to make a difference. Google probably uses this field to gather data on who is accessing the API, so I'd advise using your own unique string to identify your software.

Sample Output

That's an awful lot of information for a little note, but most of it corresponds closely to item information, so if you're unsure of how to interpret a field, have a look at the output summary for the feed/[feedurl] call.

Phew! That mostly does it for the listing methods. There are some other minor calls I've left out for brevity, but most of what you'll want to achieve is in here, and I intend on releasing complete documentation when I have finished my .NET Google Reader API library. In my next post I'll discuss the POST methods so you can start altering the contents of your Google Reader list, star/un-star items, etc. Stay tuned!