Google Base Data API

Getting Started

Developer's Guide

Reference Guide

Related Links

Using the Google Base data API Java Client Library

Google provides an extension to the Google data Java Client Library that helps connect to the Google Base feeds and interprets the result. For help setting up the client library, see the Client Library Getting Started Guide.

This client library is by no means the only way of connecting to the Google Base API server. You can achieve the same result using an Atom parser, such as Rome, or a command-line tool, such as curl coupled with an XML parser.

Audience
Introduction
Setting up
Executing a query and interpreting the results
Attributes and types
Accessing the itemtypes feed
Accessing the attributes feed
Inserting items
Updating items
Deleting items
Handling errors
Using the media feeds
Reference

Audience

This document assumes that you know Java programming, and that you are familiar with the basic concepts of Google Base.

Before you start, please make sure you have read and understood the Google data Java Client Library documentation.

Introduction

The Google Base client library extends the Google data client library and adds some Google Base-specific objects to make it easier to use. It tries to stick to the XML representation.

Each XML element in a feed or entry corresponds to one Java Object in the library. For example, an <atom:feed> element corresponds to a GoogleBaseFeed element, and an <atom:entry> element corresponds to a GoogleBaseEntryElement.

Google Base extends the Google data feeds with elements from the g namespace (http://base.google.com/ns-metadata/1.0) and elements from the gm namespace (http://base.google.com/ns/1.0). Elements in the g: namespace in an entry correspond to an instance of the class GoogleBaseAttributesExtension. Elements in the gm: namespace in an entry correspond to an instance of the class GoogleBaseMetaExtension.

Setting up

For help setting up the Java Client Library, see the Client Library Getting Started Guide. You'll find the classes you need to use in the java/lib/gdata-base-1.0.1.jar and java/lib/gdataclient-1.0.jar jar files.

You can import the classes you will need using the following import statements:

import com.google.api.gbase.client.*;
import com.google.gdata.data.*;
import com.google.gdata.util.*;

Executing a query and interpreting the results

The full source code of an example that does exactly what is described in this section is available in the distribution in the file java/src/com/google/api/gbase/examples/cmdline/QueryExample.java. You can find documentation for this example in the Sample Applications section.

As described in the Feeds Reference you can search all items in Google Base by connecting to the snippets feed URL:

http://www.google.com/base/feeds/snippets?bq=digital+camera

and then interpreting the resulting atom feed.

To do this programatically, you need to create a GoogleBaseService object and then run a query on it. This is done as follows:

GoogleBaseService service =
	new GoogleBaseService("Google-Tutorial-1.0", developerKey);

GoogleBaseQuery query = 
	new GoogleBaseQuery(FeedURLFactory.getDefault().getSnippetsFeedURL());
query.setGoogleBaseQuery("digital camera");

GoogleBaseFeed feed = service.query(query);

GoogleBaseQuery takes the URL of the feed you want to access and adds parameters or categories as explained in the Google data documentation. Each parameter supported by the Snippets feed corresponds to a setter in the GoogleBaseQuery object. In the sample code above, setGoogleBaseQuery correponds to the bq parameter.

service.query() connects to the URL generated by GoogleBaseQuery, gets the result, parses it and returns a GoogleBaseFeed. The GoogleBaseFeed contains a list of GoogleBaseEntry objects, one for each Google Base item returned by the server.

for(GoogleBaseEntry entry: feed.getEntries()) {
	System.out.println(entry.getGoogleBaseAttributes().getItemType() +
		 ": " + entry.getTitle().getPlainText() +
		 - " +entry.getId());
}

The code snippet above displays the following information for each entry:

its item type (<g:item_type type="text">)
its title (<atom:title>)
its id (<atom:id>)

Since <g:item_type> is in the g: namespace, you first need to get the GoogleBaseAttributesExtension object of the entry using entry.getGoogleBaseAttribute(). Then you get the attribute value using getItemType().

getItemType() is a shortcut that corresponds to getTextAttribute("item type"). getTextAttribute() gets the first attribute in the entry that is called 'item type' and whose type is 'text'". The second line in the example above could be rewritten as follows using getTextAttribute():

System.out.println(entry.getGoogleBaseAttributes().getTextAttribute("item type") +

Attributes and types

In the client library, an attribute is always identified by both its type and its name, as reflected by the class GoogleBaseAttributeId. Make sure you always specify the type when setting an attribute, as it will have an impact on which queries can be run on your items. For more details on constructing queries, see Attributes and Queries and also the Query Language Specification.

When getting attribute values, both the attribute name and its type are important. If an item contains the attribute <g:bathrooms type="float"> and you call the method getTextAttribute("bathrooms") , you would not get any answer, because the attribute bathrooms is of type float . If instead you call getFloatAttribute("bathrooms") , you will get the value of the bathrooms attribute.

If, on the other hand, you set the number of bathrooms in your "house" item using setTextAttribute("bathrooms") the attribute appear on the XML output, if users run this query: " [bathrooms > 2]" they will never get your item as an answer. Make sure you choose the correct type for your attributes to get the maximum benefit from the Google Base data API.

In some cases, when it is unclear whether an attribute should be an int or a float, you can avoid the dilemma by using the type number . If you call getNumberAttribute("bathrooms") you get both attributes defined as int and attributes defined as float.

Similarly, getDateTimeRangeAttribute() returns date , dateTime and dateTimeRange attributes..

Accessing the itemtypes feed

You can access the itemtypes feed using the client library as follows:

GoogleBaseService service = new GoogleBaseService("Google-Tutorial-1.0");
GoogleBaseFeed feed = 
    service.query(new GoogleBaseQuery(FeedURLFactory.getDefault().getItemTypesFeedURL("en_US"));

Each GoogleBaseEntry in this feed describes one item type, using entry elements in the gm: namespace. To access these elements, call GoogleBaseEntry.getGoogleBaseMetadata() and then call getItemTypeDescription() to access the subset of the gm: namespace which describes item types.

for(GoogleBaseEntry entry : feed.getEntries()) {
  ItemTypeDescription itemType = entry.getGoogleBaseMetadata().getItemTypeDescription();
  System.out.println("Google proposed item type: " + itemType.getName());

  System.out.println("Google proposed attributes: ");
  for(GoogleBaseAttributeId attributeId: itemType.getAttributeIds()) {
    System.out.println(attributeId);
  }
}

Accessing the attributes feed

Here's how you could use the client library to find out the 10 most commonly-used attributes for a recipe and for these, the 5 most common values (for text attributes).

GoogleBaseService service = new GoogleBaseService("Google-Tutorial-1.0");
GoogleBaseQuery query = new GoogleBaseQuery(FeedURLFactory.getDefault().getAttributesFeedURL())
query.setGoogleBaseQuery(" [item type: recipes]");
query.setMaxResults(10);
query.setMaxValues(5);
GoogleBaseFeed feed = service.query();

Each GoogleBaseEntry in the feed describes an attribute, from the most common to the least common. This time, the subset of gm: attributes can be accessed using getAttributeHistogram()

for(GoogleBaseEntry entry: feed.getEntries()) {
  AttributeHistogram attribute = entry.getGoogleBaseMetadata().getAttributeHistogram();
  System.out.println("attribute: " + attribute.getAttributeId());

  for(AttributeHistogram.UniqueValue value: attribute.getValues()) {
    System.out.println("  '" + value.getValueAsString() + "'");
  }
}

Inserting items

This section explains how to insert items into Google Base using the client library. Refer to the Feeds Reference for information about how you can insert items using the Items feed.

Performing authentication

To insert items, you first need to be authenticated. Specify your Google Base account name and password to GoogleBaseService as follows:

GoogleBaseService service =
	new GoogleBaseService("Google-Tutorial-1.0", developerKey);
service.setUserCredentials(username, password);

Note that this example supposes you're writing a desktop application and that you have access to the user name and password. That might not be the case when writing a server, such as a web application. For more information about authentication, see the Google Account Authentication documentation and the sample application in java/src/com/google/api/gbase/examples/recipe/. There is also documentation for this sample application.

Inserting your items

The next step is to create the GoogleBaseEntry you would like to insert.

GoogleBaseEntry entry = new GoogleBaseEntry();
entry.setTitle(TextConstruct.create(TextConstruct.Type.TEXT, 
	"My House", null));
entry.setContent(TextConstruct.create(TextConstruct.Type.TEXT,
	 "The best house in the area.", null));
entry.getGoogleBaseAttributes().setItemType("test");
entry.getGoogleBaseAttributes().addTextAttribute("my attribute", "hello");
entry.getGoogleBaseAttributes().addFloatAttribute("bathrooms", 2f);
entry.getGoogleBaseAttributes().addFloatAttribute("rooms", 6.5f);
entry.getGoogleBaseAttributes().addFloatAttribute("bedrooms", 2f);
entry.getGoogleBaseAttributes().addLocationAttribute("location", 
	"1900 Snow Cone Avenue, North Pole");

Finally, insert this GoogleBaseEntry object into the Items feed.

GoogleBaseEntry asInserted =
	service.insert(FeedURLFactory.getDefault().getItemsFeedURL(), entry);

The method service.insert returns the item you just inserted as you will find it in later in Google Base.

The Google Base server assigns precomputed attributes for your entry, such as the creation date and time, the author and, probably most importantly, the identifier (or URL) of the new entry. Keep this ID in asInserted, as you will need it to update or delete your item.

URL myEntryId = new URL(asInserted.getId());

You can also get this information by running a query on the Items feed.

Describing your items

Choosing which attributes to use

For Google Base queries to be really useful, it's best if people agree on a common set of g: attributes. Google does not constrain the attributes you can use in an item, so you might need to be careful when choosing your attribute name and type.

The Item types feed and the Attributes feed are meant to make this choice easier.

The Item types feed contains a list of item types recommended by Google. For each item type, it lists the attributes that Google thinks might be useful. You can access this feed using the client library as follows:

GoogleBaseService service =
	new GoogleBaseService("Google-Tutorial-1.0", developerKey);
service.setUserCredentials(username, password);

GoogleBaseFeed feed = 
	service.query(new GoogleBaseQuery(FeedURLFactory
		.getDefault()
		.getItemTypesFeedURL("en_US")));

Each GoogleBaseEntry in this feed will describe one item type, using entry elements in the gm: namespace. To access these elements, call GoogleBaseEntry.getGoogleBaseMetadata(), then call getItemTypeDescription() to access the subset of the gm: namespace that describes item types.

for(GoogleBaseEntry entry : feed.getEntries()) {
	ItemTypeDescription itemType = 
	entry.getGoogleBaseMetadata().getItemTypeDescription();

	System.out.println("Google proposed item type: " + itemType.getName());
	
	System.out.println("Google proposed attributes: ");
	for(GoogleBaseAttributeId attributeId: itemType.getAttributeIds()) {
		System.out.println(attributeId);
	}
}

Remember that the data in this feed is just a suggestion. It is not the final list of all item types or of all attributes. The items already in Google Base might not even follow these suggestions, or you might need an item type that is not on this list.

The Attributes feed might answer these kinds of questions. Here's how you could find out the 10 most commonly-used attributes for a recipe and, for these, the 5 most common values (for text attributes).

GoogleBaseService service =
	new GoogleBaseService("Google-Tutorial-1.0", developerKey);
GoogleBaseQuery query = 
	new GoogleBaseQuery(FeedURLFactory
		.getDefault()
		.getAttributesFeedURL());
query.setGoogleBaseQuery(" [item type: recipes]");
query.setMaxResults(10);
query.setMaxValues(5);
GoogleBaseFeed feed = service.query(query);

Each GoogleBaseEntry in the feed describes an attribute, from the most common to the least common. This time, the subset of gm: attributes that interests us can be accessed using getAttributeHistogram().

for(GoogleBaseEntry entry: feed.getEntries()) {
	AttributeHistogram attribute = 
		entry.getGoogleBaseMetadata().getAttributeHistogram();
	System.out.println("attribute: " + attribute.getAttributeId());
  
	for(AttributeHistogram.UniqueValue value: attribute.getValues()) {
		System.out.println("  '" + value.getValueAsString() + "'");
	}
}

Specifying the attribute type

In the Google Base client library, an attribute is always identified by both its type and its name, as reflected by the class GoogleBaseAttributeId. Make sure you always specify the type when setting an attribute, as it will have an impact on which Google Base queries may be run on your items.

For example, if you set the number of bathrooms in your "house" item using addTextAttribute("bathrooms") the attribute will appear on the XML output. However, if users run the query: [bathrooms > 2] they will never get your item as an answer.

Make sure you choose the correct type for your attributes to get the maximum benefit from Google Base.

Updating items

To modify an item you have inserted, get it back from the server, change it, then call update on it:

GoogleBaseService service =
	new GoogleBaseService("Google-Tutorial-1.0", developerKey);
service.setUserCredentials(username, password);

GoogleBaseEntry entry = service.getEntry(myEntryId);
entry.getGoogleBaseAttributes().addFloatAttribute("rooms", 7f);
service.update(myEntryId, entry);

You might avoid reading the entry from the server if you know exactly what your entry should look like. This is dangerous, as updating will replace everything with the entry you specify to update. If you forget to set an attribute that is already in the entry, it will be removed when it is updated.

myEntryId should be the ID that was assigned to your entry when you inserted it. You might have written it down when creating the entry or you might have found it by running a query on the Items feed.

Deleting items

To delete an item, all you need is its ID, expressed as a URL:

GoogleBaseService service =
	new GoogleBaseService("Google-Tutorial-1.0", developerKey);
service.setUserCredentials(username, password);

service.delete(myEntryId);

Using the media feeds

Reading Media Attachment Information

To get the media feed link for an item, first retrieve the item from the items feed. The item entry contains the URL of the media feed. (The corresponding entry in the snippets feed does not contain the link to the media feed.)

// Obtain the item from the /items feed
GoogleBaseEntry item = ...

// Obtain the media feed link. This call returns null if no mediaFeedLink is present in the item. 
// This happens when the item is obtained from a feed other than the itens feed, such as the snippets 
// or attributes feed.
FeedLink<GoogleBaseMediaFeed> mediaFeedLink = item.getMediaFeedLink(); 

// Get the URL to the media feed. This URL can be used for GETs or POSTs.
mediaFeedLink.getHref(); 

// Get the number of media attachments for this item.
mediaFeedLink.getCountHint();

You can get all the entries from the media feed for the item as follows.

// Gets the media feed.
GoogleBaseMediaFeed mediaFeed = service.getMediaFeed(new URL(mediaFeedLink.getHref()));

// Gets the list of entries in the media feed. Each entry describes one of the item's media attachments.
List<GoogleBaseMediaEntry> entries = mediaFeed.getEntries();

You can use a GoogleBaseMediaEntry as follows.

GoogleBaseMediaEntry mediaAttachment = entries.get(0);

// Gets the atom:content element. You can also convert the content to com.google.gdata.data.media.MediaContent; 
// however, note that this MediaContent is different than the com.google.gdata.data.media.mediarss.MediaContent,
// so you must be careful to avoid naming conflicts between the atom content and the media rss element. 
OutOfLineContent atomContent = (OutOfLineContent) mediaAttachment.getContent(); 

// Get the atom:link@rel='via'. This link is present if the image was crawled by the system (e.g. inserted 
// using the image_link or a bulk upload). This link will not be present for images that were uploaded via 
// the media feed or dashboard.
Link viaLink = mediaAttachment.getLink("via", null); 

// Get the atom:link@rel='edit'. This URL should be used for UPDATEs of metadata and DELETEs of media 
// attachments.
Link editLink = mediaAttachment.getEditLink();

You can use media content as follows.

// Returns the media:content attribute
MediaContent mediaContent = 
  mediaAttachment.getExtension(com.google.gdata.data.media.mediarss.MediaContent.class); 

// Returns the URL pointing to the image stored in the image cache server (scaled down, and encoded 
// to jpeg format).
mediaContent.getUrl(); 

// Returns the medium (image, video) for the media attachment. Currently, only images are supported.
mediaContent.getMedium(); 

// Returns the mime-type of the image.
mediaContent.getType(); 

// Returns a URL pointing to the computed thumbnail with the specified width and height.
List<MediaThumbnail> thumbnails = 
  mediaContent.getRepeatingExtension(com.google.gdata.data.media.mediarss.MediaThumbnail.class);
for (MediaThumbnail thumbnail : thumbnails) {
  thumbnail.getWidth();
  thumbnail.getHeight();
  thumbnail.getUrl();

Modifying a media attachment as binary content

You can modify a media attachment from a file on disk, with no media except title:

MediaFileSource mediaSource = new MediaFileSource(new File("image.png"), "image/png");

... or from an InputStream:

MediaStreamSource mediaSource = new MediaStreamSource(someInputStream, "image/jpeg");

... or from a byte array:

MediaByteArraySource mediaSource = new MediaByteArraySource(someByteArray, "image/tiff");

When you upload an attachment the title is set by default to the name of the file, but can be changed as follows.

mediaSource.setName("My caption");

Once you've made your modifications, save the image.

GoogleBaseMediaEntry insertedEntry = service.insert(
  new URL(mediaFeedLink.getHref()), 
  GoogleBaseMediaEntry.class, 
  mediaSource)

The insertedEntry will contain the metadata for the inserted image, and can be interpreted as described above.

Modifying a media attachment as an atom entry with binary content

First, create a media entry.

GoogleBaseMediaEntry mediaEntry = new GoogleBaseMediaEntry();

Set its title.

mediaEntry.setTitle(new PlainTextConstruct("My image"));

Attach media source to it.

mediaEntry.setMediaSource(new MediaStreamSource(someInputStream, "image/jpeg"));

Then save it.

GoogleBaseMediaEntry insertedMediaEntry = service.insert(new URL(mediaFeedLink.getHref()), mediaEntry);

Updating the caption of a media attachment

Once you obtain a media entry; either from the media feed, or by executing an insert or an update, you can use it to modify the caption as follows.

mediaEntry.setTitle(new PlainTextConstruct("My updated title"));
GoogleBaseMediaEntry updatedEntry = service.update(new URL(mediaEntry.getEditLink().getHref()), mediaEntry);

Deleting a media attachment

Delete a media attachment as follows.

service.delete(new URL(mediaEntry.getEditLink().getHref());

Handling errors

The examples above do not contain any error-handling code to keep things simple.

The GoogleBaseService methods throw two kinds of exceptions:

IOException, which mean that communication with the Google Base server failed
ServiceException, which can have different meaning depending on the concrete subclass that has been thrown, such as AuthenticationException or InvalidEntryException.

If you receive a ServiceException, make sure you get the error message using getResponseBody() . This error message contains the text sent by the server and is usually an XML message. Check the type of this message using getResponseContentType(). If it is indeed an XML message, you can parse it to get the real error message.

To let the library do the XML parsing for you, create a ServiceErrors object, passing it the ServiceException. The ServiceErrors object will read the response body and return it as a series of plain-text error messages. Some of these error messages are associated with a field; others are global errors.

The following shows an example of very basic error handling:

} catch(ServiceException e) {
	System.err.println("error: " + e.getMessage());
  
	ServiceErrors errors = new ServiceErrors(e);
	for (ServiceError error : errors.getAllErrors()) {
		String scope;
		if (error.getField() != null) {
			scope = error.getField();
		} else {
			scope = "global error";
		}
		System.err.println(scope + ": " + error.getReason());
	}
}

Reference

For referential information, see the Google data client library javadoc.


e.g. "ajax apis" or "open source"