Programmable Search Element Control API

You can embed Programmable Search Engine components (search boxes and search results pages) in your web pages and other web applications using HTML markup. These Programmable Search Engine elements consist of components that are rendered based on settings stored by the Programmable Search server, along with any customizations you make.

All JavaScript is loaded asynchronously, which allows your webpage to continue loading while the browser fetches the Programmable Search Engine JavaScript.

Introduction

This document provides a basic model for adding Programmable Search Engine elements to your web page, along with explanations of the element's configurable components and flexible JavaScript API.

Scope

This document describes how to use the functions and properties specific to the Programmable Search Engine Control API.

Browser compatibility

The list of browsers supported by Programmable Search Engine can be found here .

Audience

This documentation is intended for developers who wish to add Google Programmable Search functionality to their pages.

Programmable Search Elements

You can use HTML markup to add a Programmable Search Element to your page. Each element consists of at least one component: a search box, a block of search results, or both. The search box accepts user input in any of the following ways:

• A search query typed in the text input field
• A query string embedded in a URL
• Programmatic execution

In addition, the block of search results accepts input in the following ways:

• A query string embedded in a URL
• Programmatic execution

The following types of Programmable Search Elements are available:

You can add any number of valid Search Elements to your webpage. For two-column mode, all required components (a searchbox and search results block) must be present.

Here is an example of a simple Search Element:

<!-- Put the following javascript before the closing </head> tag
and replace 123456 with your own Programmable Search Engine ID. -->
<script async src="https://cse.google.com/cse.js?cx=123456"></script>

<!-- Place this tag where you want both of the search box and the search results to render -->
<div class="gcse-search"></div>

Compose different layout options using Programmable Search Elements

The following layout options are available on the Look and Feel page of the Programmable Search Engine control panel. Here are some general guidelines about composing layout options using Programmable Search Elements. To see a demo of any of these options, click the link.

More information about layout options.

Customizing Programmable Search Elements

To customize colors, font, or link style, go to the Look and Feel page of your programmable search engine.

