Google Bookmarks API Guide

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 bookmarked.mobi has collected here the information that was previously scattered over the internet, plus some of our own.

We 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.

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"?>"

We 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.

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

"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 Feb 2009), 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.