Overview
========

This README describes the client Google Web APIs distribution. This
package is all you need to use Google's SOAP-based API. Inside you'll
find a WSDL file which formally describes the API. It can be used with
any language with web services support to call Google. We also provide
a custom Java library that provides a convenience wrapper for Java
programmers. Finally, we have an example .NET program that calls the
Google Web APIs. For more details, see below.

The Google Web APIs service is in beta release. All interfaces are
subject to change as we refine and extend our APIs. Please see the
terms of use (in the file "LICENSE.txt") for more information.

For questions, comments, etc, please mail Google at
  <api-support@google.com>
You can also discuss Google Web APIs using the Google Group
google.public.web-apis available at
  http://groups.google.com/groups?hl=en&group=google.public.web-apis


Registration and key
--------------------

In order to use Google Web APIs you first must register with Google to
receive an authentication key. You can do this online at
http://www.google.com/apis/.

Your key will have a limit on the number of requests a day that you
can make. The default limit is 1000 queries per day. If you have
problems with your key or getting the correct the daily quota of
queries, plase contact <api-support@google.com>.


How to use the Java API
-----------------------

To quickly try the API, run
  java -cp googleapi.jar com.google.soap.search.GoogleAPIDemo <key> search Foo
Where <key> is your registration key and Foo is the item you wish to
search for. GoogleAPIDemo is a simple demonstration of how to use the
Java API included in googleapi.jar. For usage, run it with no arguments: 
  java -cp googleapi.jar com.google.soap.search.GoogleAPIDemo

GoogleAPIDemo is only a demonstration; Java programmers should look at
the source for GoogleAPIDemo and the included Javadoc for the
GoogleSearch class to learn more about how to use our Java library.

The library has our SOAP endpoint address built in. You may want to
override this endpoint, for instance to point it at a debugging proxy.
You can do this either by calling the appropriate method in
GoogleSearch or by setting the Java property "google.soapEndpointURL".
The default URL is http://api.google.com/search/beta2


How to use the .NET Example
---------------------------

We have provided a simple example program that calls the Google Web
APIs service from .NET. In the dotnet directory you will find files
for this example, including

  Google Web APIs Demo.exe
    Compiled binary, requires .NET Framework installed on your machine
  GoogleSearchService.cs
    Proxy to the Google Web APIs, automatically generated by wsdl.exe
  Form1.cs
    Simple GUI program that calls the API
  Google Web APIs Demo.csproj
    Project file for the API demo; open in Visual Studio .NET

To browse the code, simply look at the end of Form1.cs for the methods
at the end named searchButton_Click, cacheButton_Click, and
spellButton_Click. To see the code in Visual Studio .NET, open the
project, right click on "Form1.cs" in the Solution Explorer, and
select "View Code".


How to use the WSDL File
------------------------

The WSDL file provides a standard description of Google's search
services. Many programming languages now understand WSDL and can use
this file to automatically invoke Google's API. For example, the WSDL
can be imported into .NET, converted into Java code using Apache Axis
WSDL2Java, or used directly by Perl SOAP::Lite.

The WSDL file has been tested with SOAP::Lite 0.52, the .NET Framework
wsdl.exe version 1.0.3705.0, and Apache Axis Beta 1.

Below is a simple Perl script to use the WSDL file to do a query:

use SOAP::Lite;
my $key='000000000000000000000000';
my $query="foo";
my $googleSearch = SOAP::Lite -> service("file:GoogleSearch.wsdl");
my $result = $googleSearch -> doGoogleSearch($key, $query, 0, 10, "false", "", "false", "", "latin1", "latin1");
print "About $result->{'estimatedTotalResultsCount'} results.\n";



Contents of this package:
=========================

googleapi.jar
  Java library for accessing the Google Web APIs service.
GoogleAPIDemo.java
  Example program that uses googleapi.jar.
dotnet/
  Example .NET program that uses Google Web APIs.

LICENSE
  Terms of use for the API.
APIs_Reference.html
  Reference doc for the API. Describes semantics of all calls and fields.
javadoc/
  Documentation for the example Java libraries.
licenses/
  Licenses for Java code that is redistributed in this package.

GoogleSearch.wsdl
  WSDL description for Google SOAP API.
soap-samples/
  Example SOAP messages and responses.


googleapi.jar contents
======================

com.google.soap.search.*;
  Google's own Java wrapper for the API SOAP calls
JAF 1.0.1 (activation.jar)
  http://java.sun.com/products/javabeans/glasgow/jaf.html
Javamail API (mailapi.jar)
  http://java.sun.com/products/javamail/
Apache SOAP 2.2 (apache-soap-22.jar)
  http://xml.apache.org/soap/
Apache Crimson 1.1.3 (crimson.jar)
  http://xml.apache.org/crimson/

See the "licenses" subdirectory for licensing details of all third
party software. This product includes software developed by the Apache
Software Foundation (http://www.apache.org/).

Release notes
=============

2002-04-11:

  Public release of beta2 of the Google Web APIs service.
