The Google Base Data API allows client applications to query and update Base content in the form of Google Data API feeds. Your client application can execute queries, retrieve quantitative information about item types and attributes, insert new items in Google Base, and edit or delete existing items.
This document is intended for programmers who want to write client applications that can interact with Google Base. It provides a series of examples of basic Data API interactions using raw XML/HTTP, with explanations. After reading this document, you may wish to learn more about interacting with the API using our client libraries by reading the language-specific developer guides.
For introductory information about using the Base Data API, see the Getting Started guide. For an introduction to the Base query language, refer to Attributes and Queries.
This document assumes that you understand the general ideas behind the Google Data APIs protocol. Each example in this document shows how to use the bare protocol to interact with Base.
Your client application can connect to the Google Base API server using an Atom parser, such as Rome, or a command-line tool, such as curl coupled with an XML parser.
This guide is most useful if you are writing code for a language for which we don't yet have a client library. Most languages have XML parsers and HTTP request operations. With those two tools and this guide, you should have all you need.
Google Base extends the Google Data feeds with elements from the g namespace
(http://base.google.com/ns)
and elements from the gm namespace (http://base.google.com/ns/1.0).
Every request that you send using the Google Base Data API should specify version 2 of the API.
To specify a version number, use the GData-Version HTTP header:
GData-Version: 2
Alternatively, if you can't set HTTP headers, you can specify v=2 as a query parameter in the URL. But the HTTP header is preferred where possible.
Note: The client libraries supply appropriate version headers automatically, so don't use the v=2 query parameter when you're using a client library.
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. The results of a query will be an Atom feed that looks like this:
|
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
xmlns:gm='http://base.google.com/ns-metadata/1.0'
xmlns:g='http://base.google.com/ns/1.0'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"DU4CSH44eCp7ImA9WxRVGUg."'>
<id>http://www.google.com/base/feeds/snippets</id>
<updated>2008-11-17T21:39:29.030Z</updated>
<title>Items matching query: digital camera</title>
...
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/snippets?start-index=1&max-results=25&bq=digital+camera' />
<link rel='next' type='application/atom+xml'
href='http://www.google.com/base/feeds/snippets?start-index=26&max-results=25&bq=digital+camera' />
<author>
<name>Google Inc.</name>
<email>base@google.com</email>
</author>
<generator version='1.0' uri='http://base.google.com'>
GoogleBase</generator>
<openSearch:totalResults>5575760</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>25</openSearch:itemsPerPage>
<entry gd:etag='W/"AkMASH47eCp7ImA9WxRWFUQ."'>
<id>
http://www.google.com/base/feeds/snippets/9669...</id>
...
<category scheme='http://base.google.com/categories/itemtypes'
term='Products' />
<title type='text'>NEW ... Digital Camera Battery</title>
<content type='html'>BRAND NEW ... Digital ...
Camera ...</content>
<link rel='alternate' type='text/html'
href='http://example.com/Digital-Camera-Battery.html'/>
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/snippets/9669...' />
<author>
...
</author>
<g:brand type='text'>...</g:brand>
<g:item_type type='text'>Products</g:item_type>
<g:item_language type='text'>EN</g:item_language>
<g:target_country type='text'>US</g:target_country>
<g:price type='floatUnit'>19.75 usd</g:price>
<g:image_link type='url'>
http://example.com/battery_image.jpg</g:image_link>
<g:category type='text'>Cameras & Photo>Digital Camera
Accessories>Batteries & Chargers>Batteries>Other
Brands</g:category>
<g:customer_id type='int'>...</g:customer_id>
...
</entry>
<entry gd:etag='W/"Ak8EQH47eCp7ImA9WxRVFk4."'>
<id>
http://www.google.com/base/feeds/snippets/9104...</id>
...
<category scheme='http://base.google.com/categories/itemtypes'
term='Products' />
<title type='text'>NEW ... Digital Camera Battery</title>
<content type='html'>BRAND NEW Canon ... Digital Camera Battery
...</content>
<link rel='alternate' type='text/html'
href='http://example.com/my_digital_camera_battery.html' />
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/snippets/9104...' />
<author>
...
</author>
<g:item_type type='text'>Products</g:item_type>
<g:item_language type='text'>EN</g:item_language>
<g:target_country type='text'>US</g:target_country>
<g:price type='floatUnit'>14.75 usd</g:price>
<g:image_link type='url'>
http://example.com/canon_battery.jpg</g:image_link>
...
</entry>
</feed>
If you want to retrieve a feed that you've retrieved before, you can improve efficiency by telling Google Base to send the feed only if it has changed since the last time you retrieved it.
To do this sort of conditional retrieval, send an HTTP GET request that includes an HTTP If-None-Match header. In the header, specify the feed's ETag, which you can find in the <feed> element's gd:etag attribute.
For example:
If-None-Match: W/"DU4CSH44eCp7ImA9WxRVGUg."
When Google Base receives this request, it checks to see whether the feed that you requested has the same ETag as the ETag you specified. If the ETags match, then the feed hasn't changed, and Base returns either an HTTP 304 Not Modified status code or an HTTP 412 Precondition Failed status code. Both of those status codes indicate that the feed you've already retrieved is up-to-date.
If the ETags don't match, then the feed has been modified since the last time you requested it, and Base returns the feed.
For more information about ETags, see the Google Data APIs reference guide.
You can access the itemtypes feed by making a GET
request to a URL similar to the following:
http://www.google.com/base/feeds/itemtypes/en_US
The URL for the item types feed includes the desired locale. You can also add a target item type to further refine your query. For information on item type queries, see the Feeds Reference.
The result of your query will be a feed that contains information about the item type or types you requested. The results of the above query should look something like the following:
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
xmlns:gm='http://base.google.com/ns-metadata/1.0'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"CEMMQHw4fip7ImA9WxRVGUs."'>
<id>http://www.google.com/base/feeds/itemtypes/en_US</id>
<updated>2008-11-17T22:54:41.236Z</updated>
<title>Item types for locale en_US</title>
<link rel='alternate' type='text/html'
href='http://base.google.com' />
...
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/itemtypes/en_US?start-index=1&max-results=25' />
<author>
<name>Google Inc.</name>
<email>base@google.com</email>
</author>
<generator version='1.0' uri='http://base.google.com'>
GoogleBase</generator>
<openSearch:totalResults>19</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>25</openSearch:itemsPerPage>
<entry gd:etag='W/"CEMMQHw4fCp7ImA9WxRVGUs."'>
<id>http://www.google.com/base/feeds/itemtypes/en_US/jobs</id>
<updated>2008-11-17T22:54:41.234Z</updated>
<category scheme='http://base.google.com/categories/itemtypes'
term='jobs' />
<title>jobs</title>
<content>jobs</content>
<link rel='related' type='application/atom+xml'
href='http://www.google.com/base/feeds/snippets/-/jobs'
title='Items of type 'jobs'' />
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/itemtypes/en_US/jobs' />
<gm:item_type>jobs</gm:item_type>
<gm:attributes>
<gm:attribute name='job type' type='text' />
<gm:attribute name='job industry' type='text' />
<gm:attribute name='job function' type='text' />
...
</gm:attributes>
</entry>
<entry gd:etag='W/"CEMMQHw4fSp7ImA9WxRVGUs."'>
<id>
http://www.google.com/base/feeds/itemtypes/en_US/products</id>
<updated>2008-11-17T22:54:41.235Z</updated>
<category scheme='http://base.google.com/categories/itemtypes'
term='products' />
<title>products</title>
<content>products</content>
<link rel='related' type='application/atom+xml'
href='http://www.google.com/base/feeds/snippets/-/products'
title='Items of type 'products'' />
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/itemtypes/en_US/products' />
<gm:item_type>products</gm:item_type>
<gm:attributes>
<gm:attribute name='product type' type='text' />
<gm:attribute name='condition' type='text' />
<gm:attribute name='brand' type='text' />
...
</gm:attributes>
</entry>
...
<entry gd:etag='W/"CEMMQHw4fip7ImA9WxRVGUs."'>
<id>
http://www.google.com/base/feeds/itemtypes/en_US/_rainbow</id>
<updated>2008-11-17T22:54:41.236Z</updated>
<category scheme='http://base.google.com/categories/itemtypes'
term='_rainbow' />
<title>_rainbow</title>
<content>_rainbow</content>
<link rel='related' type='application/atom+xml'
href='http://www.google.com/base/feeds/snippets/-/_rainbow'
title='Items of type '_rainbow'' />
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/itemtypes/en_US/_rainbow' />
<gm:item_type>_rainbow</gm:item_type>
<gm:attributes>
<gm:attribute name='expiration date' type='dateTime' />
</gm:attributes>
</entry>
</feed>
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.
You can query the attributes feed by making a GET request to the attributes feed URL:
http://www.google.com/base/feeds/attributes
The attributes feed is most useful when querying for the attributes used with items that match a "base query". A request to the following URL will show 10 commonly-used attributes for items which match "digital camera" and, for each attribute, 5 common values (for text attributes).
For more information on the attributes feed, see the Feed reference.
http://www.google.com/base/feeds/attributes?bq=digital+camera&max-results=10&max-values=5
The result of the above query should look something like this:
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
xmlns:openSearch='http://a9.com/-/spec/opensearch/1.1/'
xmlns:gm='http://base.google.com/ns-metadata/1.0'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"CUINQnoyfyp7ImA9WxRVGUs."'>
<id>http://www.google.com/base/feeds/attributes</id>
<updated>2008-11-17T23:13:13.497Z</updated>
<category scheme='http://base.google.com/categories/itemtypes'
term='products' />
<title>Attribute histogram for query: digital camera</title>
<link rel='alternate' type='text/html'
href='http://base.google.com' />
<link rel='http://schemas.google.com/g/2005#feed'
type='application/atom+xml'
href='http://www.google.com/base/feeds/attributes' />
...
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/attributes?start-index=1&max-results=10&bq=digital+camera&max-values=5' />
...
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>10</openSearch:itemsPerPage>
<entry gd:etag='W/"CUINQnoyfip7ImA9WxRVGUs."'>
<id>
http://www.google.com/base/feeds/attributes/item+type%28text%29?bq=digital+camera</id>
<updated>2008-11-17T23:13:13.496Z</updated>
<title>item type(text)</title>
<content>Attribute "item type" of type text in query: digital
camera</content>
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/attributes/item+type%28text%29?bq=digital+camera' />
<gm:attribute name='item type' type='text' count='47069'>
<gm:value count='46825'>products</gm:value>
</gm:attribute>
</entry>
...
<entry gd:etag='W/"CUINQnoyfip7ImA9WxRVGUs."'>
<id>
http://www.google.com/base/feeds/attributes/price%28float+usd%29?bq=digital+camera</id>
<updated>2008-11-17T23:13:13.496Z</updated>
<title>price(float usd)</title>
<content>Attribute "price" of type floatUnit with unit "usd" in
query: digital camera</content>
<link rel='self' type='application/atom+xml'
href='http://www.google.com/base/feeds/attributes/price%28float+usd%29?bq=digital+camera' />
<gm:attribute name='price' type='floatUnit' count='46825'>
<gm:value count='1913'>9.98 usd</gm:value>
<gm:value count='1236'>6.98 usd</gm:value>
<gm:value count='1055'>4.98 usd</gm:value>
<gm:value count='868'>14.98 usd</gm:value>
<gm:value count='738'>19.98 usd</gm:value>
</gm:attribute>
</entry>
...
</feed>
This section explains how to insert items into Google Base. Refer to the Feeds Reference for information about how you can insert items using the Items feed.
To insert items, you first need to be authenticated with a Google account. Begin by requesting an authentication token as described in the Google Account Authentication documentation. The authenticated account has to be properly set up for Google Base, otherwise the insert operations will give an error. To set up the account, just log in on Google Base site.
Below is an example request for a client login authentication token. This request would be sent to https://www.google.com/accounts/ClientLogin and the server will respond with an authentication token. Note that the service name for the Google Base API is gbase
POST /accounts/ClientLogin HTTP/1.0 Content-type: application/x-www-form-urlencoded accountType=HOSTED_OR_GOOGLE&Email=jo@gmail.com&Passwd=nr23AZ&service=gbase&source=my-app-name
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 an application for a server, such as a web application. For an example of AuthSub authentication, see the authentication section on the interactive demo page.
To insert a new item into Google Base, make an HTTP POST request to the items feed
with the Atom entry for your new item as the request body. Here is an example request:
POST /base/feeds/items Content-Type: application/atom+xml Authorization: AuthSub token=... X-Google-Key: key=... <?xml version='1.0'?> <entry xmlns='http://www.w3.org/2005/Atom' xmlns:g='http://base.google.com/ns/1.0'> <author> <name>Jane Doe</name> <email>jo@gmail.com</email> </author> <title type="text">Marie-Louise's chocolate butter</title> <content type="xhtml"> <b>Ingredients:</b> <ul> <li>250g margarine,</li> <li>200g sugar,</li> <li>2 eggs, and</li> <li>approx. 8 tsp cacao.</li> </ul> <p>Mix everything. Heat while stirring, but do not allow the mix to boil. Put in a container and cool in fridge.</p> </content> <g:item_language type="text">en</g:item_language> <g:item_type type="text">testrecipes</g:item_type> <g:cuisine type="text">danish</g:cuisine> <g:cooking_time type="intUnit">10 minutes</g:cooking_time> <g:main_ingredient type="text">cacao</g:main_ingredient> <g:main_ingredient type="text">margarine</g:main_ingredient> <g:serving_count type="int">4</g:serving_count> </entry>
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 Itemtypes feed and the Attributes feed are meant to make this choice easier.
The Itemtypes feed contains a list of item types recommended by Google. For each item type, it lists the attributes that Google thinks might be useful.
To query the item types feed for attributes used in the US in the housing category,
make an HTTP GET request to
http://www.google.com/base/feeds/itemtypes/en_US/housing. The result will look something like this:
<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:gm='http://base.google.com/ns-metadata/1.0'
xmlns:batch='http://schemas.google.com/gdata/batch'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"Dk4GSHkyfSp7ImA9WxRVGUs."'>
<id>http://www.google.com/base/feeds/itemtypes/en_US/housing</id>
<updated>2008-11-17T23:35:29.795Z</updated>
<category scheme='http://base.google.com/categories/itemtypes'
term='housing' />
<title>housing</title>
<content>housing</content>
...
<gm:item_type>housing</gm:item_type>
<gm:attributes>
<gm:attribute name='listing type' type='text' />
<gm:attribute name='property type' type='text' />
<gm:attribute name='bedrooms' type='number' />
<gm:attribute name='bathrooms' type='number' />
<gm:attribute name='agent' type='text' />
<gm:attribute name='year' type='number' />
<gm:attribute name='school district' type='text' />
<gm:attribute name='hoa dues' type='number' />
<gm:attribute name='area' type='numberUnit' />
<gm:attribute name='style' type='text' />
<gm:attribute name='broker' type='text' />
<gm:attribute name='lot size' type='numberUnit' />
<gm:attribute name='zoning' type='text' />
<gm:attribute name='feature' type='text' />
<gm:attribute name='property taxes' type='number' />
<gm:attribute name='listing status' type='text' />
<gm:attribute name='school' type='text' />
<gm:attribute name='mls listing id' type='text' />
<gm:attribute name='mls name' type='text' />
<gm:attribute name='model' type='text' />
<gm:attribute name='price type' type='text' />
<gm:attribute name='price units' type='text' />
<gm:attribute name='price' type='floatUnit' />
...
</gm:attributes>
</entry>
In the Google Base API, an attribute is always identified by both its type and its name. 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, this attribute should be set to a number, instead of text. To specify a Google Base attribute along with the type, include an XML element that look like this:
<g:bathrooms type="float">2</g:bathrooms>
If users run the query: [bathrooms > 2] they
will only get your item if your bathrooms attribute is understood to be of the desired type.
Make sure you choose the correct type for your attributes to get the maximum benefit from Google Base.
To update an item which you have already posted on Google Base, perform an HTTP PUT to the URL of the specific item with the new XML. When you perform an update, all of the contents of the Atom entry are replaced with the contents of your PUT call, so be sure to include all of your desired data. Some item types need to be updated periodically to prevent expiration.
PUT /base/feeds/items/itemID
Content-Type: application/atom+xml
Authorization: AuthSub token=...
X-Google-Key: key=...
<?xml version='1.0'?>
<entry xmlns='http://www.w3.org/2005/Atom'
xmlns:g='http://base.google.com/ns/1.0'
xmlns:gd='http://schemas.google.com/g/2005'
gd:etag='W/"DU4CSH44eCp7ImA9WxRVGUg."'>
<author>
<name>Jane Doe</name>
<email>jo@gmail.com</email>
</author>
<title type="text">Marie-Louise's chocolate butter</title>
<content type="xhtml">
<b>Ingredients:</b>
<ul>
<li>250g margarine,</li>
<li>200g sugar,</li>
<li>2 eggs, and</li>
<li>approx. 8 tsp cacao.</li>
</ul>
<p>Mix everything. Heat while stirring, but do not allow the mix to boil.
Put in a container and cool in fridge.</p>
</content>
<g:item_language type="text">en</g:item_language>
<g:item_type type="text">testrecipes</g:item_type>
<g:cuisine type="text">danish</g:cuisine>
<g:cooking_time type="intUnit">10 minutes</g:cooking_time>
<g:main_ingredient type="text">cacao</g:main_ingredient>
<g:main_ingredient type="text">margarine</g:main_ingredient>
<g:serving_count type="int">4</g:serving_count>
</entry>
To remove an item from Google Base, send an HTTP DELETE request to the URL for the item.
DELETE /base/feeds/items/itemID Content-Type: application/atom+xml Authorization: AuthSub token=... X-Google-Key: key=...
In order to be able to manage your Google base items, you need to authenticate with a Google account that was properly set up for Google Base. Trying to manage your items without having a valid account for Google Base will result in an error message, even if the authentication was successful. The error messages look similar to these:
<errors>
<error type="request" reason="Service forbidden: Account not registered for Google Base. (http://www.google.com/base/basicsettings)"/>
</errors>
or
<errors>
<error type="request" reason="Service forbidden: Terms of Service acceptance required."/>
</errors>
See Handling errors section available for different client libraries for details how to parse these error messages.