Google Base Data API

Getting Started

Developer's Guide

Reference Guide

Related Links

Getting Started

This chapter will help you get started using the Google Base data API.

Audience
Google Base terminology
Google Base data API services
Accessing Google Base
Testing
Troubleshooting
1. Disapproved items
Writing a Google Base data API application

Audience

The Google Base data API documentation is intended for programmers who want to write client applications that interact with Google Base. This documentation assumes that you are familiar with HTTP protocol and the Atom syndication format. Since the Google Base data API is a Google Data API, you should also familiarize yourself with the Google Data API.

Google Base terminology

In order to understand this chapter, you'll need to be familiar with the terms presented in this section. Because Google Base defines these terms slightly differently than the XML standard, you should read this section carefully, even if you're already familiar with XML.

Data items

A data item is an XML construct that describes a single entry in Google Base. Each data item consists of a set of attributes that describe it. You can see an example of a data item below.

Attributes

Attributes are typed name/value pairs that describe the content. Each attribute associates a value with an attribute name to describe the data item. For example, in Google Base, <g:label>kung pao chicken</g:label> is an attribute (rather than an element.) You can specify multiple values for a single attribute name. For example, the data item below specifies multiple values for the label attribute. See Attributes and Queries for more information about attributes.

Item types

The item type describes the type of data. Valid Google Base item types include recipe, housing, and products. Each item type has a set of recommended attributes for describing it. For instance, items of type recipe should use the recommended attributes main ingredient and cuisine . There are many standard item types in Google Base, each with its own set of recommended attributes. The Recommended Attributes page lists the valid item types and their associated approved attributes.

Google Base data API services

The Google Base data API exposes the following functionality via a webservice:

searching for data items
discovering metadata
inserting, updating, and deleting data items

Searching for data items

You can use the API to create a client that searches for items programmatically. Your client can send a query and retrieve a specified number of data items that match the query. The Google Base data API supports structured queries that express constraints on attributes and their values. For example, you can create specific queries, search for all items that use a certain label or you can exclude certain attributes and values. You can also perform unstructured queries on the contents of Google Base. You can execute queries against either the public snippets feed ( /feeds/snippets ) or your own specific items feed ( /feeds/items), depending on the scope of data you want to retrieve.

By referencing attributes in your search query, you can obtain very specific results. For example, you can search for cars manufactured in 2004, or you can look for jobs in Denver, Colorado.

Data available in Google Base

Here is a current snapshot of some of the most popular item types available in Google Base. Refer to the Google Base homepage for a more complete list. Don't feel limited to the types below; you can also create your own custom item type.

Executing queries

You can execute queries using a curl command entered into a Unix shell, as follows:

 curl "queryURI" | xmllint --format -

Alternately, you can enter the URI in a browser window. If you execute the query in a feed-enabled browser, you must view the source of the result page in order to see the complete result feed.For more information about how to search for data items, refer to Attributes and Queries.

Data feeds

The Google Base data API provides two feeds for data: Then snippets feed is a read-only feed that is used to access all published items in Google Base. This feed does not require authentication. You can perform attribute and full text queries on this feed. The items feed is a read/write, customer-specific feed that you can use to insert, update, delete, and query your own data. This feed requires authentication. Note that all data submitted to Google Base is public, except for any attributes that you explicitly hide. The items feed is simply a convenient way to view the items you added to Google Base.

Discovering metadata

You can use the API to get information about how Google Base data is structured and how each item type is used. This information can be helpful when you are deciding what to query on, and also when you are deciding how to describe new items you post. Google Base associates certain attributes with specific item types. For example, job type and job function are attributes associated with the jobs item type. To see which attributes to use with a specific item type, use the itemtypes metadata feed. For more information about how to discover metadata, refer to Attributes and Queries.

Meta-data feeds

There are three feeds for metadata: the attributes feed, the item types feed, and the locales feed.The item types feed contains referential information about the Google Base schema. It shows the attributes that Google Base recommends you use to describe your items. The item types feed uses <gm:item_type> to identify each item type for which there is a set of recommended attributes, <gm:attributes> to indicate a list of attributes, and <gm:attribute> to identify each attribute. If you want metadata about the item types or wish to look at the recommended schema for an item type, use the item types feed.The attributes feed returns attribute histograms for items that match a given query. The feed lists frequent attributes and attribute values. The attributes feed uses <gm:attribute> to identify each attribute for which there is a set of values and <gm:value> to identify each value. If you want to see which attributes and attribute values are most frequently used for a particular item type, use the attributes feed. The locales feed defines the supported locales for Google Base. Each locale has its own list of recommended item types. You need to specify the locale when accessing the item types feed.