You can use optional attributes to overwrite configurations created in the Programmable Search Engine control panel . This enables you to create a page-specific search experience. For example, the following code creates a search box that opens a result page (http://www.example.com?search=lady+gaga) in a new window. The value of the queryParameterName attribute, along with the user query string, is used to create the results URL.

Note that the queryParameterName attribute is prefixed with data- . This prefix is required for all attributes.

<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">

If you've used the Programmable Search Engine control panel to enable features like autocomplete or refinements , you can use attributes to customize those features. Any customizations you specify using these attributes will override settings made in the control panel. The following example creates a two-column Search Element with the following features:

• History management is enabled
• The maximum number of displayed autocompletions is set to 5
• Refinements are displayed as links.

<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5">
<div class="gcse-searchresults" data-refinementStyle="link">

Supported attributes

<div class="gcse-searchbox" data-gname="storesearch"></div>
<div class="gcse-searchresults" data-gname="storesearch"></div>

Callbacks

Callbacks support detailed control of the search-element initialization and search processes. They are registered with the Search Element JavaScript through the global __gcse object. Register Callbacks illustrates registration of all the supported callbacks.

   
 window 
 . 
 __gcse 
  
 = 
  
 { 
  
 parsetags 
 : 
  
 'explicit' 
 , 
  
 // 
  
 Defaults 
  
 to 
  
 'onload' 
  
 initializationCallback 
 : 
  
 myInitializationCallback 
 , 
  
 searchCallbacks 
 : 
  
 { 
  
 image 
 : 
  
 { 
  
 starting 
 : 
  
 myImageSearchStartingCallback 
 , 
  
 ready 
 : 
  
 myImageResultsReadyCallback 
 , 
  
 rendered 
 : 
  
 myImageResultsRenderedCallback 
 , 
  
 }, 
  
 web 
 : 
  
 { 
  
 starting 
 : 
  
 myWebSearchStartingCallback 
 , 
  
 ready 
 : 
  
 myWebResultsReadyCallback 
 , 
  
 rendered 
 : 
  
 myWebResultsRenderedCallback 
 , 
  
 }, 
  
 }, 
  
 }; 
  
 

The Initialization Callback

The initialization callback is invoked before the Search Element JavaScript renders search elements in the DOM. If parsetags is set to explicit in __gcse , the Search Element JavaScript leaves rendering Search Elements to the initialization callback (as shown in Register Callbacks ). This might be used to select elements to render, or to defer rendering elements until they are needed. It can also override the attributes of the elements; for instance, it can turn a searchbox that is configured through the Control Panel or HTML attributes to default to web search into an image search box, or specify that queries submitted via a Programmable Search Engine form are executed in a searchresults-only element. See a demo.

The role of the initialization callback is controlled by the value of the parsetags property of __gcse .

• If its value is onload , the Search Element JavaScript renders all Search Elements on the page automatically. The initialization callback is still invoked, but it is not responsible for rendering the Search Elements.
• If its value is explicit , the Search Element JavaScript does not render Search Elements. The callback may render them selectively using the render() function, or render all Search Elements with the go() function

The following code demonstrates how to render a search box, together with search results, in a div , using the explicit parsetag and initialization callback:

 <div id="test"></div> 

  const 
  
 myInitCallback 
  
 = 
  
 function 
 () 
  
 { 
  
 if 
  
 ( 
 document 
 . 
 readyState 
  
 == 
  
 'complete' 
 ) 
  
 { 
  
 // 
  
 Document 
  
 is 
  
 ready 
  
 when 
  
 Search 
  
 Element 
  
 is 
  
 initialized 
 . 
  
 // 
  
 Render 
  
 an 
  
 element 
  
 with 
  
 both 
  
 search 
  
 box 
  
 and 
  
 search 
  
 results 
  
 in 
  
 div 
  
 with 
  
 id 
  
 'test' 
 . 
  
 google 
 . 
 search 
 . 
 cse 
 . 
 element 
 . 
 render 
 ( 
  
 { 
  
 div 
 : 
  
 "test" 
 , 
  
 tag 
 : 
  
 'search' 
  
 }); 
  
 } 
  
 else 
  
 { 
  
 // 
  
 Document 
  
 is 
  
 not 
  
 ready 
  
 yet 
 , 
  
 when 
  
 Search 
  
 Element 
  
 is 
  
 initialized 
 . 
  
 google 
 . 
 setOnLoadCallback 
 ( 
 function 
 () 
  
 { 
  
 // 
  
 Render 
  
 an 
  
 element 
  
 with 
  
 both 
  
 search 
  
 box 
  
 and 
  
 search 
  
 results 
  
 in 
  
 div 
  
 with 
  
 id 
  
 'test' 
 . 
  
 google 
 . 
 search 
 . 
 cse 
 . 
 element 
 . 
 render 
 ( 
  
 { 
  
 div 
 : 
  
 "test" 
 , 
  
 tag 
 : 
  
 'search' 
  
 }); 
  
 }, 
  
 true 
 ); 
  
 } 
 }; 
 // 
  
 Insert 
  
 it 
  
 before 
  
 the 
  
 Search 
  
 Element 
  
 code 
  
 snippet 
  
 so 
  
 the 
  
 global 
  
 properties 
  
 like 
  
 parsetags 
  
 and 
  
 callback 
 // 
  
 are 
  
 available 
  
 when 
  
 cse 
 . 
 js 
  
 runs 
 . 
 window 
 . 
 __gcse 
  
 = 
  
 { 
  
 parsetags 
 : 
  
 'explicit' 
 , 
  
 initializationCallback 
 : 
  
 myInitCallback 
 }; 
 

 <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script> 

Search Callbacks

The Search Element JavaScript supports six callbacks that operate in the search control flow. The search callbacks come in pairs, a web-search callback and matching image-search callback:

• Search Starting
  • For image search
  • For web search
• Results ready
  • For image search
  • For web search
• Results rendered
  • For image search
  • For web search

Like the initialization callback, the search callbacks are configured using entries in the __gcse object. This happens as the Search Element JavaScript starts. Modifications to __gcse after startup are ignored.

Each of these callbacks is passed the gName for the Search Element as an argument. The gname is useful when a page contains more than one search. Give a search element a gname values using the data-gname attribute:

<div class="gcse-searchbox" data-gname="storesearch"></div>

If the HTML doesn’t identify the gname, the Search Element JavaScript generates a value that will remain consistent until the HTML is modified.

Image/Web Search-Starting Callback

The search starting callbacks are invoked immediately before the Search Element JavaScript requests search results from its server. An example use-case would be using the local time of day to control changes to the query.

searchStartingCallback(gname, query)

gname

Search Element's identifying string

query

value entered by the user (possibly modified by search element JavaScript.)

The callback returns the value that should be used as the query for this search. If it returns an empty string, the return value is ignored and the caller uses the unmodified query.

Alternatively, you can put the callback function in the __gcse object or dynamically add the callback to the object with JavaScript:

window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};

