Google AJAX web search API

== readers through feed readers (like google reader), please visit my blogspot page to get the full context of this post. Sample scripts/formatting may not work in feed readers ==

While I was thinking about unique ways of enhancing my blog, this thought struck me -- the idea is to show a random search result from Google when searched for me. And here it is. You can see my own blogger widget on the right column, that shows a random search result.

The work needed to add our own stuff as a widget dynamically to a blog is a separate topic and I would not talk about it now. This post will concentrate only on how to use Google AJAX websearch APIs to get a search result and how to make use of it.

Obviously, Google's API would be anytime a better choice instead of trying to manage our own ajax requests to google search and parse the resulting HTML. Google AJAX search APIs are well structured, with WebSearch being one implementation of a generic Search interface. The other implementations implementing the Search interface include LocalSearch (classifieds), VideoSearch (youtube), BlogSearch, NewsSearch, ImageSearch etc., Effectively this design allows us to program any search in a very similar fashion.

For a simple user, google.search.SearchControl is an important class. This wraps the UI portion that formats and displays the search results.

A simple code:

google.load('search', '1.0');

// the UI wrapper
var search_control = new google.search.SearchControl();

// one can add any number of searchers to the search control.
search_control.addSearcher(new google.search.WebSearch());

// attach the search ctrl to a div element (ideally) -- where it populates the results
search_control.draw(document.getElementById("search_control_div"));

// this call would do a search and populate the results in 'search_control_div'.
search_control.execute("google api");

But for my requirement, this is not going to help. This will pollute my blog page. These are my requirements:

1. Only one search result required
2. Result should be randomly selected
3. Formatted in my own way to avoid cluttering

As I need to present my own UI, I don't need a SearchControl for my use. All I need is a WebSearch class. See this self-explaining code:

var srch = new google.search.WebSearch();
srch.execute("\"gerald naveen\"");

This would do the search and put the results in the "implied" read-only property named "results" of Search interface. results is an array of type GwebResult in the case of WebSearch. My script can make use of the results array to present the result in the required fashion in a blogger widget. However, the execute method (as expected) is asynchronous -- so you need to wait for the operation to complete before making use of the results array. To get notified, you need to register a callback for search completion as shown:

function when_done( srch)
{
   // populate the custom widget from srch.results[ ]
   // results[] is an array of GwebResult
  // most useful GwebResult members : url, content, title
}

srch.setSearchCompleteCallback(null, when_done, new Array(srch));

All that is remaining for my requirement is to choose a random result. Every search page by default returns 4 results (this can be increased programmatically). There are a number of such pages. I had to randomly seek to a page and then randomly choose one result and show it to the user. To seek to a page, I used gotoPage(n) function in the Search interface.

In summary, the overall code for my search widget looks something like this: (click on expand source to view).

function my_random(n)
{
   return Math.floor(Math.random()*n);
}

function search_gerald()
{
   var srch = new google.search.WebSearch();
   srch.execute("\"gerald naveen\"");
   srch.setSearchCompleteCallback(null, when_done, new Array(srch, true));
}

function when_done(srch, first) {
   if(first) {
       srch.gotoPage(my_random(10));
       srch.setSearchCompleteCallback(null, when_done, new Array(srch, false));
       return;
   }
   var result = srch.results[my_random(srch.results.length-1)];
   var my_ctx = "<a href='" + result.url + "' target='_blank'>" 
              + result.title + "</a><br>" + result.content + "<br>";
   document.getElementById("search_result").innerHTML = my_ctx;
}

For more information visit Google's official developer's guide for AJAX Search API.