Item types

To help standardize some of the data entered, Google Base promotes a set of item types, as well as approved attributes for each item type. You can see the current list of item types and by looking at the Recommended Attributes document, or you can request an item types feed. You do not have to restrict yourself to this list, but if you do, your data is more likely to be found by other users.

If you look at the attributes in the item types feed, you can see that certain attributes have been defined for each item type. Others are item type-specific. For instance, job type, job function, job industry, and employer are defined attributes for the jobs item type.

If your data doesn't correspond at all to the existing item types, you can create your own item type. If your data is similiar in structure to one of the existing item types, it's probably best to use the most similar item type, and add custom attributes to it.

If you invent your own item type, you can use existing approved attributes, as well as create new attributes for your item type. If you choose to create a new item type, bear in mind that the title attribute and the item type attribute are required. Aside from these two, you can use whichever attributes you want.

There are a few attributes, like title, that should be included for every item, regardless of the type. These are called Universal attributes. There are also some universal attributes that are automatically generated by Google Base, such as modification time. You can query on some universal attributes, but not all of them. Finally, some attributes, such as id, can be defined by the user, but if they are not, will be automatically generated. The linked page provides more information.

If you create your own attributes, they will be indexed, unless you specify that they should be private.

Attributes

There are two different notations for specifying attributes:

an XML-based notation in the context of an Atom or JSON feed describing the attributes of data items, and
the Google Base query language notation used in a URL describing your search criteria.

In Atom feeds, attributes correspond to XML elements in either the Atom namespace (atom:) or the Google Base namespace (g:). The standard Atom elements, including title, content, link, id, category, author, created and updated, are supported and mapped to the corresponding Google Base attributes. Here is an example of what definitions in the Google Base namespace look like:

<g:attribute_name type="attributeType">
    attribute value
</g:attribute_name>

An attribute definition consists of an attribute name (the XML tag,) an attribute type, and the attribute value. The Attribute Types section contains a list of the supported attribute types. Note that specifying the attribute type is optional. If recommended attributes are used, Google Base will infer the corresponding type from the attribute name. Refer to Recommended Attributes for a list of recommended attributes. Within the recommended attributes, there are a number of universal attributes that can be used with every item type. Each item type has an individual set of attributes specific to items of this type. Spaces are not allowed in attribute names. Use an underscore instead.For instance, the job type attribute can be specified via the XML element <g:job_type>. Here are some sample attributes of the jobs itemtype from an Atom feed entry.

<g:employer>Hewlett Packard</g:employer>
<g:job_type>full time</g:job_type>
<g:job_industry>Computers</g:job_industry>
<g:job_function>Marketing</g:job_function>

The Google g namespace needs to be defined in your input feed as:

xmlns:g="http://base.google.com/ns/1.0"

If you want to add a custom attribute to your item, you must add it as part of the g: namespace. If you attempt to add a custom attribute as part of the atom: namespace, the attribute will be silently dropped from your item. Google Base will throw an error if you try to insert an item in any namespace except for g: or atom:.

The notation for defining constants on attributes in queries is not based on XML. Namespace definitions are superfluous and spaces do not have to be escaped using underscores. In general, a query constraining the value of an attribute looks like this:

 [attribute_name(attributeType): attribute value query]

Brackets are used to associate an attribute name with a type and a query constraining the value of this attribute. Such an attribute query will match items that define an attribute of the given name and type with a value that matches the given value query. Again, types are optional, and most queries will look like this:

 [attribute_name: attribute value query]

For example, here's a job-related query:

 [employer: Apple]  [job_type: full time]  [job_function: Marketing]

This query will match items that define an employer attribute of type text that contains the term Apple, a job_type text attribute that matches both the terms full and time, and a job_function text attribute that contains the term Marketing in its attribute value.

Attribute limitations

There are some limitations on how long your attribute names and values can be and how many you can use:

titles: between 3-1000 characters
attributes:
- names: 30 characters
- attribute text: 1000 characters, including spaces
- total number permitted: 30 per item
labels:
- names: 40 characters
- total number permitted: 10 per item
URL length: 1000