Example Search Starting Callback

The example search starting callback in Example Search Starting Callback adds either morning or afternoon to the query depending on the time of day.

  
  const 
  
 myWebSearchStartingCallback 
  
 = 
  
 ( 
 gname 
 , 
  
 query 
 ) 
  
 => 
  
 { 
  
 const 
  
 hour 
  
 = 
  
 new 
  
 Date 
 () 
 . 
 getHours 
 (); 
  
 return 
  
 query 
  
 + 
  
 ( 
 hour 
 < 
 12 
  
 ? 
  
 ' morning' 
  
 : 
  
 ' afternoon' 
 ); 
  
 }; 
  
 window 
 . 
 myImageSearchStartingCallbackName 
  
 = 
  
 myWebSearchStartingCallback 
 ; 
 

Install this callback in window.__gcse:

  
  window 
 . 
 __gcse 
  
 || 
  
 ( 
 window 
 . 
 __gcse 
  
 = 
  
 {} 
 ); 
  
 window 
 . 
 __gcse 
 . 
 searchCallbacks 
  
 = 
  
 { 
  
 image 
 : 
  
 { 
  
 starting 
 : 
  
 'myImageSearchStartingCallbackName' 
 , 
  
 } 
 , 
  
 web 
 : 
  
 { 
  
 starting 
 : 
  
 myWebSearchStartingCallback 
 , 
  
 } 
 , 
  
 } 
 ; 
  
 

 <script
  async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div> 

Image/Web Search Results-Ready Callback

These callbacks are invoked immediately before the Search Element JavaScript renders promotions and results. An example use case would a callback that renders promotions and results in a style that cannot be specified with normal customization.

resultsReadyCallback(gname, query, promos, results, div)

gname

Search Element's identifying string

query

query that produced these results

promos

an array of promotion objects, which correspond to matched promotions for the user’s query. See the promotion object definition .

results

an array of result objects. See the result object definition .

div

an HTML div positioned in the DOM where the Search Element would ordinarily place promotions and search results. Normally, the Search Element JavaScript would handle populating this div, but this callback may choose to stop the automatic rendering of results and use this div to render results itself.

If this callback returns a true value, the Search Element JavaScript skips to its page-footer work.

Example Results Ready Callback

