Important: This is an old version of this page. For the latest version, use the links in the left-side navbar.
Google provides an extension to the Google Data .NET Client Library that helps connect to the Google Base feeds and interprets the result. For help setting up the client library, see the Client Library Getting Started Guide.
This client library is by no means the only way of connecting to the Google Base API server in C#. You can achieve the same result using an XML parser.
This document assumes that you know C# programming, and that you are familiar with the basic concepts of Google Base.
Before you start, please make sure you have read and understood the Google Data .NET Client Library documentation.
The Google Base client library extends the Google Data client library and adds some Google Base-specific objects to make it easier to use. It tries to stick to the XML representation.
Each XML element
in a feed or entry corresponds to one C# Object in the library.
For example, an <atom:feed> element corresponds to a GBaseFeed element,
and an <atom:entry> element corresponds to a GBaseEntry.
Google Base extends the Google Data feeds with elements from the g namespace
(http://base.google.com/ns-metadata/1.0)
and elements from the gm namespace (http://base.google.com/ns/1.0).
Elements in the g: namespace in an entry correspond to an instance of the class GBaseAttributes. Elements in the gm: namespace
in an entry correspond to an instance of the classes ItemTypeDefinition or AttributeHistogram, depending on the current feed.
For help setting up the client library, see the Client Library Getting Started Guide. You'll find the classes you need to use the Google Base client library
in the distribution in the cs/lib/Release/gbase.dll and cs/lib/Release/gdata.dll assemblies.
You can import the classes you will need using the following statements:
using Google.GData.Client; using Google.GData.GoogleBase;
The full source code of an example that does exactly what is described in
this section is available in the distribution in the file cs/samples/gbase/queryexample.cs. You can find documentation for this example in the Sample Applications section.
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.
To do this programatically, you need to create a GBaseService object and then run a query on it. This is done as follows:
|
GBaseService service = new GBaseService("Google-Tutorial-1.0", developerKey);
GBaseQuery query = new GBaseQuery(GBaseUriFactory.Default.SnippetsFeedUri);
query.GoogleBaseQuery = "digital camera";
GBaseFeed feed = service.Query(query);
GBaseQuery takes the URL of the feed you want to access and adds
parameters or categories as explained in the Google
data documentation. Each parameter supported by the Snippets feed corresponds to a property in the GBaseQuery object.
In the sample code above, the GoogleBaseQuery property corresponds
to the bq parameter.
service.Query() connects to the URL generated by GBaseQuery,
gets the result, parses it and returns a GBaseFeed. The GBaseFeed contains a list of GBaseEntry objects, one for
each Google Base item returned by the server.
foreach (GBaseEntry entry in feed.Entries)
{
System.Console.WriteLine(entry.GBaseAttributes.ItemType +
": " + entry.Title.Text +
" - " + entry.Id.Uri);
}
The code snippet above displays the following information for each entry:
<g:item_type
type="text">) <atom:title>) <atom:id>)Since <g:item_type> is in the g: namespace, you
first need to get the GBaseAttributes object of the entry
using entry.GBaseAttributes. Then you get the attribute
value using the property ItemType.
ItemType is a shortcut that corresponds to GetTextAttribute("item
type"). GetTextAttribute() gets the first attribute
in the entry that is called 'item type' and whose type is 'text'. The
second line in the example above could be rewritten as follows using GetTextAttribute():
System.Console.WriteLine(entry.GBaseAttributes.GetTextAttribute("item type") +
In the client library, an attribute is always identified by
both its type and its name, as reflected by the class GoogleBaseAttributeId.
Make sure you always specify the type when setting an attribute, as it
will have an impact on which queries can be run on your items. For more
details on constructing queries, see Attributes
and Queries and also the Query Language
Specification.
When getting attribute values, both the attribute name and its type are
important. If an item contains the attribute <g:bathrooms type="float"> and
you call the method getTextAttribute("bathrooms") ,
you would not get any answer, because the attribute bathrooms is
of type float . If instead you call getFloatAttribute("bathrooms") ,
you will get the value of the bathrooms attribute.
If, on the other hand, you set the number of bathrooms in your "house" item
using setTextAttribute("bathrooms") the attribute
appear on the XML output, if users run this query: " [bathrooms > 2]" they
will never get your item as an answer. Make sure you choose the correct
type for your attributes to get the maximum benefit from the Google Base Data API.
In some cases, when it is unclear whether an attribute should be an int or
a float, you can avoid the dilemma by using the type number .
If you call getNumberAttribute("bathrooms") you
get both attributes defined as int and attributes defined
as float.
Similarly, getDateTimeRangeAttribute() returns date , dateTime and dateTimeRange attributes.
You can access the itemtypes feed using the client library as follows:
GBaseService service = new GBaseService(
"Google-Tutorial-1.0", developerKey);
GBaseFeed feed = service.Query(new GBaseQuery(
GBaseUriFactory.Default.GetItemTypesFeedUri("en_US")));
Each GBaseEntry in this feed describes one item type, using entry elements in the gm: namespace. To access these elements, get the property GBaseEntry.ItemTypeDefinition to access the subset of the gm: namespace which describes item types.
foreach (GBaseEntry entry in feed.Entries)
{
ItemTypeDefinition itemType = entry.ItemTypeDefinition;
System.Console.WriteLine("Google proposed item type: " + itemType.Name);
System.Console.WriteLine("Google proposed attributes: ");
foreach(AttributeId attribute in itemType.Attributes)
{
System.Console.WriteLine(attribute);
}
}
Here's how you could use the client library to find out the 10 most commonly-used attributes for a recipe and for these, the 5 most common values (for text attributes).
GBaseService service = new GBaseService(
"Google-Tutorial-1.0", developerKey);
GBaseQuery query = new GBaseQuery(GBaseUriFactory.Default.AttributesFeedUri);
query.GoogleBaseQuery = " [item type: recipes]";
query.NumberToRetrieve = 10;
query.MaxValues = 5;
GBaseFeed feed = service.Query(query);
Each GBaseEntry in the feed describes an attribute, from the most common to the least common. This time, the subset of gm: attributes can be accessed using AttributeHistogram.
foreach (GBaseEntry entry in feed.getEntries())
{
AttributeHistogram attribute = entry.AttributeHistogram;
System.Console.WriteLine("attribute: " + attribute.Name);
foreach(HistogramValue value in attribute.Values)
{
System.Console.WriteLine(" '" + value.Content + "'");
}
}
This section explains how to insert items into Google Base using the client library. 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. Specify your Google Base account name and password to GBaseService as follows:
GBaseService service =
new GBaseService("Google-Tutorial-1.0", developerKey);
service.setUserCredentials(username, password)
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 a server, such as a web application. For more information about authentication, see the Google Account Authentication documentation.
The next step is to create the GBaseEntry you would like to insert.
GBaseEntry entry = new GBaseEntry();
entry.Title.Text = "My House";
entry.Content.Content = "The best house of the area.";
entry.GBaseAttributes.ItemType = "test";
entry.GBaseAttributes.AddTextAttribute("my attribute", "hello");
entry.GBaseAttributes.AddFloatAttribute("bathrooms", 2f);
entry.GBaseAttributes.AddFloatAttribute("rooms", 6.5f);
entry.GBaseAttributes.AddFloatAttribute("bedrooms", 2f);
entry.GBaseAttributes.Location = "1900 Snow Cone Avenue, North Pole";
Finally, insert this GBaseEntry object into the Items feed.
GBaseEntry myEntry = service.Insert(
GBaseUriFactory.Default.ItemsFeedUri, entry);
The method service.Insert returns the item you just inserted as
you will find it in later in Google Base.
The Google Base server assigns precomputed attributes for your entry, such as the creation date and time, the author and, probably most importantly, the identifier (or URL) of the new entry.
You can also get this information by running a query on the Items feed.
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. You can access this feed using the client library as follows:
GBaseService service = new GBaseService(
"Google-Tutorial-1.0", developerKey);
service.setUserCredentials(username, password);
GBaseFeed feed = service.Query(new GBaseQuery(
GBaseUriFactory.Default.GetItemTypesFeedUri("en_US")));
Each GBaseEntry in this feed will describe one item type, using
entry elements in the gm: namespace. To access these elements, get the value of the property GBaseEntry.ItemTypeDefinition,
to access the subset of the gm: namespace
that describes item types.
foreach (GBaseEntry entry in feed.Entries)
{
ItemTypeDefinition itemType = entry.ItemTypeDefinition;
System.Console.WriteLine("Google proposed item type: " + itemType.ItemType);
System.Console.WriteLine("Google proposed attributes: ");
foreach(AttributeId attribute in itemType.Attributes)
{
System.Console.WriteLine(attribute);
}
}
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.
The Attributes feed might answer these kinds of questions. Here's how you could find out the 10 most commonly-used attributes for a recipe and, for these, the 5 most common values (for text attributes).
GBaseService service =
new GBaseService("Google-Tutorial-1.0", developerKey);
GBaseQuery query = new GBaseQuery(
GBaseUriFactory.Default.AttributesFeedUri);
query.GoogleBaseQuery = " [item type: recipes]";
query.NumberToRetrieve = 10;
query.MaxValues = 5;
GBaseFeed feed = service.Query(query);
Each GBaseEntry in the feed describes an attribute, from the
most common to the least common. This time, the subset of gm: attributes
that interests us can be accessed using the property AttributeHistogram
foreach (GBaseEntry entry in feed.Entries)
{
AttributeHistogram attribute = entry.AttributeHistogram;
System.Console.WriteLine("attribute: " + attribute.Name);
foreach(HistogramValue value in attribute.Values)
{
System.Console.WriteLine(" '" + value.Content + "'");
}
}
In the Google Base client library, an attribute is always identified by both its
type and its name, as reflected by the class AttributeId.
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
using AddTextAttribute("bathrooms") the attribute will
appear on the XML output. However, if users run the query: [bathrooms > 2] they
will never get your item as an answer.
Make sure you choose the correct type for your attributes to get the maximum benefit from Google Base.
To modify an item you have inserted, get it
back from the server, change it, then call update on it. myEntryId should be the Uri of the entry as returned by GBaseService.Insert (GBaseService.Insert(entry).Id.Uri)
GBaseService service =
new GBaseService("Google-Tutorial-1.0", developerKey);
service.setUserCredentials(username, password);
GBaseEntry entry = service.GetEntry(myEntryId);
entry.GBaseAttributes.AddFloatAttribute("rooms", 7f);
service.Update(entry);
You might avoid reading the entry from the server if you know exactly
what your entry should look like. This is dangerous, as updating will
replace everything with the entry you specify to update. If you
forget to set an attribute that is already in the entry, it will be
removed when it is updated.
myEntry should be the entry object that was returned when you created the entry or
you might have found it by running a query on the Items
feed.
To delete an item, all you need is its ID, expressed as a URL:
GBaseService service =
new GBaseService("Google-Tutorial-1.0", developerKey);
service.setUserCredentials(username, password);
service.Delete(myEntry);
The examples above do not contain any error-handling code to keep things simple.
The GBaseService methods throw GDataRequestException, which can have different meaning depending on
the concrete subclass that has been thrown, such as ClientQueryException or ClientFeedException.
If you receive a GDataRequestException, make sure you get the error message
using Response.GetResponseStream() . This error message contains the text
sent by the server and is usually an XML message. Check the type of this
message using Response.ContentType. If it is indeed an XML
message, you can parse it to get the real error message.
For reference information, see the Google Data client library ndoc reference.