English | Site Directory

Google Base Data API

Frequently Asked Questions

Main Google Data API FAQ

The questions below are specifically targeted for the Google Base Data API. There are, however, many questions that are applicable to all of the Google Data APIs. Visit the Google Data APIs FAQ if you do not find the question you are looking for below.

Getting Started

What Client libraries are available for the Base API?
 
 How do I install and use the .NET Client Library?
 
 Where can I find the Developer Guide?
 
 What is the Google Base data API?
 
 Who should use the Google Base data API?
 
 Can I restrict access to my items?
 
 How do I view my items?
 
 What are my options for adding items via the Google Base data API?
 
 Do I need a Google Base account to use the API?
 
 How can I sort my results?
 
 Does the Google Base data API support incremental changes?
 
 How do I query using the Google Base data API?
 
 Does Base support location based queries?
 
 How do I list an item in a specific country?
 
 Do you have any tips or short sample code for common issues?
 

Authentication

How do I authenticate with the service?
 
 I'm getting the error "AuthSub token has wrong scope." What can I do to resolve this issue?
 
 What is the ClientLogin service name for the Base Data API?
 

Best Practices

Why are my items not showing up immediately in the snippets/items feed?
 
 Can I use the API with a multi-client account?
 
 How do I set up a multi-client account?
 
 What are the limits for API usage?
 
 How can I validate my XML?
 
 What values can I set for price type?
 
 How do I send users to my site when they click on an item in Google Base?
 
 Are private attributes indexed?
 
 Are custom attributes indexed?
 
 What is the size limit for a batch request?
 
 How do I upload images in the API?
 
 Do items with a custom item types ever expire?
 
 Can I prevent my items from being searchable through the API?
 
 Can I hide an item?
 
 What is the size limit for a batch request?
 

Getting Started

What Client libraries are available for the Base API?
Currently, the API has support in the Java, PHP, .NET, and Python client libraries. For more information on the libraries, see the Client Libraries section.
How do I install and use the .NET Client Library?
You can find more information in the article on Getting Started with the .NET Client Library
Where can I find the Developer Guide?
The Developer Guide can be found at http://code.google.com/apis/base/protodevguide.html.
What is the Google Base data API?
The Google Base data API is an extension of the Google Data API protocol, which you can use to create programs that interact with the Google Base servers. The API allows you to query for items and insert, update, and delete items in Google Base.

The Google Base data API is designed for developers who would like to integrate their applications with Google Base. Due to the nature of the Google Base data API, developers should have some technical know-how and experience in programming applications. To get started, visit the Getting Started Guide.
Who should use the Google Base data API?
The API is designed to help anyone interested in finding items in Google Base or adding items to it. You are free to leverage the data in the API to create interesting applications and mashups and to publish new items for others to find and use. Here are some projects which are querying Google Base through the API:

http://findaconvertiblecar.com/
http://www.jobcentral.com/

If you're a casual user of Google Base and would like to add a few items at a time, we suggest you do this using the existing submission methods: single-item postings and bulk uploads. To get started, go to http://base.google.com/.

If you need to develop a more sophisticated application, you might want to consider the Google Base data API. This method will allow you to programmatically manage items in Google Base. Developers should be familiar with the HTTP protocol.
Can I restrict access to my items?
No. Items posted to Google Base will be publicly viewable in the /feeds/snippets feed and can be queried by anyone. However, you are the only person who can see or edit your items in the /feeds/items feed.
How do I view my items?
You can see your items in your Google Base dashboard or by using the /items/feed feed (without a bq parameter). Within 24 hours, your items will be searchable at http://base.google.com and via the /feeds/snippets feed.
What are my options for adding items via the Google Base data API?
You can manage your items in Google Base by using HTTP POST, PUT, DELETE and GET requests. You can implement the API with any programming language, and we provide client libraries for your convenience.
Do I need a Google Base account to use the API?

To query Google Base using the API, no—all you need is a developer key. You can can request a key here.

To insert, update, delete, or query your own items in the items feed, you'll need to authenticate using a Google Base account. You can authenticate using an AuthSub (authentication for web applications)token or the username and password for a Google Base account. You can register for a Google Base account at http://base.google.com/base/welcome.

How can I sort my results?

By default, results returned by the Google Base data API are sorted according to relevancy. You can change the order by using the orderby parameter. Possible values for this parameter can be found here:

http://code.google.com/apis/base/snippets-feed.html#Parameters
Does the Google Base data API support incremental changes?
Yes. With the Google Base data API, you have the ability to make incremental changes to your items. To do this, submit an updated version of your item with all of the modified attributes and values you would like to include.
How do I query using the Google Base data API?

Queries are made to the Google Base data API using the HTTP GET method. You can query against the public feed by adding search parameters that conform to the query language specifications found here:


http://code.google.com/apis/base/query-lang-spec.html

A successful query returns data as an Atom feed. As with all Google Base data API operations, you must provide a developer key in the query.

Does Base support location based queries?
Yes. You can include location as one of the attributes in your query. You can even search for items within a radius of a location using the "+ radius" format. For example: [location: @"1600 Amphitheatre Parkway, Mountain View, CA, USA" + 100mi]. To include the item's actual latitude/longitude in query results, use the content=geocodes parameter: http://www.google.com/base/feeds/snippets?bq=[location]&content=geocodes