The example resultsReady callback in Example Results Ready Callback overrides the default presentation of promotions and results with a very simple replacement.

  
   const 
  
 myResultsReadyCallback 
  
 = 
  
 function 
 ( 
 name 
 , 
  
 q 
 , 
  
 promos 
 , 
  
 results 
 , 
  
 resultsDiv 
 ) 
  
 { 
  
 const 
  
 makePromoElt 
  
 = 
  
 ( 
 promo 
 ) 
  
 => 
  
 { 
  
 const 
  
 anchor 
  
 = 
  
 document 
 . 
 createElement 
 ( 
 'a' 
 ); 
  
 anchor 
 . 
 href 
  
 = 
  
 promo 
 [ 
 'url' 
 ]; 
  
 anchor 
 . 
 target 
  
 = 
  
 '_blank' 
 ; 
  
 anchor 
 . 
 classList 
 . 
 add 
 ( 
 'gs-title' 
 ); 
  
 const 
  
 span 
  
 = 
  
 document 
 . 
 createElement 
 ( 
 'span' 
 ); 
  
 span 
 . 
 innerHTML 
  
 = 
  
 'Promo: ' 
  
 + 
  
 promo 
 [ 
 'title' 
 ]; 
  
 anchor 
 . 
 appendChild 
 ( 
 span 
 ); 
  
 return 
  
 anchor 
 ; 
  
 }; 
  
 const 
  
 makeResultParts 
  
 = 
  
 ( 
 result 
 ) 
  
 => 
  
 { 
  
 const 
  
 anchor 
  
 = 
  
 document 
 . 
 createElement 
 ( 
 'a' 
 ); 
  
 anchor 
 . 
 href 
  
 = 
  
 result 
 [ 
 'url' 
 ]; 
  
 anchor 
 . 
 target 
  
 = 
  
 '_blank' 
 ; 
  
 anchor 
 . 
 classList 
 . 
 add 
 ( 
 'gs_title' 
 ); 
  
 anchor 
 . 
 appendChild 
 ( 
 document 
 . 
 createTextNode 
 ( 
 result 
 [ 
 'visibleUrl' 
 ])); 
  
 const 
  
 span 
  
 = 
  
 document 
 . 
 createElement 
 ( 
 'span' 
 ); 
  
 span 
 . 
 innerHTML 
  
 = 
  
 ' ' 
  
 + 
  
 result 
 [ 
 'title' 
 ]; 
  
 return 
  
 [ 
 anchor 
 , 
  
 span 
 ]; 
  
 }; 
  
  const 
  
 table 
  
 = 
  
 document 
 . 
 createElement 
 ( 
 'table' 
 ); 
  
 if 
  
 ( 
 promos 
 ) 
  
 { 
  
 for 
  
 ( 
 const 
  
 promo 
  
 of 
  
 promos 
 ) 
  
 { 
  
 const 
  
 row 
  
 = 
  
 table 
 . 
 insertRow 
 ( 
 - 
 1 
 ); 
  
 const 
  
 cell 
  
 = 
  
 row 
 . 
 insertCell 
 ( 
 - 
 1 
 ); 
  
 cell 
 . 
 appendChild 
 ( 
 makePromoElt 
 ( 
 promo 
 )); 
  
 } 
  
 resultsDiv 
 . 
 appendChild 
 ( 
 table 
 ); 
  
 resultsDiv 
 . 
 appendChild 
 ( 
 document 
 . 
 createElement 
 ( 
 'br' 
 )); 
  
 } 
  
 if 
  
 ( 
 results 
 ) 
  
 { 
  
 const 
  
 table 
  
 = 
  
 document 
 . 
 createElement 
 ( 
 'table' 
 ); 
  
 for 
  
 ( 
 const 
  
 result 
  
 of 
  
 results 
 ) 
  
 { 
  
 const 
  
 row 
  
 = 
  
 table 
 . 
 insertRow 
 ( 
 - 
 1 
 ); 
  
 const 
  
 cell 
  
 = 
  
 row 
 . 
 insertCell 
 ( 
 - 
 1 
 ); 
  
 const 
  
 [ 
 anchor 
 , 
  
 span 
 ] 
  
 = 
  
 makeResultParts 
 ( 
 result 
 ); 
  
 cell 
 . 
 appendChild 
 ( 
 anchor 
 ); 
  
 const 
  
 cell2 
  
 = 
  
 row 
 . 
 insertCell 
 ( 
 - 
 1 
 ); 
  
 cell2 
 . 
 appendChild 
 ( 
 span 
 ); 
  
 } 
  
 resultsDiv 
 . 
 appendChild 
 ( 
 table 
 ); 
  
 } 
  
 return 
  
 true 
 ; 
  
 }; 
 

  
  window 
 . 
 __gcse 
  
 || 
  
 ( 
 window 
 . 
 __gcse 
  
 = 
  
 {} 
 ); 
  
 window 
 . 
 __gcse 
 . 
 searchCallbacks 
  
 = 
  
 { 
  
 web 
 : 
  
 { 
  
 ready 
 : 
  
 myResultsReadyCallback 
 , 
  
 } 
 , 
  
 } 
 ; 
 

 <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div> 

