Important: This is an old version of this page. For the latest version, use the links in the left-side navbar.
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).
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/opensearchrss/1.0/'
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'>
<id>http://www.google.com/base/feeds/snippets</id>
<updated>2007-09-13T16:45:52.167Z</updated>
<title type='text'>Items matching query: digital camera</title>
...
<link rel='self' type='application/atomxml'
href='http://www.google.com/base/feeds/snippets?start-index=1&max-results=25&bq=digitalcamera' />
<link rel='next' type='application/atomxml'
href='http://www.google.com/base/feeds/snippets?start-index=26&max-results=25&bq=digitalcamera' />
<author>
<name>Google Inc.</name>
<email>base@google.com</email>
</author>
<generator version='1.0' uri='http://base.google.com'>
GoogleBase</generator>
<openSearch:totalResults>2766128</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>25</openSearch:itemsPerPage>
<entry>
<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/atomxml'
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>
<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/atomxml'
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>
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 Google Data feed which contains information about the item type or types you requested. The results 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/opensearchrss/1.0/' xmlns:gm='http://base.google.com/ns-metadata/1.0' xmlns:batch='http://schemas.google.com/gdata/batch'> <id>http://www.google.com/base/feeds/itemtypes/en_US</id> <updated>2007-08-29T18:22:38.728Z</updated> <title type='text'>Item types for locale en_US</title> <link rel='alternate' type='text/html' href='http://base.google.com' /> ... <link rel='self' type='application/atomxml' 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>17</openSearch:totalResults> <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>25</openSearch:itemsPerPage> <entry> <id> http://www.google.com/base/feeds/itemtypes/en_US/products</id> <updated>2007-08-29T18:22:38.725Z</updated> <category scheme='http://base.google.com/categories/itemtypes' term='products' /> <title type='text'>products</title> <content type='text'>products</content> <link rel='related' type='application/atomxml' href='http://www.google.com/base/feeds/snippets/-/products' title='Items of type 'products'' /> <link rel='self' type='application/atomxml' 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> <id>http://www.google.com/base/feeds/itemtypes/en_US/jobs</id> <updated>2007-08-29T18:22:38.726Z</updated> <category scheme='http://base.google.com/categories/itemtypes' term='jobs' /> <title type='text'>jobs</title> <content type='text'>jobs</content> <link rel='related' type='application/atomxml' href='http://www.google.com/base/feeds/snippets/-/jobs' title='Items of type 'jobs'' /> <link rel='self' type='application/atomxml' 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> <id> http://www.google.com/base/feeds/itemtypes/en_US/businesslocations</id> <updated>2007-08-29T18:22:38.728Z</updated> <category scheme='http://base.google.com/categories/itemtypes' term='business locations' /> <title type='text'>business locations</title> <content type='text'>business locations</content> <link rel='related' type='application/atomxml' href='http://www.google.com/base/feeds/snippets/-/businesslocations' title='Items of type 'business locations'' /> <link rel='self' type='application/atomxml' href='http://www.google.com/base/feeds/itemtypes/en_US/businesslocations' /> <gm:item_type>business locations</gm:item_type> <gm:attributes> <gm:attribute name='location' type='location' /> </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 quering 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).
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/opensearchrss/1.0/' xmlns:gm='http://base.google.com/ns-metadata/1.0' xmlns:batch='http://schemas.google.com/gdata/batch'> <id>http://www.google.com/base/feeds/attributes</id> <updated>2007-08-29T18:43:50.051Z</updated> <category scheme='http://base.google.com/categories/itemtypes' term='products' /> <title type='text'>Attribute histogram for query: digital camera</title> <link rel='http://schemas.google.com/g/2005#feed' type='application/atomxml' href='http://www.google.com/base/feeds/attributes' /> ... <link rel='self' type='application/atomxml' href='http://www.google.com/base/feeds/attributes?start-index=1&max-results=10&bq=digitalcamera&max-values=5' /> ... <openSearch:startIndex>1</openSearch:startIndex> <openSearch:itemsPerPage>10</openSearch:itemsPerPage> <entry> <id> http://www.google.com/base/feeds/attributes/itemtype%28text%29?bq=digitalcamera</id> <updated>2007-08-29T18:43:50.051Z</updated> <title type='text'>item type(text)</title> <content type='text'>Attribute "item type" of type text in query: digital camera</content> <link rel='self' type='application/atomxml' href='http://www.google.com/base/feeds/attributes/itemtype%28text%29?bq=digitalcamera' /> <gm:attribute name='item type' type='text' count='199798'> <gm:value count='194526'>products</gm:value> </gm:attribute> </entry> <entry> <id> http://www.google.com/base/feeds/attributes/price%28floatusd%29?bq=digitalcamera</id> <updated>2007-08-29T18:43:50.051Z</updated> <title type='text'>price(float usd)</title> <content type='text'>Attribute "price" of type floatUnit with unit "usd" in query: digital camera</content> <link rel='self' type='application/atomxml' href='http://www.google.com/base/feeds/attributes/price%28floatusd%29?bq=digitalcamera' /> <gm:attribute name='price' type='floatUnit' count='191832'> <gm:value count='10767'>9.98 usd</gm:value> <gm:value count='6432'>13.98 usd</gm:value> <gm:value count='5664'>14.98 usd</gm:value> <gm:value count='4902'>7.98 usd</gm:value> <gm:value count='3412'>19.98 usd</gm:value> </gm:attribute> </entry> <entry> <id> http://www.google.com/base/feeds/attributes/location%28location%29?bq=digitalcamera</id> <updated>2007-08-29T18:43:50.051Z</updated> <title type='text'>location(location)</title> <content type='text'>Attribute "location" of type location in query: digital camera</content> <link rel='self' type='application/atomxml' href='http://www.google.com/base/feeds/attributes/location%28location%29?bq=digitalcamera' /> <gm:attribute name='location' type='location' count='30069'> <gm:value count='239'>houston tx us</gm:value> <gm:value count='112'>miami fl us</gm:value> <gm:value count='91'>chicago il us</gm:value> <gm:value count='89'>atlanta ga us</gm:value> </gm:attribute> </entry> ... <entry> <id> http://www.google.com/base/feeds/attributes/itemrank%28float%29?bq=digitalcamera</id> <updated>2007-08-29T18:43:50.051Z</updated> <title type='text'>item rank(float)</title> <content type='text'>Attribute "item rank" of type float in query: digital camera</content> <link rel='self' type='application/atomxml' href='http://www.google.com/base/feeds/attributes/itemrank%28float%29?bq=digitalcamera' /> <gm:attribute name='item rank' type='float' /> </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. Begin by requesting an authentication token as described in the the Google Account Authentication documentation.
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 auth sub 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>JaneDoe@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 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.
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'> <id>http://www.google.com/base/feeds/itemtypes/en_US/housing</id> <category scheme='http://base.google.com/categories/itemtypes' term='housing' /> <title type='text'>housing</title> <content type='text'>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='broker' type='text' /> <gm:attribute name='lot size' type='numberUnit' /> <gm:attribute name='zoning' type='text' /> <gm:attribute name='listing status' type='text' /> <gm:attribute name='school' type='text' /> <gm:attribute name='mls listing id' type='text' /> <gm:attribute name='location' type='location' /> <gm:attribute name='price' type='floatUnit' /> <gm:attribute name='price type' type='text' /> <gm:attribute name='price units' type='text' /> ... </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 items types need to be updated periodically to prevent expiration.
PUT /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>JaneDoe@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/1263232256914517833 Content-Type: application/atom+xml Authorization: AuthSub token=... X-Google-Key: key=...