See more examples at http://code.google.com/apis/base/attrs-queries.html#LocDatQuer
How do I list an item in a specific country?

You can specify the country and language of an item by setting the target country and target language attributes. For example,to list an item only in the UK, make sure that the following attribute is set in your item:

<g:target_country>GB</g:target_country>

If you want to list your item in Germany, you would set the target country and target language as follows:

<g:target_country>DE</g:target_country>
<g:item_language>DE</g:item_language>

When you POST your item, it should be sent to base.google.com/base/feeds/items.

Do you have any tips or short sample code for common issues?
You should browse the Google Data API Tips Blog for help with both our client libraries and making raw requests.

Authentication

How do I authenticate with the service?
Your HTTP request must include an Authorization header. The token you provide in this header must be obtained by using either programmatic login (ClientLogin) or AuthSub login.
I'm getting the error "AuthSub token has wrong scope." What can I do to resolve this issue?
You are receiving this error because you are using an unsupported root URL in your application. The correct scope is http://www.google.com/base/.
What is the ClientLogin service name for the Base Data API?
The service name for ClientLogin is gbase.

For more Authentication FAQs, see the Google Data APIs FAQ

Best Practices

Why are my items not showing up immediately in the snippets/items feed?
When writing an item to Google Base (i.e., inserting or updating an item), you can specify its publishing priority. In this way, you control how soon the item will be searchable. By default, this value is low. For your items to be searchable within minutes after publishing, set this value to high: 
<entry xmlns:app='http://purl.org/atom/app#'
       xmlns:gm='http://base.google.com/ns-metadata/1.0'>
   ...
   <app:control>
      <gm:publishing_priority>high</gm:publishing_priority>
   </app:control>
</entry>
Can I use the API with a multi-client account?
Yes, if you use a multi-client account to submit items for multiple sites, you can still use the Google Base data API.

Learn more about submitting content via the API.
How do I set up a multi-client account?
Please familiarize yourself with the limitations of multi-client accounts before you request one. If you're sure you'd like us to set up a multi-client account for you, please contact us and include the following information for each client you'd like to manage:
  1. Client's display name.
  2. A unique filename. Please don't duplicate filenames. If you plan to submit an XML data feed, please ensure that your filename includes the .xml extension (e.g., base_site1.xml).
  3. Item type. This refers to the type of information you'll be submitting for each client (e.g., Products, Housing, Reviews, etc.).
  4. Client's homepage. This refers to the homepage of the client (if applicable). Please ensure that each URL begins with http://.

Important: Please make sure you've set up a Google Account before contacting us for a multi-client account. You can create a Google Account by clicking Create an account now on the lower right-hand side of the Google Base sign-in page.

What are the limits for API usage?
The Google Base data API supports up to approximately 5 queries per second, per user.
How can I validate my XML?
You can validate the XML you use to submit your items via the API by setting the dry-run flag in your insert, update, or delete request. Specify that an operation is a "dry run" by adding dry-run=true as a URL parameter (/base/feeds/items?dry-run=true). No changes will be made to your items when dry-run is set.
What values can I set for price type?
The price type attribute can be set to either "starting" or "negotiable". If a price type is not specified, the default value of "fixed price" is used.
How do I send users to my site when they click on an item in Google Base?
To point the item to your external page, add the following tag to your item:

<link rel='alternate' type='text/html' href='http://ENTER-YOUR-URL'/>
Are private attributes indexed?
No, private attributes are not indexed. The item's creator can view and edit them via the items feed, but the public cannot query them.

Here is how to set an attribute as private:
<g:private_id type="text" access="private">this is not visible by others</g:private_id>
Are custom attributes indexed?
It depends. If the attribute is both human-readable and is not set to be hidden, it will be indexed. Hidden attributes have an access attribute which is set to private (access="private"). If your custom attribute is non-human-readable (i.e. a custom id like <g:customId>12345XASFO3YCHKA73KJHS</g:customId>), it may not be indexed.
What is the size limit for a batch request?
Your batch request can be up to 1 MB (1,048,576 bytes) in length.
How do I upload images in the API?
You cannot send the image data through the API, but you can include the image URL in your item's XML when you send it. The Google Base system will check your image and include the image URL in your item.
Do items with a custom item types ever expire?
There is no default expiration date for items with a custom item type, so these items will never expire unless you set the expiration date manually when you create or update the item.
Can I prevent my items from being searchable through the API?
If you prefer not to have some of your data syndicated via the Google Base API, please include an attribute titled no_api_syndication in your data feed. Then, for each item you don't want syndicated, set the no_api_syndication attribte to <g:no_api_syndication>true<g:no_api_syndication>.
Can I hide an item?
Yes you can, by using standard atom app:draft element. Set the draft's text to "yes" as follows: 
  <app:control xmlns:app='http://purl.org/atom/app#'>
    <app:draft>yes</app:draft>
  </app:control>

Note that hidden items are not indexed, so you will not be able to search for them in your items feed.

What is the size limit for a batch request?
Your batch request can be up to 1 MB (1,048,576 bytes) in length.