Posted on Thursday 29th of November 2007 at 06:31 in Tutorials

Google Custom Search tutorial (using XML and PHP)

Recently I've been doing some work with the new Google Custom Search and while it is still in beta, it's still a very powerful tool. The main problem I had with it was the lack of useful examples/documentation explaining how to extract your results. So after some tinkering I've got a very basic example with a PHP class to make life easier.

Google Custom Search is pretty useful; for $100 a year you can have a fully customisable search engine indexing up to 5,000 pages. You are given a unique ID number, you specify the URLs that are to be searched and the results are returned as XML. Fortunately Google do provide documentation for the XML schema - because you DO need it. The XML has dozens of tiers without meaningful naming conventions... So I'm publishing my initial efforts as a tutorial to allow people to get up to speed quickly.

My googleCustomSearch PHP Class It seemed logical to write a re-usable PHP class for future implementations, so let me explain what I've done (don't worry, there is a full downloadable version):

Download the Google Custom Search example
class googleCustomSearch { function googleCustomSearch() { } function cleanInput($input) { $input = preg_replace('/[^a-zA-Z0-9\s]/', '', $input); $input = str_replace(" ","+",$input); $input = str_replace("++","+",$input); return $input; }
So I start my class and have the empty googleCustomSearch() constructor. I then have a handy method for cleaning inputs (from a search form for example), making them largely safe for PHP.
function getXML($searchterms,$start) { $cseNumber = '054433340767201226619%3A8wd17vnupp8'; $xmlfile = 'http://www.google.com/search?cx='.$cseNumber.'&client=google-csbe&start='.$start.'&num=10&output=xml_no_dtd&q='.$searchterms; $xml = new SimpleXMLElement(file_get_contents($xmlfile)); return $xml; }
The above function is to get the XML result back using the PHP SimpleXMLElement library. The $cseNumber variable is the unique identifier that Google provides you with to identify your custom search engine above anyone elses. I've spoofed this example with a random number to show you what you should expect to see. Then it's just a case of building the string for the XML file. Google provides this information but it's important to query-string on the searchterms ($searchterms) in the above way (identified by "q" in the querystring itself). The $start variable is used for pagination, I'll explain more about that later on.
function getTotalResults($xml) { $total = $xml->RES->M; return $total; } function getPageTotal($xml) { return count($xml->RES->R); }
getTotalResults() gives you the estimated number of total results for the search (although this is criminally inaccurate on anything but the last pages of the resultset), so this too is used in pagination. The getPageTotal() function returns how many results you're dealing with on the current page.
function writePagination($totalnum, $total, $start, $searchterms) { //if there you have a full 10 results on the page if($total >= 10) { //if we're not at the start if($start != 0) { echo '<a href=""><strong>< Previous Page</strong></a>'; echo '  '; } //if where you started + 10 is NOT equal to the total number of results if(($start + 10) != $totalnum) { echo '<a href=""><strong>Next Page ></strong></a>'; } } }
Here is my function that writes the pagination at the foot of the search results. This takes a number of variables as parameters to work out whether there are more results and which page you're on (so you don't write "previous page" on the first page of results, for example).
function writeSearchResults($xml) { foreach ($xml->RES->R as $key) { $output .= '<p class="search-result"><a href="'.$key->U.'">'.$key->T.'</a>'; $output .= $key->S.'<br />'; $output .= '<span>'.$key->U.'</span></p>'; $output .= '</p>'; } echo $output; }
This is the important function - it outputs the search results. Obviously this will need to be customised depending on how you want your results to be displayed but this simply displays them in the same manner Google does.
function writeSuggestion($xml) { $searchterm = $xml->Q; $suggestion = $xml->Spelling->Suggestion; if($suggestion != "") echo '<p>You searched for <strong>'.$searchterm.'</strong>, did you mean <strong><a href="">'.$suggestion.'</a></strong>?</p>'; } }
And here we have the final function that writes any suggestions Google has - i.e. if you typed something incorrectly or it didn't recognise the search term. Then it will write the suggestion with the suggestion as a link which runs the search with that word. Finally we close the class.

That's all very confusing and long winded, so how do we implement it? I'm not going to explain that all here but I'll provide it as a downloadable example. It's merely a case of instantiating the class and capturing the search terms, with attention placed on the querystrings used to paginate through the results.

So basically you need to be able to take numerous querystring values to allow you to alter the starting point of the search results. This is all explained fully in comments within the PHP documents so please download them and have a look through.

Download the Google Custom Search example

Hopefully the explanation of the class is of some use, but really the best information is contained within the comments in my examples. You should be able to just replace the cseNumber and use my example. If you have any problems, questions, comments or queries please drop them in a comment or send me an email.

Enjoy this article? Why not subscribe to the full RSS feed?