Metadata namespace

The gm namespace is used to represent metadata. It is identified by the URL http://base.google.com/ns-metadata/1.0. For example, the item types feed describes attributes using the <gm:attribute> element. Similarly, the attributes feed uses the <gm:attribute> and <gm:value> to represent attribute histograms. Finally, the items feed provides access to statistics that keep track of the number of clicks, impressions, and page views for each item. This information is stored, respectively, in the <gm:impressions>, <gm:clicks>, and <gm:page_views> elements.The meta-data attributes are read-only.

Inserting, updating, and deleting data items

You can use the Google Base data API to programmatically post new items, and edit or delete items you have posted. You must use your own items feed to insert, update, or delete data.

If possible, you should try to use one of the recommended itemtypes to represent your data. If the itemtype doesn't exactly fit your application, you can add custom attributes to suit your needs.

You may also create your own item type, if necessary. However, if you do so, it will be much more difficult for other people to find your data, since only the recommended itemtypes are publicized.

If you choose to create your own item type, your item must have a title, and must belong to one of the accepted locales. You can choose your own itemtype name, and use the item without any restrictions.

Data namespaces

When you are defining the attributes for a new Google Base item, it is important to use the correct namespace in the XML input file.The XML encoding of Google Base items uses the Atom and Google Base namespaces. Attributes like <title>, <link>, <entry>, <id>, and <category> are encoded as XML elements in the Atom namespace. All other attributes use the Google Base namespace. This namespace is identified by the URL http://base.google.com/ns/1.0 . In the following example, the first several attributes, such as <title> and <author>, are standard Atom attributes. The next set of <g:main_ingredient> tags define Google Base recommended attributes. And the last set, such as <g:spices_used> and <g:cook_technique> are user-defined attributes.

Every item is required to have the <title> and <g:item_type> elements. You can optionally include a <g:id> element to uniquely identify your items. If included, Google Base will consider this attribute value as a surrogate ID for your item.

When you insert a new item, you can optionally specify a value for the <g:id> element. The value of <g:id> should be unique among all of your items. If your INSERT operation specifies a <g:id> that is already used by another one of your Google Base items, the data in that item will be overwritten by the data in the new item.

Once an item is inserted into Google Base, you will not be able to change the value of its <g:id> attribute, or remove the attribute. If you attempt to do so, the server will return an error.

<?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>
    <category scheme='http://www.google.com/type' term='googlebase.item'/>
    <title type='text'>He Jingxian's chicken</title>
    <content type='xhtml'>
      <div xmlns='http://www.w3.org/1999/xhtml'>Delectable Sichuan specialty</div>
    </content>
    <link rel='alternate' type='text/html' href='http://www.host.com/123456jsh9'/>
    <g:item_type>Recipes</g:item_type>
    <g:cooking_time>30</g:cooking_time>
    <g:main_ingredient>chicken</g:main_ingredient>
    <g:main_ingredient>chili peppers</g:main_ingredient>
    <g:main_ingredient>peanuts</g:main_ingredient>
    <g:spices_used>Szechuan peppercorn</g:spices_used>
    <g:cook_technique>blackened</g:cook_technique>
</entry>

Hiding Attributes

You can control whether attributes are visible by specifying the XML attribute access="private". For instance, if you include the following attribute definition in an entry:

<g:private_id type="text" access="private"> 
   this is not visible by others 
</g:private_id>

then the <private_id> element will not appear on the snippets feed, and will consequently not be visible by other users. It will, however, be visible on the items feed, so that you can access it for queries or updates.

You should only mark your custom attributes as private. All Google-recommended attributes are public and you should not try to make them private. If you do, your items will fail validation.

If the access attribute is not specified, the content of the corresponding item will be public so that everyone can see it. This is the default behavior.

Hiding items

You can use the <app:draft> extension element, defined in the Atom Publishing Protocol, to upload an item as a draft. You can see draft items on your own items feed. However, they are not visible on the snippets feed, and are not searchable.

In order to mark an item as a draft, include the <app:control> element as follows:

<entry>
   ...   
	<app:control xmlns:app='http://purl.org/atom/app#'>
		<app:draft>yes</app:draft>
	</app:control> 
</entry>

When the item is ready for public release, remove the <app:control> element, or set the <app:draft> flag to no. Note that if the item is disapproved, you will not be able to change the value of the <app:draft> flag.