Image/Web Search Results-Rendered Callback

These callbacks are invoked immediately before the Search Element JavaScript renders the page footer. Example use cases would include a callback that adds result content that the search element does not display such as a save this checkbox or information that is not automatically rendered, or a callback that adds for more information buttons.

If a results rendered callback needs information that was in the promos and results parameters of the results ready callback , it can pass that between them, like this:

callback(gname, query, promoElts, resultElts);

gname

Search Element's identifying string

query

search string.

promoElts

an array of the DOM elements containing promotions.

resultElts

an array of the DOM elements containing results.

There is no return value.

Example Results Rendered Callback

The example resultsRendered callback in Example Results Rendered Callback adds a dummy Keep checkbox to each promotion and result.

  myWebResultsRenderedCallback 
  
 = 
  
 function 
 ( 
 name 
 , 
  
 q 
 , 
  
 promos 
 , 
  
 results 
 ) 
  
 { 
  
 for 
  
 ( 
 const 
  
 div 
  
 of 
  
 promos 
 . 
 concat 
 ( 
 results 
 )) 
  
 { 
  
 const 
  
 innerDiv 
  
 = 
  
 document 
 . 
 createElement 
 ( 
 'div' 
 ); 
  
 innerDiv 
 . 
 appendChild 
 ( 
 document 
 . 
 createTextNode 
 ( 
 'Keep: ' 
 )); 
  
 const 
  
 checkBox 
  
 = 
  
 document 
 . 
 createElement 
 ( 
 'input' 
 ); 
  
 checkBox 
 . 
 type 
  
 = 
  
 'checkbox' 
 ; 
  
 checkBox 
 . 
 name 
  
 = 
  
 'save' 
 ; 
  
 innerDiv 
 . 
 appendChild 
 ( 
 checkBox 
 ); 
  
 div 
 . 
 insertAdjacentElement 
 ( 
 'afterbegin' 
 , 
  
 innerDiv 
 ); 
  
 } 
  
 }; 
 

  window 
 . 
 __gcse 
  
 || 
  
 ( 
 window 
 . 
 __gcse 
  
 = 
  
 {} 
 ); 
 window 
 . 
 __gcse 
 . 
 searchCallbacks 
  
 = 
  
 { 
  
 web 
 : 
  
 { 
  
 rendered 
 : 
  
 'myWebResultsRenderedCallback' 
 , 
  
 } 
 , 
 } 
 ; 
 

 <script async
    src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div> 

