New API Features

Wednesday, January 09, 2008 at 12:53 AM

By Alex Dovlecel, Google Base API Engineering Team

If you've been wondering what the Google Base API team has been working on lately, wonder no more. We are happy to tell you that a couple of new features were released in the last couple of weeks.

Location queries
We think locations are extremely useful for building a large variety of applications. Mashups of Google Maps spring to mind. They look cool and are easy to develop. That's why we devoted some of our time to improving location queries.Now you can:
  • Query addresses: The radius (or lack thereof) in a location query will help you tune your results. If a radius is not provided, Google Base will match the items that are located in the specified area (zip code, city, state, country). If you include a radius, then Google Base will return the items located at a distance less than the radius from the center of the specified area. Sounds complicated? It's not. Let's take a couple of examples:
    [location:@"Mountain View, CA"] will match items located in the city of Mountain View, California. It doesn't matter if they are close or far from the center of the town.
    [location:@"Mountain View, CA" + 1mi] will match items located within one mile of Mountain View's geographic center.
    [location:@"Washington"] will match items located in Washington. You can do the same for countries by replacing Washington with a country name like Switzerland, or France. By providing a ZIP code in the address string, like in this query: [location:@"93430, CA"] the API will make sure to return only items that are located in the given zip code (Mountain View, California).

  • Query rectangular areas: For certain types of applications (like Google Maps mashups), querying for a rectangular lat/long boundary is important. Now you can easily do this by using the following syntax: [location: @+12.9+12.20..@+14.5+12.45].
For more information about location queries, refer to the developer's guide.

Reference attributes
We know items are not always isolated entities. Sometimes it makes sense to have one item point to another. Of course, you can build a relation between two items by using attributes of type "url", but that can be cumbersome. To address this case, we introduced a new "reference" attribute type. Now you can insert an item containing attributes that reference another Google Base item by passing the ID of the referenced item. For example the attribute
<g:my_ref_attribute type='reference'>17891817243016304554> refers to the item that can be accessed at
You can also query for items that reference another item. The query [my ref attribute(reference): 17891817243016304554] will return all the items that have a reference attribute named "my ref attribute" which points to the item identified by

Make no mistake - Google Base is definitely not a relational database. You can't do join operations in queries. Google Base does not enforce referential integrity for your items. References can help you interconnect your data, so that you or anyone else who finds your data can more easily navigate from one item to the next.
For more information about reference attributes, refer to the developer's guide.

Images and thumbnails
If you want to embed images for items in Google Base in your website, we have good news for you. Images are now stored at, and you can link to them directly. The Base API also supports a new value for the content query parameter called thumbnails. If you include the thumbnails argument, all of your g:image_link attributes will include links to the related thumbnails.

For example, querying reviews for "Golden Compass":

... will return, among the others, the item:

...which contains links to thumbnails:
<g:image_link type='url'>
<gm:thumbnail width='60' height='60'>
<gm:thumbnail width='90' height='90'>
<gm:thumbnail width='120' height='120'>
<gm:thumbnail width='220' height='220'>

For more information about using images in your application, refer to the developer's guide.

We hope these new features will spark some ideas for applications to build on top of Google Base. The more you use the API, the more we'll give back. Stay tuned to find out about more new features coming soon.