My favorites ▼ | English ▼ | Sign in

Google Custom Search Element

JavaScript Developer's Guide

The Google Custom Search Element allows you to embed Google Custom Search in your web pages and other web applications using JavaScript.

For Flash, and other non-JavaScript environments, there is a separate API that returns JSON-encoded results that are easily processed by most languages and runtimes. For more information, see the Google Custom Search API documentation.

Table of Contents

  1. Introduction
    1. Scope
    2. Browser compatibility
    3. Audience
    4. The "Hello World" of the Custom Search Element
  2. Getting started
    1. Load the JavaScript API and search module
  3. Building a basic application
  4. Customizing the format of search results
  5. Adding an AdSense Publisher ID
  6. Troubleshooting

Introduction

This developer's guide provides a basic model for using the Google Custom Search element, along with granular explanations of the element's configurable JavaScript components. You can use this guide to build a Custom Search element on your page.

Scope

This document describes how to use the functions and properties specific to the Custom Search API.

Browser compatibility

The Google Custom Search API currently supports Firefox 1.5+, IE6+, Safari, Opera 9+, and Chrome.

Audience

This documentation is intended for developers who wish to add Google Custom Search functionality to their pages using the Custom Search Element.

The "Hello World" of the Custom Search Element

The following example creates a Custom Search element on your page. The search form is controlled by a text input field and clear button to clear search results after a search.

Try it out!

The code for this example is as follows: 


<!--
  copyright (c) 2009 Google inc.

  You are free to copy and use this sample.
-->

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Google AJAX Search API Sample</title>
    <script src="https://www.google.com/jsapi"></script>
    <script type="text/javascript">
        google.load('search', '1');
        google.setOnLoadCallback(function(){
          new google.search.CustomSearchControl().draw('cse');
        }, true);
    </script>
  </head>
  <body style="font-family: Arial;border: 0 none;">
    <div id="cse" style="width:100%;">Loading...</div>
  </body>
</html>
​

Getting started

Load the JavaScript API and search module

To begin using the Custom Search API, include the following script in the header of your web page. 

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

Next, load the Google search module with google.load(module, version), where:

  • module calls the specific API module you wish to use on your page (in this case, search).
  • version is the version number of the module you wish to load (in this case, 1). 
<script type="text/javascript">
  google.load("search", "1");
</script>

You can find out more about google.load in the Google Loader developer's guide.

When we do a significant update to the API, we will increase the version number and post a notice on the Search API discussion group. Take note of any required code changes when this occurs, and update your URLs to the new version when they are compliant.

The Google API team will also periodically update the API with recent bug fixes and performance enhancements without requiring a version update. For the most part, these fixes should remain transparent to you, but we may inadvertently break some API clients. Please use the Search API discussion group to report such issues.

Building a basic application

The google.search.CustomSearch constructor initializes the Custom Search service so you can execute Custom Search queries and display results. The methods and properties described below apply to all objects that inherit from this base class. Each of those objects may supply additional interfaces as well.

The google.search.CustomSearchControl(opt_customSearchId) constructor creates a Custom Search Element, where opt_customSearchId is an optional parameter with two possible values:

  • A Custom Search ID scopes results based on the specified CSE.
  • A linked CSE URL, which scopes results to a specification of the CSE either hosted by Google or on your site. To include a linked CSE, enclose the URL in curly braces as follows: 
    google.search.CustomSearchControl(
        {'crefUrl' : 'http://my-ajax-site.com/cref_cse.xml'});

    • You can also call the Custom Search Element with no values, in which case it automatically restricts searches to the current site. In other words, if you call google.search.CustomSearchControl() from http://www.my-site.com, then Custom Search automatically restricts results to that site.

    Once you call the Custom Search Element, bind it to a div as follows: 

    // Create a custom search element
  var customSearchControl = new google.search.CustomSearchControl();

  // Draw the control in example-div
  customSearchControl.draw('example-div');

    For more examples of using the Custom Search element, visit the Code Playground.

    You can also auto-generate the code necessary to include a Custom Search element with this handy wizard.

    Customizing the format of search results

    The Custom Search element offers three methods for designing the look and feel of search results. You can use any of these elements individually, and you can also combine any of them:

    • Create a custom result structure - Using Custom Search element Data Rendering, you can write HTML to include rich snippets and other custom data attributes. For more information, check out the rendering documentation and blog post.
    • Modify result CSS properties - The Custom Search element uses Search Control result styles, which you can modify to change basic look and feel.
    • Use a predefined theme - Google offers several predefined themes so you can customize your look and feel without having to change any code or markup. To use a theme, simply include it in your opening google.load call: 
      google.load("search", "1", {style: google.loader.themes.BUBBLEGUM});

      You can find a full list of the available themes below. If you've created your own custom theme, show it off at our support forum!

      • google.loader.themes.BUBBLEGUM
      • google.loader.themes.ESPRESSO
      • google.loader.themes.GREENSKY
      • google.loader.themes.MINIMALIST
      • google.loader.themes.SHINY

    Adding an AdSense Publisher ID

    .enableAds(pubId) associates an AdSense Publisher ID to your Custom Search Element, where pubId supplies the publisher ID. Supplying a publisher ID allows you to share in the revenue from ads shown with the results.

    Note: If you supplied a Custom Search ID in the constructor, you cannot use this method. Instead, just enter your AdSense Publisher ID into your CSE Control Panel.

    .enableAds() has no return value.

    Troubleshooting

    If you encounter problems with your code:

    • Look for typos. Remember that JavaScript is a case-sensitive language.
    • Use a JavaScript debugger. Google Chrome has a full set of developer tools. In Firefox, you can use the JavaScript console or the Firebug. In IE, you can use the Microsoft Script Debugger.
    • Search the discussion group. If you can't find a post that answers your question, post your question to the group along with a link to a web page that demonstrates the problem.