If the results rendered callback needs information that was passed to the results ready callback it can pass that data between the callbacks. The following example shows one of many ways to pass a rating value from richSnippet from the results ready callback to the results rendered callback.

  const 
  
 makeTwoPartCallback 
  
 = 
  
 () 
  
 => 
  
 { 
  
 let 
  
 saveForRenderCallback 
 ; 
  
 const 
  
 readyCallback 
  
 = 
  
 ( 
 name 
 , 
  
 q 
 , 
  
 promos 
 , 
  
 results 
 , 
  
 resultsDiv 
 ) 
  
 => 
  
 { 
  
 saveForRenderCallback 
  
 = 
  
 [] 
 ; 
  
 for 
  
 ( 
 const 
  
 result 
  
 of 
  
 results 
 ) 
  
 { 
  
 const 
  
 { 
  
 richSnippet 
 : 
  
 { 
  
 answer 
  
 = 
  
 [] 
  
 } 
  
 = 
  
 {} 
 , 
  
 } 
  
 = 
  
 result 
 ; 
  
 const 
  
 firstAnswer 
  
 = 
  
 answer 
 [ 
 0 
 ] 
 ; 
  
 if 
  
 ( 
 firstAnswer 
 ) 
  
 { 
  
 const 
  
 upVotes 
  
 = 
  
 firstAnswer 
 [ 
 'upvotecount' 
 ] 
 ; 
  
 if 
  
 ( 
 upVotes 
 ) 
  
 { 
  
 saveForRenderCallback 
 . 
 push 
 ( 
  
 { 
 upvotes 
 : 
  
 parseInt 
 ( 
 upVotes 
 , 
  
 10 
 ) 
 } 
  
 ); 
  
 continue 
 ; 
  
 } 
  
 } 
  
 saveForRenderCallback 
 . 
 push 
 ( 
 {} 
 ); 
  
 } 
  
 } 
 ; 
  
 const 
  
 renderedCallback 
  
 = 
  
 ( 
 name 
 , 
  
 q 
 , 
  
 promos 
 , 
  
 results 
 ) 
  
 => 
  
 { 
  
 for 
  
 ( 
 let 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 results 
 . 
 length 
 ; 
  
 ++ 
 i 
 ) 
  
 { 
  
 const 
  
 div 
  
 = 
  
 results 
 [ 
 i 
 ] 
 ; 
  
 const 
  
 votes 
  
 = 
  
 saveForRenderCallback 
 [ 
 i 
 ][ 
 'upvotes' 
 ] 
 ; 
  
 if 
  
 ( 
 votes 
 ) 
  
 { 
  
 const 
  
 innerDiv 
  
 = 
  
 document 
 . 
 createElement 
 ( 
 'div' 
 ); 
  
 innerDiv 
 . 
 innerHTML 
  
 = 
  
 '<b>Upvotes: ' 
  
 + 
  
 votes 
  
 + 
  
 '</b>' 
 ; 
  
 div 
 . 
 insertAdjacentElement 
 ( 
 'afterbegin' 
 , 
  
 innerDiv 
 ); 
  
 } 
  
 } 
  
 } 
 ; 
  
 return 
  
 { 
 readyCallback 
 , 
  
 renderedCallback 
 } 
 ; 
 } 
 ; 
 

 const {
  readyCallback: webResultsReadyCallback,
  renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
  web: {
    ready: webResultsReadyCallback,
    rendered: webResultsRenderedCallback,
  },
}; 

 <script async
  src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div> 

More Callback Examples

Additional callback examples can be found in the More Callback Examples document.

Promotion and Result Properties

Using JSDoc notation, these are the properties of promotion and result objects. Here, we list all the properties that might be present. The presence of many of the properties depend on the details of the promotion or search result.

{
  content: string,
  image: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  url: string,
  visibleUrl: string,
}

{
  content: string,
  contentNoFormatting: string,
  contextUrl: string, // For image search results only
  fileFormat: string,
  image: { // For image search reseults only
    height: number,
    url: string,
    width: number,
  },
  perResultLabels: !Array<{
    anchor: string,
    label: string,
    labelWithOp: string,
  }>,
  richSnippet: !Array<!Object>, // For web search results only
  thumbnailImage: {
    height: number,
    url: string,
    width: number,
  },
  title: string,
  titleNoFormatting: string,
  url: string,
  visibleUrl: string,
}

richSnippet in results has the loose type of an array of objects. The values of entries in this array are controlled by the structured data found on the web page for each search result. For instance, a review web site might include structured data that adds this array entry to richSnippet :

'review': {
  'ratingstars': '3.0',
  'ratingcount': '1024',
},

Programmable Search Element Control API (V2)

The google.search.cse.element object publishes the following static functions:

 var 
  
 element 
  
 = 
  
 google 
 . 
 search 
 . 
 cse 
 . 
 element 
 . 
 getElement 
 ( 
 'element1' 
 ); 
  
 element 
 . 
 execute 
 ( 
 'news' 
 );