You can also set the <app:draft> flag on an existing item to remove it from the snippets feed.

Inserting reference attributes

Google Base supports an attribute type called reference. You can use a reference to create a link from one Google Base item to another.

For example, you could have a business locations item that describes your business location, and one or more products items that link to this location item. Then, if you decide to update the location attribute of the business location, you can then run a query for all of your products that reference that business location to make sure you update all of the products listings. (Note, however, that if you do this, you should still include a valid business address within the location attribute of your products listing to ensure that your product will come up in location-specific queries.)

Each reference attribute may point to exactly one item in Google Base. You can, however, create multiple reference attributes to point to several items from within a single Google Base item. For example, you could point to two business locations items from a single products listing by creating two reference attributes.

You can link to any item in Google Base, not just to the items in your items feed.

You may name a reference attribute anything, as long as you follow the standard attribute naming rules. The attribute type must be reference. The content of a reference attribute must be set to the ID of the item you wish to reference.

You reference a document based on its ID, as stored in the Atom <id> tag. The ID is a URL, consisting of a path and a numeric value. Google Base assigns the numeric part of the ID to each item upon creation. The preferred way of referencing another item is with the snippets feed URL:

http://www.google.com/base/feeds/snippets/17891817243016304554

For convenience, you may also specify a reference using the items feed URL, or simply the numerical portion of the item ID:

http://www.google.com/base/feeds/items/17891817243016304554
17891817243016304554

Although Google Base accepts these various input formats, it will always return the snippets version.

The following are reference attributes:

<g:business type='reference'>http://www.google.com/base/feeds/items/17891817243016304554</g:business>
<g:brand type='reference'>http://www.google.com/base/feeds/snippets/15670381360807634994</g:brand>

Using images

There are two ways to upload images with your Google Base items:

using the image_link attribute
using the media feed

Regardless of the method you choose, Google Base will automatically generate thumbnail images so that you can display your images in your application.

Each image file you upload may not exceed 1 megabyte, 2800 by 2800 pixels, or 8 million pixels in total size. The five common accepted image formats are:

image/bmp
image/gif
image/jpeg
image/png
image/tiff

As with all files you upload to Google Base, Google reserves the right to review all items in order to ensure they comply with the Google Base Terms and Conditions.You can upload up to 10 images per item. Google Base only stores the thumbnails it creates. It never stores the original image, so you should keep a backup copy of that elsewhere.

When you upload an image using the image_link attribute, the images are uploaded asynchronously from a web location of your choice. This has the following implications:

Google Base won't upload the data instantaneously. Instead, we'll register it so it can be crawled at some point in the future. The image must remain available at the location you specify until it is crawled.
If the image has not yet been uploaded the first time someone tries to access it, the image server will have to perform the upload synchronously. As a result, the initial access of the image might take longer.
If Google Base is unable to download the image, no error message will be sent, because the image download process is asynchronous.

If you have access to the binary image file, you should use the media feed to upload your image. You can pass the image directly using the media feed, and thus never need to post the image at an external URL. The media feed uploads images synchronously, so you will receive an error message if the insert in the image server fails.

Using the image_link Attribute in the Items feed

You provide images with the image_link attribute as follows:

<g:image_link>http://www.myphotos.com/images/cameras/digital_camera.JPG</g:image_link>

Google Base caches the provided image and normalizes it to fit within the Google webpages.

When you use the image_link attribute, you cannot upload images from a local machine. They must reside online.

When you upload an item that contains an image_link attribute, Google Base will try to retrieve the image from the stated location, create a set of thumbnails for it, and push it to the image server on GoogleHosted.

Google Base generates different sizes of thumbnails for each submitted image. All generated thumbnails are square. If the image you submit is not square, it is scaled down, and any white space is equally distributed.

Links to thumbnails are added as a set of gm:thumbnail child attributes to the image_link attribute. The content of each gm:thumbnail attribute contains the URL that points to the generated thumbnail. The gm:thumbnail attribute also includes XML attributes that specify the width and height of the image in pixels.

For example, assume you insert an image as follows:

<g:image_link>http://www.mySite.com/myImage.png</g:image_link>

Google Base will generate thumbnails for the image and return the locations for those thumbnails as follows:

<g:image_link type='url'>http://www.mySite.com/myImage.png
   <gm:thumbnail width='60' height='60'>
      http://base.googlehosted.com/base_media?q=http%3A%2F%2Fwww.mySite.com%2FmyImage.png&amp;dhm=59c821bd&amp;size=5
   </gm:thumbnail>
   <gm:thumbnail width='120' height='120'>
      http://base.googlehosted.com/base_media?q=http%3A%2F%2Fwww.mySite.com%2FmyImage.png&amp;dhm=59c821bd&amp;size=3
   </gm:thumbnail>
   <gm:thumbnail width='400' height='400'>
      http://base.googlehosted.com/base_media?q=http%3A%2F%2Fwww.mySite.com%2FmyImage.png&amp;dhm=59c821bd&amp;size=6
   </gm:thumbnail>
</g:image_link>

Using the Media Feed

You can use the media feed to manage binary attachments to your Google Base items.

The media feed differs from the other Google Base feeds in that there is one media feed defined per Google Base item (rather than one global feed, as with the other feeds.) Each item's media feed manages binary attachments for that item.

You can use an item's media feed to:

add and delete binary attachments for that item
query for information about an item's attachments

Each item may contain up to 10 attached binary files.

Attachments uploaded via the media feed are processed immediately. For each passed attachment, Google Base creates a set of thumbnails of the attachment, and stores the thumbnails on the Google Base server.

An example of an entry on the media feed is as follows:

<entry>
  <id>http://www.google.com/base/feeds/items/123456789/media/hand-4643717529959824417</id>
  <published>2007-09-06T07:59:15.000Z</published>
  <updated>2007-09-06T07:59:15.000Z</updated>
  <title type='text'>New digital camera</title>
  <content type='image/jpeg' 
    src='http://base.googlehosted.com/base_media?q=hand-4643717529959824417&amp;size=1'/>
  <link rel='self' type='application/atom+xml' 
    href='http://www.google.com/base/feeds/items/123456789/media/hand-4643717529959824417'/>
  <link rel='edit' type='application/atom+xml' 
    href='http://www.google.com/base/feeds/items/123456789/media/hand-4643717529959824417'/>
  <media:content xmlns:media='http://search.yahoo.com/mrss/' 
    url='http://base.googlehosted.com/base_media?q=hand-4643717529959824417&amp;size=1' 
    type='image/jpeg' medium='image'>
    <media:thumbnail 
      url='http://base.googlehosted.com/base_media?q=hand-4643717529959824417&amp;size=5' 
      height='60' width='60'/>
    <media:thumbnail 
      url='http://base.googlehosted.com/base_media?q=hand-4643717529959824417&amp;size=3' 
      height='120' width='120'/>
    <media:thumbnail 
      url='http://base.googlehosted.com/base_media?q=hand-4643717529959824417&amp;size=6' 
      height='400' width='400'/>
  </media:content>
</entry>

Each media feed entry describes a single attachment.

The contents of the <title> attribute are used as both the image's title and its caption.

The link rel='edit' attribute points to the media feed for an item. This attribute is created when you create the attachment. You can later use it to retrieve, update and delete the attachment.

<link rel='edit' type='image/jpeg' 
   href='http://www.google.com/base/feeds/items/123456789/media/hand-4643717529959824417'/>

Each attachment has a unique identifier within the media feed. This identifier is the suffix of the URL contained in the id, link rel='self' and link rel='edit'. For the above example, the attachment's identifier is hand-4643717529959824417.

The thumbnail identifiers are contained in the media:content attribute. media:content points to the location on http://base.googlehosted.com where the image is loaded.

The set of thumbnails linked in the media:content attribute will have consistent sizes from one item to another. These thumbnails have been preprocessed to remove image viruses and spyware, and converted to jpeg format. The atom:content points to the same URL as the media:content.

<media:content 
  xmlns:media='http://search.yahoo.com/mrss/' 
  url='http://base.googlehosted.com/base_media?q=hand-4643717529959824417&amp;size=1' 
  type='image/jpeg' 
  medium='image'>
  <media:thumbnail 
    url='http://base.googlehosted.com/base_media?q=hand-4643717529959824417&amp;size=5' 
    height='60' width='60'/>
  <media:thumbnail 
    url='http://base.googlehosted.com/base_media?q=hand-4643717529959824417&amp;size=3' 
    height='120' width='120'/>
  <media:thumbnail 
    url='http://base.googlehosted.com/base_media?q=hand-4643717529959824417&amp;size=6' 
    height='400' width='400'/>
