Google Blogoscoped

Sunday, June 22, 2003

Google Web API Tutorial

If you always wanted to give the Google Web API a try, but never did, I'd like to give you a small step-by-step tutorial.

What is the Google Web API?

The API* exposes the Google engine to developers. This means you can write scripts that access the Google search in real-time. For example, you could query all pages containing "hello", and output the page-count. Or anything else imaginable.


You have a default limit of 1,000 queries per day, you cannot get over the 1,000th result, you can only query for 10 results a time, and you can only access Google Web Search (not Google Images, Google Groups, and so on).

* Depending on the source, the abbreviation "API" stands for Application Programming Interface, Application Programmer's Interface, Application Programmer Interface, Application Program Interface, or Application Programmatic Interface. In short, it's a wrapper around a program that helps developer's to easily access its inner functionality. The Google Web API is also called "Google Web Services".

Do I have what it takes?

What you need is a server that allows you to execute server-side scripts. If you got, you should check your contract and wether or not you can do that; email your host support if in doubt. Ask them if they have CGI, scripting like PHP, Pyth├┤n, Java, ASP, or the like.

Second, you need to know the programming basics. But using the Google Web API is not very complicated, as there are several wrapping tools to get you started.

For this small tutorial, I will give examples of a PHP implementation. You can use other languages as well (like Perl). You should be familiar with HTML as well. PHP is a language, besides other things, to dynamically create HTML pages.

The Google API (currently in Beta) is further based on the Web Services technology SOAP (the XML-based Simple Object Access Protocol). But you don't need to details of SOAP to use the API, really.

Downloading the API, and registering for a key.

Create your own folder on your computer and put all the needed files in it; first, you should download the toolset of the Google Web API (note that you don't need it for this sample), and get your developer key (which you do need for the sample):

Second, get the helpful file called "NUSOAP" by Dietrich Ayala. It's free and helps you to implement a Google Web API script in PHP. (Note that I put NUSOAP on my server because I made a small but important change to the file which was necessary to get the filter-parameter to work.)

Now that everything's unpacked and waiting in your folder, create your own test project by creating a sub-folder called "test". Put the "nusoap.php" file in the folder.
Next, use Notepad – or another text-editor, like my Netpadd – and write the following testing PHP script as "index.php" and upload it to your server via FTP (you can use Absolute FTP for that; it's free to test for 30 days):

        Strict//EN" "DTD/xhtml1-strict.dtd"><html
        xmlns="" xml:lang="en"

<h1>Hello World</h1>

$Query = "Hello World"; // [3]
$key = "[Put your developer's key here]";
$start = 0;

$parameters = array( 
            "key"         => $key,
            "q"           => $Query,
            "start"       => $start,
            "maxResults"  => 10,
            "filter"      => true,
            "restrict"    => "",
            "safeSearch"  => false,
            "lr"          => "lang_en", 
            "ie"          => "",
            "oe"          => ""

$soapclient = new soapclient(""); // [1]
$result = $soapclient->call("doGoogleSearch", $parameters, "urn:GoogleSearch");
$searchtime = $result["searchTime"];
$begin = $start + 1;
$end = $start + $parameters["maxResults"];
$total = $result["estimatedTotalResultsCount"]; 

if ($total > 0)
    $result = $result["resultElements"]; 

    for ($i = 0; $i < $parameters["maxResults"]; $i++)
        $element = $result[$i];
        $url = $element["URL"];
        $title = $element["title"];
        $snippet = $element["snippet"]; // [2]
        ?><p><?= $snippet ?></p><?



The above is a mix of HTML and PHP, separated by the "<?" and "?>" strings. What it does is instantiate a Google Web API search object called "soapclient" (see highlight [1]), and output all the snippets of the search result (see highlight [2]). Note that for this to work you must insert your own developer's key!

If you uploaded the file and entered the URL in a web-browser (like ""), you should see several paragraphs with Google snippets. Those are grabbed dynamically and will be different if you change the query "Hello World" (highlight [3]) in above PHP script.

Also, you can see above script in action, or download the complete project source for your own use.

What to do next?

Now that you got the basics to work, I suggest to play around with the script and be creative with it. Try out new things, like outputting the title, URL, and search-time as well. If you got a website indexed by Google, you can also build your own search engine that looks exactly like you want. You can also look at some of the tools at this site for inspiration (see navigation, like Egobot chat), or buy the Google Hacks book and read through many more samples.

Questions about the Google Web API?

If you have any further questions not covered in the Google Web API FAQ, or something doesn't work, just write to the Google support, or me. Also, check out the Google Web API newsgroups.


Blog  |  Forum     more >> Archive | Feed | Google's blogs | About


This site unofficially covers Google™ and more with some rights reserved. Join our forum!