By: Bernard Peh

April 12th, 2006

Reader Rating: 9

In 2002, Google implemented an API for its popular search engine to allow web developers to perform Google searches on their own web sites. Using SOAP (Simple Object Access Protocol), the API allows the search and results retrieval to run in the background. Many people also like to make use of the Google API in order to customise the way search results are displayed on their sites. However, one of the lesser-known benefits of being able to access the Google API is that you can use it to find your site's search ranking in Google, without having to visit the Google web site.

Developers and site owners are often interested in keeping up to date with how well their sites rank for certain keywords. The traditional way to do this is to type your search term into google.com (or your browser's Google search bar), then manually sift through the result pages that appear, looking for your URL. If your site is not optimized for the keyword that you searched for, your URL may be ranked quite low (for example, on the 50th page!). In situations like this, looking for your URL would be tedious, to say the least.

Fortunately, web services are available that automate this otherwise time-consuming process. However, many of these services place restrictions on the number of records you can query. For example, some web services will stop looking for your URL after the 200th record.

In this article, I'll introduce a script that enables you to utilize the Google API to find your site's ranking in Google. The script has a built-in feature that queries the Google server again if there is an error, and allows you to limit the number of results that are returned. I've packaged up this script so you can download the code we'll use in this article [1].

Note that at the time of writing, the Google API was still in beta. As a result, there might be some changes to the Google API in the future, though I don't imagine that they'd be too drastic.

For those of who aren't interested in delving through code, feel free to check out a little demo I made [2] to see what I'm on about (you'll need to sign up for a http://www.google.com/apis [3] Google API key, though).

Requirements

Google Key

Before you run the script, you'll require a Developer's Key from Google. If you don't have one, you'll need to sign up for a Google account at the Google API web page [4]. This key allows you to make up to 1000 queries per day; ten results will be returned each time.

After you've signed up for the account, download the API kit. In it you'll find a file called GoogleSearch.wsdl. Upload this file to your server.

PEAR SOAP

This package is one of several attempts to implement the SOAP (Simple Object Access Protocol) protocol for sending and receiving XML messages in PHP.

Many developers prefer NuSOAP (which is a lighter version of PEAR SOAP) or the SOAP extension that's built into PHP 5. I chose to use PEAR SOAP because it integrates more easily into my other PEAR applications. If you don't have experience with SOAP or web services, don't worry! You just need to make sure that your host has the PEAR SOAP package installed. If it doesn't, you'll need to install it manually (or ask your system administrator to do so) from http://pear.php.net/package/SOAP [5].

PHP Version 4 or Higher

The script is written in PHP, so your host must support PHP as well.

The Parameters

We need to set up the following parameters before we start to query the Google server. These variables can be set from within the script itself, or via a form. To appreciate what is going on here, go to the Google website and click on the "Advanced Search" link beside the search box. Some of the parameters that appear in the advanced settings are similar to those used in the Google API.

• key: This is your Google API developer's key. You did apply for a Google API account, didn't you?
• q: This is the term or phrase that you're using for the search.
• maxResults: This represents the number of results to be returned per query. Usually, you want this value to be 10, which is the maximum.
• start: The nth record from which to start querying. For example, if you want to display results 20 to 29 for a search, set the start variable to 20 and the maxResults variable to 10.
• filter: This is a boolean variable that indicates whether duplicate results should be included in the result listing. This should be set either to true or false. For example, if you don't want duplicates to be returned, set the filter to true. Your results will be filtered for duplicate content.
• restrict: You can restrict your results to certain categories such as US Government, Linux, Macintosh, and FreeBSD. Leave this empty if you wish to search the entire Web.
• safeSearch: If you want adult content to be filtered from the search results, set this to true.
• lr: This variable can be used to restrict your search results to a particular language. If you leave it empty, the results will default to English-only sites.
• oe: This can be used to control the Output Encoding of the results. Leave it empty if you want to use the default output of UTF-8.

The Dirty Work

The code uses a while loop to search for your specified URL, ten results at a time. If Google returns an error, the script will pause for 15 seconds, then resume querying. If the error is serious (such as hitting your 1000 query limit), the script will end. The while loop allows the script to keep running until either it finds your URL, or it reaches the maximum number of searched results (as specified by you). If you cannot find your URL in the first 1000 records, it's likely that your web site is still pending in the Google Sandbox, or has not yet been indexed by Google.

The code might look intimidating for beginners, but the logic is simple. With a little programming experience, you should be able to work through it easily by reading the comments.

while ($loop) {
// Instantiate the SOAP_WSDL Class.  
$wsdl = new SOAP_WSDL('GoogleSearch.wsdl');
// Get the WSDL Proxy Class  
$soapclient = $wsdl->getProxy();
// Start Google API query
$result = $soapclient->doGoogleSearch($key,$q,$start,$maxResults,
 $filter,$restrict,$safeSearch,$lr,$ie,$oe);
 // If error occurs
 if (PEAR::isError($result)) {
 $message = $result->message;
   echo "An error occured: $message<p>";
 // pause for 15 secs
   sleep(15);
 // if too many queries, quit loop
   if (preg_match("/Daily limit/i", $message)) {
     $loop = false;
   }
   // if invalid key, quit loop
else if (preg_match("/Invalid/i", $message)){
   $loop = false;
   }
   // if normal timeout message, continue
   else {
     echo "Retrying in 15 secs. <br/>";  
   }
 }
 // if no errors, check for the occurrence of your URL in the results.
else {
 $desc = "";
   // Step up the starting record for the next loop
$start += $maxResults;
 // the actual ranking
$position = $start- $maxResults;
   // Search for url
   urlSearch($position, $result);
 }
}
// display the final output
echo $output;

Searching Your URL from the Returned Google Results

From the previous code, the result class is passed to the urlSearch function. First, the function checks whether the start record is within the search limit you specified. After the search results are received, the foreach loop will try to match your URL with the results. If a match is found, the details of your web site will be displayed and the loop will end. If not, the while loop will continue ...

function urlSearch($position, &$result) {
global $loop;
global $output;
global $resultLimit;
global $maxResults;
global $desc;
global $q;
global $myUrl;
// Get total results from the search
$count =$result->estimatedTotalResultsCount;
 // Get the resultElements class
$elements = $result->resultElements;
 // if searched results reach limit set by you, quit loop
if ($position == $resultLimit) {
   echo "You have restricted the search results to $resultLimit";
 $loop = false;
 }
 else if ($count > 0) {
   echo "$position records<br/>";
   foreach ($elements as $item) {
     $position++;
   // if the URL is found, display it and quit loop
if (preg_match("/$myUrl/i", $item->URL)) {
       $size = $item->cachedSize;
 $title = $item->title;
       $url = $item->URL;
     $snippet = $item->snippet;
   $desc .= "<p>$title [Cache Size: $size]<br/> <a href=\"$url\" target=\"_blank\">$url</a><br />";
       $desc .= "$snippet</p>";
       $output = "<br /> $count results found. Your URL is ranked #{$position} for the keyword \"$q\". It will appear on page ".ceil($position/ $maxResults)." in the Google Search Engine. Your listing will appear as follows: <p>$desc</p>";
       // now exit the while loop
   $loop = false;
   }
   }
 }
 // if Google returns no result, quit loop
 else {
   $output = "No results found for the keyword \"$q\"";
   $loop = false;
 }
}

Adding the Form

We need a form to submit the parameters to the script in order to query the Google API server. This simple form should contain a few important fields:

• URL
• Google key
• keyword
• maximum search results

The HTML for the form is displayed below:

<form id="form1" name="form1" method="post" action="">
<p>Your URL:  
<input type="text" name="myUrl" />  
eg. sitecritic.net <br/>

Google API Key:  
<input type="text" name="key" />  
eg. EVwOpL34dfds2mD4354651ksCpk/YoYE <br/>
Keyword:  
<input type="text" name="q" />  
eg. Web Site Reviews<br />

Max Results To Search:  
<input name="resultLimit" type="text" value="500" size="4" />  
eg. 500 </p>
 
<p>    
<input type="submit" name="submit" value="Submit" />
</p>
</form>

Conclusion

Unless your web site is well established and already has a good Google ranking, tracking it in Google can be a tedious process. This script can make your life easier by automating the process, allowing you to search through the results until your "1000 queries a day" limit is reached. By understanding the logic involved, you can also transport the script to other languages. An automated task (e.g. a cron job on Unix or a Windows Scheduled Task) could also be set up to run the script at a certain time of day, and email you the results once the search has completed.

Don't forget: the full source code is available for download [6].

[1] http://www.sitepoint.com/examples/googleapi/googleapisearch.zip
[2] http://web-developer.sitecritic.net/google_api_search.php
[3] http://www.google.com/apis
[4] http://www.google.com/apis
[5] http://pear.php.net/package/SOAP
[6] http://www.sitepoint.com/examples/googleapi/googleapisearch.zip