</media:content>

The published and updated attributes reflect the timestamp of the most recent modification of the parent item, not the modification of the attachment.

Every attachment contains a title, specified in the title attribute. You can define the title when you create the attachment. If you don't, a title will be automatically generated.

Posting an attachment

There are two ways to add an attachment to an item:

Upload the binary image data along with its metadata. To do this, use MIME content type "multipart/related"; send attachment metadata in one part of the POST body, and binary-encoded image data in another part. This is the preferred approach.
Upload the binary image data without the metadata.

Post an attachment with metadata

You can create an attachment by passing an entire media feed entry with a binary attachment to the media feed using a POST request:

POST http://base.google.com/base/feeds/items/item_id/media/

For example, POST http://base.google.com/base/feeds/items/123456789/media/ creates an attachment for the item with the ID 123456789.

The following example shows a multipart posting that uploads both binary and metadata.

POST /base/feeds/items/123456789/media
Content-Type: multipart/related; boundary="END_OF_PART"
Content-Length: 24680246
MIME-version: 1.0

Media multipart posting
--END_OF_PART
Content-Type: application/atom+xml

<entry xmlns='http://www.w3.org/2005/Atom'>
  <title>Powerful Powershot</title>
  <category scheme="http://schemas.google.com/g/2005#kind"

    term="http://schemas.google.com/attachments/2007#attachment"/>
</entry>
--END_OF_PART

Content-Type: image/jpeg

...binary image data goes here...
--END_OF_PART--

If you pass an entire entry, you should only specify a value for the title attribute. All other attributes, including summary, will be ignored and discarded. The <title> element contains the filename you want to use for the image.

Post an attachment without metadata

To send an attachment without its associated metadata, post to the same URL:

POST http://base.google.com/base/feeds/items/item_id/media/

And use the following format for the body of the POST:

Content-Type: image/jpeg
Content-Length: 47899
Slug: My amazing photograph
... other HTTP Headers, like Cache-Control, Connection ...


... binary image data goes here ...

When you post an attachment without metadata, you can use the Slug: HTTP header to set the title of an attachment. The client library contains helper methods for creating the slug header.

Updating an attachment

You can only replace the attachment's title.

You can update an attachment's binary data by deleting the item and re-inserting an updated item. This implies a DELETE call and a POST call. Note that this will result in a new item ID.

Updating the title

You update an attachment's title by passing in the entry with the modified data. The link rel='edit' attribute identifies the attachment to update.

PUT http://base.google.com/base/feeds/items/item_id/media/attachment_id

For example, PUT http://base.google.com/base/feeds/items/123456789/media/555 can be used to update the title of the attachment with the identifier 555 that is associated with the item with the ID 123456789.

The URI is the value of the <link rel="edit"> tag that was returned after you did the earlier POST.

In the body of the PUT, provide the updated metadata, in the form of an <atom:entry> element containing image metadata.

Note: As usual with GData, you can't do a partial update of an entry; you have to send the full entry metadata to replace the existing metadata.

The attachment itself is not re-sent to the server.

Deleting an attachment

You delete an attachment by making an HTTP DELETE request on the attachment's URL. The link rel='edit' attribute identifies the attachment to delete. You delete an attachment with the following DELETE request:

DELETE http://base.google.com/base/feeds/items/item_id/media/attachment_id

Querying for information about an item's attachments

To retrieve a feed containing a single attachment, make a GET request that includes the attachment_id:

GET http://base.google.com/base/feeds/items/item_id/media/attachment_id

You can also retrieve a feed containing all attachments for an item by making a GET request with no attachment_id:

GET http://base.google.com/base/feeds/items/item_id/media/

The media feed supports the Google Base data API standard query parameters.

When you send the GET request, Google Base returns an HTTP 200 OK status code and a feed containing the requested items. Each item contains links to the generated thumbnails for each attachment.

Retrieving thumbnails

Regardless of how you post your binary content, be it from the PFE, Feeds, or the API, using image_link or the media feed, you can retrieve links to the generated thumbnails by setting the query content argument to all or thumbnails.

Specifying shipping rules

If you insert an item that includes shipping information, you must describe it using the <g:shipping> element. The <g:shipping> element contain the following subelements:

<g:country> is a two-letter ISO 3166 country code that describes the country of origin of the item. <g:country> is required.
<g:service> is a free-form description of the mode of transportation for the item. <g:service> is optional.
<g:price> is the price of the item, a space, and a three-character currency code. <g:price> is optional.

<g:shipping>
   <g:country> US </g:country>
   <g:service> By monkey </g:service>
    <g:price> 20 EUR </g:price>
 </g:shipping>

Each item may have a maximum of 10 shipping rules. Multiple shipping methods with the same region and shipping service are not allowed.

shipping is the only attribute that can be of type shipping.

Inserting attributes with non-geocodable locations

When you insert an attribute of type location, Google Base attempts to calculate the coordinates of the address. If an address cannot be geocoded, either because the address isn't recognized or because there are multiple matches, the Google Base data API returns an error.If you know where an address is, you can specify the geographic location of the address by adding two elements to your item: <g:latitude> and <g:longitude>. The values of these attributes must be the geographic latitude and longitude you wish to associate with the address string. Both values must be numbers, and they must fall within the valid range. The valid range for latitude is from -90.0 through 90.0. The valid range for longitude is from -180.0 through 180.0, exclusive. If you add the latitude and longitude to a location using these attributes, Google Base will not attempt to geocode the address string, and instead will accept the geographic location you submitted. The following example submits latitude and longitude with an address string:

<g:location>
    My Favorite Beach
    <g:latitude>37.0</g:latitude>
    <g:longitude>-122.5</g:longitude>
</g:location>

If you specify the latitude and longitude when you submit the item, you can later query on these values. If you submit a geocodable location, the latitude and longitude are calculated, but not returned in query feeds.

Accessing Google Base

To use the Google Base data API from your application, you need to:

obtain an API key
know the URLs for the Google Base servers:
- The default data server is http://www.google.com/base/ .
- The default authentication server is https://www.google.com/accounts/.
authenticate the customer if your application performs inserts, updates, or deletes

All of the feeds require you to specify an API Key when making a request. To query for customer-specific data or to insert, update, or delete data, you need to perform authentication. The API Demo Page has code that obtains web authentication tokens for you. If you are using the API instead, you need to provide a valid username and password to the defined authentication server to be able to access the items feed. If you are doing queries on the public snippets feed, you do not need to be authenticated.

Authenticating the user

If you are doing a query against the public snippets feed, you do not need to be authenticated. The public data includes all data and is available for read-only access by anyone.If, however, you want to insert, update, or delete data, you need to go against the customer items feed and you need to be authenticated. Customer-specific data is available for read-write access by each customer. Only the owner of a piece of data can change or remove it. Also, as a customer, you can choose to limit your query to your own data and you need to be authenticated for this type of query. There are two methods for authentication. Desktop applications, such as the Google Base Java samples, use a Google-specific authentication system called Programmatic Login and web applications, such as the Google Base web-UI demo application, use another approach, called AuthSub. Both require a username and password.If you use the Programmatic Login system, the desktop client asks the user for their credentials, and then sends those credentials to the Google authentication system. If authentication succeeds, then the authentication system returns a token that the client subsequently uses (in an HTTP Authorization header) when it sends GData requests. If authentication fails, then the server returns a 403 Forbidden status code, along with a WWW-Authenticate header containing a challenge applicable to the authentication.In the AuthSub system, the client connects the user to a Google service that requests credentials. The service then returns a token that the web application can use. In this way, Google (rather than the web front end) securely handles and stores the user's credentials. The API Demo Page uses AuthSub to authenticate users. With this form of authentication, customers log in to a page that provides their username and password to a Google authentication server. The AuthSub processing creates a token that is then passed back to the demo page and is used to authenticate you whenever you perform an action (insert, update, delete) from that page. For more information, see the AuthSub documentation and the Google data API Developer's Guide.In summary, AuthSub consists of these two steps:

Get one-time upgradable token.
The third-party application sends the user to http://www.google.com/accounts/AuthSubRequest to authorize the application to act on their behalf. When the user clicks the "Grant" permission button, Google redirects the user back to the application, appending the token to the URL.
Upgrade to multi-use session token.
The application sends a GET request to http://www.google.com/accounts/AuthSubSessionToken with an HTTP Authorization header that includes the one-time token. The Google frontend responds with the multi-use session token in the body.

