Notebook Data API
Google Data APIs
Google Notebook Data API Developer's Guide
The Google Notebook data API allows client applications to view public notebook content in the form of Google data API ("GData") feeds. Your client application can request a list of notes from a public notebook, request a list of public notebooks owned by a particular user, and query for notes that match particular criteria.
Google Notebook feeds are currently read-only and public-only; you can't send data to Notebook using the data API, and you can't get a feed of private Notebook data.
Contents
Audience
This document is intended for programmers who want to write client applications that can interact with Google Notebook. It provides a series of examples of basic data API interactions, with explanations.
For Google Notebook data API reference information, see the reference guide.
This document assumes that you understand the general ideas behind the Google data APIs protocol. It also assumes that you know how to program in Java.
The code examples in this document use the GData Java client library; see the client library documentation for more information and more (non-Notebook-specific) examples. If your client is written in another language, see the client library documentation for that language, if available; you can translate the examples in this document into other languages as needed.
Interacting with Google Notebook: examples
Assume you're creating a client application that needs to communicate with Google Notebook. You want your client to be able to get a list of notes from a notebook.
Note (no pun intended): If you don't already have a Google Notebook account, you may want to create one for testing purposes.
To communicate with Google Notebook, your application needs to request the feed for a particular notebook, or for a list of public notebooks from a particular user. The first step is to obtain the user ID; then you can get a list of all the user's public notebooks.
You can also get a feed of the contents of an individual notebook. With any GData feed, you can take either of two approaches:
- Request the feed manually, using the raw GData protocol.
- Request the feed using the client library.
Finally, you can send a query to request a feed of entries that match particular criteria.
For general information about Google data APIs and more example code that you can adapt for use with Notebook, see Using the Java Client Library.
Obtain the user ID
Before you can request a feed, you have to determine the feed URL. This requires a manual step: the user must visit the public notebook or user page that they want to subscribe to, and copy the URL of that page, and provide the URL to your client.
Note: Only public notebooks provide feeds. To make a notebook public, the owner has to use the "Publish this notebook" link in the GUI. The user—the person reading the notebook—generally finds out about a public notebook by following a link to it from email or a web page. The notebook's owner can find the notebook's public URL in various ways, such as by following the "Published (view)" link. For more information about publishing notebooks and viewing public notebooks, see the Google Notebook help pages.
The URL of a user's page, listing all their public notebooks, is of the following form:
http://www.google.com/notebook/user/userID
The URL of a public notebook page is of the following form:
http://www.google.com/notebook/public/userID/notebookID
Your client should parse the URL supplied by the user, and store the user ID and (if included) notebook ID for later use in constructing a feed URL.
The user may supply your client with a feed URL rather than with an HTML page's URL, so your client should be able to identify a feed URL; see below for information about feed URLs.
Get a list of all the user's public notebooks
The general idea of how to request a feed is that you determine the feed URL, and then you send an HTTP GET request to that URL. Google Notebook then returns a GData feed containing either notebooks or notes, depending on the type of feed you requested.
Google provides client libraries for interacting with Google data API services in a variety of programming languages. You can use the client libraries to send the HTTP request and handle the returned feed; we'll show you an example of how to do that below. But whether or not you use the client library, the following is what's going on at the protocol level. If you're using a UNIX system and you want to try this out without writing any code, you may find the UNIX command-line utilities curl or wget useful; for more information, see the manual pages for those utilities.
To get a feed listing all of a user's public notebooks, send the following HTTP request to Google Notebook:
GET http://www.google.com/notebook/feeds/userID
Where userID is the user ID you obtained in the previous section.
Google Notebook then returns an HTTP 200 OK status code and a "metafeed," a feed that lists all of that user's public notebook feeds; each entry in the feed represents a public notebook associated with the user.
An entry in the metafeed might resemble the following:
<entry>
<id>http://www.google.com/notebook/feeds/userID/notebookID</id>
<published>2007-01-10T15:20:12.819Z</published>
<updated>2007-01-23T20:03:59.624Z</updated>
<title type='text'>My Birthday Wish List</title>
<summary type='text'>My Birthday Wish List</summary>
<content type='application/atom+xml'
src='http://www.google.com/notebook/feeds/userID/notebooks/notebookID'>
</content>
<link rel='alternate' type='text/html'
href='http://www.google.com/notebook/public/userID/notebookID'
title='My Birthday Wish List'></link>
<link rel='self' type='application/atom+xml'
href='http://www.google.com/notebook/feeds/userID/notebookID'></link>
<author>
<name>Elizabeth Bennet</name>
</author>
</entry>
For information about what each of those elements means, see the Google Data APIs Protocol Reference or the Atom 1.0 specification.
If your request fails for some reason, Google Notebook may return a different status code; for information about the status codes, see the protocol reference document.
Request a feed manually
To get a feed of all the notes in a particular public notebook, send the following HTTP request:
GET http://www.google.com/notebook/feeds/userID/notebooks/notebookID
Where userID and notebookID are the IDs you obtained earlier.
Google Notebook then returns an HTTP 200 OK status code and a feed containing all the notes in the specified notebook.
Suppose you request the notes in a public notebook, and the notebook has only one note. Then Google Notebook returns something similar to the following feed. We've slightly edited the following example to make it a little more readable by humans; in particular, a real feed contains actual IDs and URLs.
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:openSearch='http://a9.com/-/spec/opensearchrss/1.0/'>
<id>http://www.google.com/notebook/feeds/userID/notebooks/notebookID</id>
<updated>2007-01-10T22:21:21.552Z</updated>
<title type='text'>My Birthday Wish List</title>
<link rel='alternate' type='text/html'
href='http://www.google.com/notebook/public/userID/notebookID'
title='My Birthday Wish List'></link>
<link rel='http://schemas.google.com/g/2005#feed' type='application/atom+xml'
href='http://www.google.com/notebook/feeds/userID/notebooks/notebookID'>
</link>
<link rel='self' type='application/atom+xml'
href='http://www.google.com/notebook/feeds/userID/notebooks/notebookID'>
</link>
<author>
<name>Elizabeth Bennet</name>
</author>
<generator version='1.0'
uri='http://www.google.com/notebook'>Google Notebook</generator>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<entry>
<id>http://www.google.com/notebook/feeds/userID/notebooks/notebookID/noteID</id>
<published>2007-01-10T23:21:21.552Z</published>
<updated>2007-01-10T23:21:21.552Z</updated>
<title type='text'>Jane Austen books</title>
<content type='html'>
Jane Austen books: <em>especially</em> <cite>Pride and Prejudice</cite>.
</content>
<link rel='related' type='text/html'
href='http://en.wikipedia.org/wiki/Pride_and_Prejudice'
title='Pride and Prejudice'></link>
<link rel='alternate' type='text/html'
href='http://www.google.com/notebook/public/userID/notebookID#noteID'
title='Pride and Prejudice'></link>
<link rel='self' type='application/atom+xml'
href='http://www.google.com/notebook/feeds/userID/notebooks/notebookID/noteID'>
</link>
<author>
<name>Elizabeth Bennet</name>
</author>
</entry>
</feed>
For information about what each of those elements means, see the Google Data APIs Protocol Reference, the Google Notebook Reference Guide, and/or the Atom 1.0 specification.
Note: The entries in a feed are ordered by the values of their updated elements, with the most recently updated entry appearing first in the feed. To request notes in the order that they are listed in the notebook, use the orderby query parameter, which is described in the Google Notebook Reference Guide.
Request a feed using the client library
The above description shows how to send a request and receive a response by hand; if you already have code that handles feeds, then you can simply use it to send the relevant GET request, as shown above.
However, if you don't already have your own feed-handling code, then we encourage you to use Google's client library where possible.
To use the client library, the general steps are:
- Obtain or construct the appropriate URL.
- Create an object of the
GoogleServiceclass, which handles communication and authentication with Google Data services. - Use client library methods to send the request and receive any results the service sends back.
For example, to request the feed of notes from a public notebook, you could use the following Java code. You'll have to replace the URL in this example with one of the feed URLs you constructed earlier.
URL feedUrl =
new URL("http://www.google.com/notebook/feeds/userID/notebooks/notebookID");
GoogleService myService = new GoogleService("notebook", "exampleCo-exampleApp-1");
// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);
// Print the title of the notebook:
System.out.println(myFeed.getTitle().getPlainText());
In the above example, first you specify the URL; to request a metafeed rather than a notebook's feed, just use the metafeed URL instead.
Then you create a GoogleService object.
Then you call the getFeed method. That method handles all of the communication with Google Notebook—it sends the HTTP GET request, it waits for the XML response to arrive, and it parses the XML and assigns the element contents and attribute values to appropriate parts of the Feed object.
If an error occurs during the getFeed call, then the client library generates an appropriate exception, so your code should be prepared to handle exceptions.
The final line of the above code calls the feed's getTitle method, which returns a TextConstruct object. To transform the text construct into a String, we call the title's getPlainText method.
In most contexts, you'll probably want to do something more with the feed than just print out the title. For example, the client library lets you generate Atom or RSS representations of the feed and perform various other transformations. For more information, see the Javadoc documentation.
Send a query
GData lets you request a set of entries that match specified criteria, such as requesting entries created or updated in a given date range, or requesting entries in the order that they appear in the notebook.
For more information about the query parameters for GData queries (such as updated-min and updated-max), see the Google Data APIs Protocol Reference document.
Here's how to create and send a date-range query at the protocol level:
Send an HTTP request like the following to Google Notebook, using the feed URL:
GET http://www.google.com/notebook/feeds/userID/notebooks/notebookID?updated-min=2006-03-16T00:00:00&updated-max=2006-03-24T23:59:59
When you send that GET request, Google Notebook returns
an HTTP 200 OK status code and a feed (of a notebook) containing any
entries (notes) that were created or updated in the date range you specified.
To query using other standard GData query parameters, just change the URL to use other parameters. Google Notebook supports all standard query parameters in the protocol reference except for entry author (author) and full-text search (q). Google Notebook also offers one special query parameter, orderby. If you append orderby=position to the end of a query of a notebook, Google Notebook returns a feed of notes sorted in the order that they would appear in the original notebook, instead of by their update times.
You can, of course, use the client library to send a query instead of sending it by hand. In this case, you'll need to add a new step to the process: constructing a Query object.
For example, to view entries created or modified in a particular date range, use the following Java code.
URL feedUrl = new URL("http://www.google.com/notebook/feeds/userID/notebooks/notebookID");
Query myQuery = new Query(feedUrl);
myQuery.setUpdatedMin(DateTime.parseDateTime("2006-03-16T00:00:00"));
myQuery.setUpdatedMax(DateTime.parseDateTime("2006-03-24T23:59:59"));
GoogleService myService = new GoogleService("notebook", "exampleCo-exampleApp-1");
// Send the request and receive the response:
Feed resultFeed = myService.query(myQuery, Feed.class);
The above code creates a new Query and sets the minimum and maximum updated times; then it creates a GoogleService and calls the query method to send the query and receive the response.