Lab 09 -- The Google API

Summary

This article covers performing search queries on Google using their API. This means you can transparently run a Google search in the background, and then present the results to your users however you want to. The Google API is a SOAP web service. SOAP (Simple Object Access Protocol) is an XML schema used for calling a remote procedures (usually) over the web. In this case, the remote procedure is Google search.

The instructions on this page will show you how to:

Download and install the latest version of NuSOAP class.
Create a search PHP script that sends a text query to the Google API.
Display the results to your users.
Create a Google-search front end to get the query string from your users.

Note: You must Have your Google developer's key before starting this lab.

In this article, we are going to create a single PHP script called google.php, to simply demonstrate how to query Google. Hopefully using this information, you will be able to come up with more advanced ways of using the API. The Google API does offer querying of their cache, as well as spelling requests, however, this article covers only performing searches. If you’re interested in these other types of queries, you’re best of reading the API reference guide.

Download and install the NuSOAP classes

Download the latest version of the NuSOAP from SourceForge and save the NuSOAP zip file in your public_html folder on Dante.
lynx -dump http://switch.dl.sourceforge.net/sourceforge/nusoap/nusoap -0.7.0.zip > nusoap.zip
Unzip the file to expand the contents.
unzip -d nusoap nusoap.zip
Make sure that you have executable permissions for the nusoap classes:
chmod -R +x nusoap

Create a php script to search the Google API

There are a few things you should be aware of before using the Google API, mainly to do with terms and restrictions on the service:

Google’s terms of service say it is for “personal, non-commercial use only”
There is a limit of 1,000 queries per day using your license key
You can only fetch 10 results at a time, and you can’t get results past the 1,000th result.
A single query can have 10 terms at most

There’s not much you can do about the first of these restrictions, although this is not specifically clear. For example, this web site is non-commerical – does that mean it could be used on here?

The second limitation (1,000 queries per day) can be overcome by using caching. So whenever you perform a query, save the results to a file, then when somebody performs the same request you can just fetch the results from your hard disk instead of querying Google again. Implementation of this is not covered in this lab, but if you’re interested, PEAR’s Cache_Lite might be a good starting point.

Okay, so the first thing we do is create the parameters. The parameters for NuSOAP are held in associative array, which means the array key is the parameter name, and the corresponding array value is that parameter’s value.

The minimal set of parameters we need are:

key – The Google license key you created
q – The term you want to search form
Other parameters you can specify include:
start – The first result you want to fetch, starting from 0. For example if you wanted to fetch from the very first result, this value would be 0. If you wanted to fetch the second page of results (at 10 per page), this value would be 10 (because you want results 10-19, so the third page would be 20-29).
maxResults – This is the maximum number of results you want to fetch, from 1 to 10.

There are several more you can specify, but this is enough for our purposes. For a full list, see the Google API reference page.

Create a new file called google.php using pico or your favorite php editor.

Add the search parameters to the php script

<?php
    $key = 'YOUR_GOOGLE_KEY_HERE';
    $q = 'SOME QUERY';
    $parameters = array('key'        => $key,
                        'q'          => $q,
                        'start'      => 0,
                        'maxResults' => 10);
?>

Now that we have our parameters, we can call the SOAP web service. To do this we are using the NuSOAP library.
```
<?php
    require_once('./PATH_TO/nusoap.php');

    $soap = new SoapClient('http://api.google.com/GoogleSearch.wsdl', 'wsdl');
    $result = $soap->call('doGoogleSearch', $parameters);
?>
```
Now to explain this:
- The URL of the Google web service is at http://api.google.com/GoogleSearch.wsdl
- WSDL stands for Web Service Description Language. The WSDL provides a description of how the service works, what procedures it has available, and the parameters required for calling those procedurs. If you visit that URL in your browser, you will a see an XML file description everything about the web service.
- The procedure we’re calling is called ‘doGoogleSearch’
So once you run the call() function of NuSOAP, the actual request is performed, meaning that Google is now queried for that search term.
The last thing to do is handle the results. The returned data contains an array called ‘resultElements’, which contain the returned results. So if this array is empty, there were no results. To output them, we simply loop over this array and output each one.

Each result element contains the following data:
- URL—the URL of the web site
- title—the title of the web site
- snippet—a brief summary of the web site content
There are other fields it contains, that we don’t need right now.

Additionally, the returned data contains the following:
- searchQuery—the search that was performed
- estimatedTotalResultsCount—the number of results (approximately) the search yielded
- startIndex—the position in the search of the first returned result (e.g. if we were fetching page 2)
- endIndex—the position in the search of the last returned result
- searchTime—the time in seconds it took Google to perform the search

Now, using all this data we can output the search results:

Add the following code to your php script:

<?php
    $numResults = count($result['resultElements']);
    if ($numResults == 0) { 
?>

    <p>
        Your search yielded no results.
    </p>

<?php } else { ?>
    <p>
        Results <?= $result['startIndex'] ?> to <?= $result['endIndex'] ?>
        of <?= $result['estimatedTotalResultsCount'] ?>
    </p>

    <?php foreach ($result['resultElements'] as $row) { ?>
        <h3><a href="<?= $row['URL'] ?>"><?= $row['title'] ?></a></h3>
        <p>
            <?= $row['snippet'] ?>
        </p>
        <p>
            <?= $row['URL'] ?>
        </p>
    <?php } ?>
<?php } ?>

Be sure to run your script at this point to make sure that the search works!

Now we'll combine this with a simple search form to create a Google-front end

We’re going to combine and adapt the code created in previous steps to build our own Google front end. The main changes we will make to our code here involve retrieving the search term from the form, as well as providing the option for returning pages other than just the first.

Remember that this is very basic and there is a lot of further customization you can do.

You can put all this new code in the file google.php

Get the search term from the user

//$q = 'SOME_QUERY';
$q = trim(isset($_GET['query']) ? $_GET['query'] : '');

Check the string length before executing the query, don't send empty queries to Google

if (strlen($q) > 0 ) {
  $parameters = array('key'             => $key,
                      'q'               => $q,
                      'start'           => $limit,
                      'maxResults'      => $maxResults);
  // Use the NuSOAP library
  require_once('./nusoap-0/lib/nusoap.php');

  $soap = new SoapClient($wsdl, 'wsdl');
  $result = $soap->call('doGoogleSearch', $parameters);
}

Add a simple search form to the page

<form method="get">
  <input type="text" name='query' value="<?= htmlSpecialChars($q) ?>" />
  <input type="submit" value="Submit" />
  <input type="reset" value="Reset" />
</form>

Again, check the string length before trying to print the results