mmartins.com
Sections

Google Bookmarks API Guide

Written on: March, 2008.
Updated: January, 2011.

Many Web 2.0 applications are built on top of a Web API. This technology allows for rich and versatile communication between browser and web site or between two web sites. Google is a leader in the publication of its services through public interfaces such as the ones for Search, Google Maps, Picasa, Calendar and many others, which you can read about in their Google Code web site. However, they have not yet published an API for Google Boomarks. Several people have tried to reverse engineer Google Bookmarks, and I collected here the information that was previously scattered over the internet, plus some of my own.

I have organized this page in terms of the actions that can be performed with this API. All actions require the user to be logged in to his or her Google account. POST actions require a ...&sig=... parameter with the signature key. If you are not logged in, the HTML and XML links send you to the ServiceLogin page first. The RSS page seems to allow more direct authentication.

The zx parameter with a random unique value is recommened for GET and POST requests as a proxy cache defeater, but it is not really required. Here's an example: ...&zx=hihi40f1q5g1MA...

Create one bookmark

Method: POST
Address: http://www.google.com/bookmarks/mark
Form fields:
bkmk=url
title=title
annotation=notes
labels=comma-separated list of labels
Hidden form fields:
prev="/lookup"
sig=valid sig key
Landing page: a page with all the bookmarks created so far.

Edit one bookmark

Use the same method as to add a bookmark. If URL already exists, bookmark will be edited/updated.

Start creation of a bookmark

Method: GET
Address: http://www.google.com/bookmarks/mark?op=add
Parameters:
output=popup | ?
bkmk=url
title=title
annotation=notes
labels=comma separated list of labels
Landing page: the link creation page, with all the fields already filled in. The user still needs to press the "Add bookmark" button in this form to complete the creation of the bookmark. This kind of action is useful for a bookmarklet, for example.

Upload an XML file with all bookmarks

Description: this is an efficient method for applications to upload bookmarks. With a single POST, all bookmarks are submitted. One important limiations is that it does not accept annotations. The reason for this limitation is that the upload capability was written to migrate "IE favorites" to Google Bookmarks, and IE favorites don't have annotations. The action of importing bookmarks does not remove the existing ones. See also the XML export option below.
Method: POST
Address: http://www.google.com/bookmarks/mark?op=upload
Form fields: this form contains a single field. Because of the way the XML POST request is handled on the server side, the XML file is split at the first equal side, going one half to the name of the field and the other to the value. The name of the field must be "<?xml version". And the value of the field must start with ""1.0" encoding="utf-8"?>"

I have created a page with an example of such a form: the Google Bookmarks API XML Upload Form.

Lookup one record given a certain criteria

http://www.google.com/bookmarks/lookup?q=label:label2&output=xml

XML Data Access

Description: From all the export options, this is the best one if you are trying to build a web application on top of the Google Bookmarks service; however, keep in mind that bookmark annotations are not part of the XML.
Method: GET
Address: http://www.google.com/bookmarks/?output=xml
Parameters:
num=a large number (if parameter is ommited, only 25 bookmarks are returned)

RSS Data Access

Description: Certain tools can handle an RSS but cannot handle any XML file.
Address: http://www.google.com/bookmarks/?output=rss
This RSS like many others at Google has a limit of 1000 items. I have not yet tested using the start-index and max-results uqery parameters to loop over a 1000 bookmarks.

"Bookmarks File" data access

Description: Compatible with most browsers and bookmark sites
Address: http://www.google.com/bookmarks/bookmarks.html

Limitations of the Google Bookmarks API

Well, the first limitation of the Google Bookmarks is that (as of Jan 2011), there is no Google Bookmarks API... All we have is a collection of reverse engineered URL's and their parameters.

Here are the main obstacles to using the Google Bookmarks data in a mobile web application:
  • Neither of the authentication methods recognized by Google (OAuth and AuthSub) apply to Google Bookmarks access.
  • To get the XML with all bookmarks, the GET request has to have the appropriate Cookies set by (and for) the google.com domain. These cookies are not available (for writing by or reading to) the mobile web app domain.
  • Getting all the bookmarks at once may be slow on a mobile device. What is needed is to get just the labels first, but there is no known URL for this.
  • It is not possible to use the Google AJAX Feed API for Google Bookmarks, because Google AJAX Feed API works only with public feeds.
  • As far as we can tell, it is not possible to use an iFrame to get the XML because the iFrem GET request also doesn't carry the google.com cookies.
  • The POST action to add/edit a bookmark requires a sig parameter, which, as far as we can tell, is only available for not just "registered" but also "secure" appplications.

Additional API's - 1

The developer of the Chrome extension "Add to Google Bookmarks" graciously contacted me with information on additional API's. Here are the steps to add a bookmark to one bookmark list:
  1. Open the Bookmarklet page: https://www.google.com/bookmarks/api/bookmarklet
  2. Grab the SL.xt variable from inside it (this is effectively thesignature)
  3. Do a request to https://www.google.com/bookmarks/api/api/tp?nr=100 - the NR is the amount of lists to show (people will have less than 100...)
  4. To add a page, send:
    • xt = (signature)
    • op = AddResults
    and the POST payload is encoded json stringified:
    td={"results":[{"threadId":(bookmark list ID), "elementId":0, "authorId":0, "title":"Google Bookmarks API Guide", "timestamp":0, "formattedTimestamp":0, "url":"http://mmartins.com/mmartins/googlebookmarksapi/", "signedUrl":"","previewUrl":"","snippet":"", "threadComments":[], "parentId":"(bookmark list ID)","labels":[]}]}

Additional API's - 2

The developer of the app GMarks for Android also has sent in his own page about the Bookmarks API. In his page he describes the REST-based API for their Google's AJAX calls.


Please contact me with comments or with new information on the Google Bookmarks API. And if this page was useful to you, please consider linking to it from one of your web sites, or from a blog, forum posting, Facebook, Twitter, etc.