Once you have a token, you pass it as part of every request you send to Google Base. The following example shows how to use curl to access the published items of a customer/user of the application in the items feed:

 curl --header "Authorization:AuthSub token=<YOUR AUTHSUB TOKEN HERE>" 
    -I http://www.google.com/base/feeds/items?bq=recipes

Authenticating the developer

In order to develop a Google Base application, you will need an API key. You will need a valid Google account in order to get an API key. If you don't already have a valid Google account, go to http://www.google.com to get one. To get an API key, you must agree to the terms of service. You will need to supply this API key every time you make a request to the Google Base data API. You can supply the key parameter in three ways: In the HTTP header of your request, as in the following example:

X-Google-Key: key=ABQIAAAA2P3O4IU5JL23H452LKJ34HEDJFHQWI04985QWEKLTJJQ43

As a query parameter in the URL, as in the following example:

http://www.google.com/base/feeds/items?bq=digital+camera&key=ABQIAAAA2P3O4IU5JL23H452LKJ34HEDJFHQWI04985QWEKLTJJQ43

Using curl , as in the following example. The URL being passed includes a query that searches for recipes.

curl --header "X-Google-Key: key=ABQIAAAA2P3O4IU5JL23H452LKJ34HEDJFHQWI04985QWEKLTJJQ43" 
   -I http://www.google.com/base/feeds/snippets?bq=recipes

Managing multiple clients

Aggregators can use Google Base to manipulate data on behalf of their customers.To become an aggregator, send a request to the Google Base team. Once your account has been configured to manage multiple clients, you will be able to see your customers' IDs in the Google Base dashboard. To submit an operation on behalf of a customer, insert the customer ID in the path of the Customer Items feed as follows: http://www.google.com/base/feeds/customer_ID/items For example, if the customer ID is 12345, the URL would be http://www.google.com/base/feeds/12345/items You can perform all of the standard Items feed operations on this URL. Refer to the Items feed reference for more information.

Testing

You can test a feed operation before it is actually executed by specifying the dry-run flag. Once you are sure that you want to submit the data, remove the dry-run flag to execute the operation.

Troubleshooting

Disapproved items

Google Base monitors all items according to our Program Policies and Editorial Guidelines. Items that do not comply with these policies always remain drafts, which means that they will not match any queries. Such items are marked <gm:disapproved/>. Disapproved items have an <app:draft> flag that is always set to yes.

The <app:draft> flag can never be removed from a disapproved item. In order to resolve a disapproved item, delete it from Google Base, fix it so that it complies with the Google Base Program Policies and Editorial Guidelines, and resubmit it as a new item.

<entry>
...
	<app:control xmlns:app='http://purl.org/atom/app#'>
		<app:draft>yes</app:draft>
		<gm:disapproved/>   
	</app:control>
</entry>

Writing a Google Base data API application

There are two ways to write an application using the Google Base data APIs:

You can interact directly with the Google Base feeds. This is a language-independent method of accessing the Google Base functionality. We provide some basic tutorial examples that show how to do this using Java. Even if you choose to use a different language, you can refer to these examples to help you get started. We provide sample code in a host of other languages, as well.
You can use the Client Libraries. Currently, we offer client libraries in Java and C#. You can download both from the Download page. We provide a Java Developer's Guide and a C# Developer's Guide to help you get started, as well as some sample applications in both Java and C# that use the client library.


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

Google Base Data API

Getting Started

Developer's Guide

Reference Guide

Related Links

Getting Started

Contents

Audience

Google Base terminology

Data items

Attributes

Item types

Google Base data API services

Searching for data items

Data available in Google Base

Executing queries

Data feeds

Discovering metadata

Meta-data feeds

Item types

Attributes

Attribute limitations

Metadata namespace

Inserting, updating, and deleting data items

Data namespaces

Hiding Attributes

Hiding items

Inserting reference attributes

Using images

Using the image_link Attribute in the Items feed

Using the Media Feed

Posting an attachment

Post an attachment with metadata

Post an attachment without metadata

Updating an attachment

Updating the title

Deleting an attachment

Querying for information about an item's attachments

Retrieving thumbnails

Specifying shipping rules

Inserting attributes with non-geocodable locations

Accessing Google Base

Authenticating the user

Authenticating the developer

Managing multiple clients

Testing

Troubleshooting

Disapproved items

Writing a Google Base data API application