As of January, 2012, this site is no longer being updated, due to work and health issues

Google Custom Search API Decoded -
Simple Sample Code

Avi Rappoport, Search Tools.com


The Google CustomSearch object interface is a new way to add site-specific search to a web site or blog, using a JavaScript class and the whole power of the Google Search AJAX API.

See also: Google CSE API Analysis,
Google Search Service Tools page,
and review of the CSE/ 2007.

The new interface is complex enough in its JavaScript object code that it's easy to break their default examples without knowing how to fix it. I highly recommend Firebug for Firefox and the Safari Debugging tools. Between the two of them and a million readings of the CustomSearchControl documentation and Search AJAX API Class Reference Documentation, I figured it out. My thanks to Adam Feldman of Google for posting a very helpful answer in the custom search help forum.

You can test the functionality in this example which uses exactly the same code as the visible code example, except that it has my ID: you should get your own Google Custom Search ID.

Google Custom Search Engine AJAX API Test

GCSE loading: requires JavaScript

Script in the header, using CDATA to escape parser encoding issues

I have put the AJAX script in the header instead of the body, for ease of access. However, when the browser opens a page and reads the HTML to display it, it will call the scripting parsers for everything surrounded by <script> tags. In the header, if text includes ampersands and other possible escape characters, that might cause problems, tell the browser that is should ignore un-escaped characters, by using the command //<![CDATA before the script text and //]]> after it.

Change result click target

The default behavior for the Custom Search class is to respond to clicks in the search results by opening the link in a new browser window in front of the search results. This is not how the Google web search (or any other major search engine) works, and will be confusing to naive users.

To instruct the CustomSearchControl to open clicked results in the same window, call the method:

cseControl.setLinkTarget (google.search.Search.LINK_TARGET_SELF);

Add a helpful note if there are no matches

By default, the Custom Search Element will just show nothing, or just an ad, if the search terms find no matches in the index for the site(s).

I've done some testing and log analysis, and strongly recommend better communication in no-match situations. Even if you can't get elaborate, at least give the user a helpful note, using the supplied method:

cseControl.setNoResultsString
  ("Sorry, there are no pages in this web site
   that match all the search terms."
);

And the situation will be clearer:


Source Code for getting and setting the CustomSearchControl

<head>

<!-- link to the Google JavaScript API library -->

<script src="http://www.google.com/jsapi" type="text/javascript"></script>

<!-- the search functions -->

<script type="text/javascript">

//<![CDATA[// <!-- hides any escape codes in the JavaScript -->

google.load('search', '1'); // loads Google Search library, v 1

// call this function when the browser loads the google lib.

google.setOnLoadCallback(function()

{

// get a custom search control & keep it in cseControl

// note: put your own custom search ID number here

var cseControl = new google.search.CustomSearchControl('YOUR CSE ID HERE');

// open pages from search results clicks on the same page

cseControl.setLinkTarget(google.search.Search.LINK_TARGET_SELF);

// when there are no matches, explain why

cseControl.setNoResultsString

("Sorry, there are no pages in this web site that match all the search terms.");


// make the search field visible in div with ID 'cseDiv'

cseControl.draw('cseDiv');

 

}, true);// end of block setOnLoadCallback

//]]></script>    <!-- end of the JavaScript -->

 

<!-- to override the server styles, including the weird ones,

     put the css statements after the script, -->

<style type="text/css"><!--

.search-style { width:80%; margin-left:3em; background-color:#ccccff; }

--></style>

</head>

 

<body>

<!-- navigation and page header text goes here-->

<h1 align="center">Google CSE Element Object Test</h1>

<h4 align="center">code by Avi Rappoport, SearchTools.com</h4>

<hr>

<!-- This div is important, the search field and results will go here -->

<div id="cseDiv" class="search-style">Loading gcse object</div>

<hr />

<!-- additional text & navigation can go here-->

</body>


For more information, advice, or search consulting, please contact Search Tools Consulting.

Page Updated: 2009-07-02