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

Decoding the Google Custom Search AJAX API

by Avi Rappoport, Search Tools Consulting


The Google Custom Search Engine Element is a JavaScript object introduced in June 2009. It hides all complexity, generating a bit of code that non-technical users can copy and paste to their web pages and especially to blogs. Unlike earlier versions of the CSE, this new element can work within the browser to display the results in the same page, rather than in an iframe page or a Google-hosted page.

For more information on the Custom Search Engine (free, with advertising) and Site Search (paid) features, see my Google Search Service Tools page and review of the Custom Search Engine from 2007.

Programmers who are comfortable with the Google AJAX API will find it very easy to understand and use the new class. However, non-programmers may prefer the other ways to call the CSE. For the paid ('Site Search') version, there are a great many useful options in the XML interface for Site Search, such as a display of Rich Text snippets,

For the AJAX version, there a page of CustomSearchControl documentation, The CustomSearch object can use all the methods and properties from the Search and WebSearch classes, as described in the Search AJAX API Class Reference Documentation. However, it takes a while to decode which ones apply and how to use them (Firebug and the Safari 4 Developer tools help a lot).

I have created some CSE object example source code, extensively commented, which is free for the taking. It creates and draws the search form, dispatches the query to Google, and displays the results inside a div tag on the same page as the form (that's a new feature for CSE). I have added a custom to set the target of links in the results to the same page, instead of a new page, so it works more like the Google web search. The other is just a little string of text for the engine to display if there are no matches for the search, instead of nothing. Every search should be more helpful in that case, and I have some best practices on the No-Matches Page Guide.

The example search below is the same code that is presented in the example page, including background color and left margin. CSS settings turn the result titles to red text and shows the full URL of the page, instead of the short host-only URL, as per the CSS Results Formatting page.

If you'd like to see some alternatives, I have a list of hosted site search services and of many flavors of Site/Enterprise search tools. I am also available for search consulting, both for large and small jobs. Please contact Search Tools for more information.


Google Custom/Site Search API Example

custom code by Avi Rappoport, SearchTools.com

Loading gcse object

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

Page Updated: 2009-07-24