Google Web Search API (Deprecated)

Class Reference (old classnames and namespace)

Note: The Google Web Search API has been officially deprecated as of November 1, 2010. It will continue to work as per our deprecation policy, but the number of requests you may make per day will be limited. Therefore, we encourage you to move to Custom Search, which provides an alternative solution.

The Google Search API is a JavaScript API implemented in the following classes.

We've updated this documentation to make use of the API loader. This loader makes it easier to use multiple Google APIs on the same page and unifies the namespaces across them. If you don't want to change your code, that's fine -- it won't break and the old namespace will continue to work. We hope you'll choose to transition to the new loader and namespace, as we'll continue to extend it for future APIs.

Click here to view this documentation with the new class name and namespace scheme (e.g. google.search.WebSearch, etc.)

Table of Contents

The Search Control

GSearchControlgoogle.search.SearchControl

An instance of GSearchControlgoogle.search.SearchControl represents a single search control on a page. Each search control manages the presentation of the user interface object and the search mechanism for a selected set of searcher objects (objects which implement the GSearch google.search.Search interface).

GSearchControlgoogle.search.SearchControl - Constructor

Constructor Description

GSearchControl()google.search.SearchControl()

Creates a new search control object. The search control object is a container for searchers, objects which implement the GSearchgoogle.search.Search interface. The search control object is not operational until is has at least one searcher child. A search control is bound to an html container using the .draw() method. Note that searcher objects may not be added to a search control once its draw() method has been called.

The expected order of operations is:

  • sc = new GSearchControl()google.search.SearchControl();
  • sc.addSearcher();
  • sc.draw();

Once these steps have occurred, the search control is active and ready to begin performing searches.

GSearchControlgoogle.search.SearchControl - Methods

Method Description

.addSearcher(searcher, opt_options?)

This method adds a searcher object to the search control. Once added, the search control will coordinate the activities of the searcher. It will coordinate the execution of searches, handle the related search completion events, provide a location where results are to be rendered, and provide a ui for "keeping" or "clipping" search results.

The method accepts an optional GsearcherOptionsgoogle.search.SearchOptions object which is used to specify various searcher specific options:

  • searcher - supplies a searcher object
  • opt_options - if specified, supplies configuration options for this searcher
  • returns - n/a

.draw(element, opt_drawOptions?)

This method is the final step needed to activate a search control object. It may only be called once all searchers have been added into the search control. When called, this method produces the user interface and search result containers for each configured searcher, and then sets up the various linkages needed to coordinate parallel searches across all of the searchers.

The method requires that the caller supply an html block element, typically a div element which the control draws within. The control operates best when provided with at least 300px of width and will scale reasonably well down to ~250px.

The default user interface style is a linear style where the control inputs are at the top followed by a linear set of stacked results. Optionally, callers may request a tabbed user interface which works well when vertical real estate is at a premium.

  • element - supplies an html block element that acts as a container for the control
  • opt_drawOptions - if specified, supplies a GdrawOptionsgoogle.search.DrawOptions object which can be used to specify linear or tabbed drawing mode. The object can also be used to supply the search control with a text input element that should be used to capture query terms. If unspecified, a linear drawing mode is assumed and the control allocates and manages its own text input element.
  • returns - n/a

.setTimeoutInterval(timeoutInterval)

When an application is providing its own input control and asking the search control to use that, the search control uses an input timer to determine when to execute a search. Each time a user types into the search controls text input area, a countdown timer is initialized. When the timer executes, a search is requested. The time lag between the last keystroke and the initiation of a search is programmed using this API. Note: The default value of the control is GSearchControlgoogle.search.SearchControl.TIMEOUT_MEDIUM (about 500ms).

  • timeoutInterval - supplies the value for the timeoutInterval, the amount of time between the last keystroke and the execution of a resulting search. Valid values include:
    • GSearchControlgoogle.search.SearchControl.TIMEOUT_SHORT - used to specify a very short delay ~350ms.
    • GSearchControlgoogle.search.SearchControl.TIMEOUT_MEDIUM - used to specify a medium delay of ~500ms.
    • GSearchControlgoogle.search.SearchControl.TIMEOUT_LONG - used to specify a long delay ~700ms.
  • returns - n/a

.execute(opt_query?)

This method causes the search control to initiate a sequence of parallel searches across all of the searchers configured into the control. If the opt_query argument is supplied, its value is placed within the search controls input text box, and becomes the search expression for the parallel search. Otherwise, the current value of the search control input text box is used. Note: this method allows applications to automate portions of the search control. For example, an application could choose to automatically initiate a search whenever the user hovers over a word or phrase or makes some other application specific gesture.

As a side effect of this call, the current set of search results displayed, as well as the search results stored within each of the controlled searcher objects is cleared.

  • opt_query - supplies an optional search expression used by the ensuing search. If not specified, then the search expression present in the search control's text input box is used.
  • returns - n/a

.setOnKeepCallback(object, method, opt_keepLabel?)

This method is used to inform the search control that the caller would like to be notified when a user has selected for copy, one of the search results managed by the control. If this method is not called, then the user is not offered an opportunity to copy search results. If the method is called, each search result is annotated with a text link, underneath the search result. Clicking on this link will cause the specified method to be called on the specified object, passing in a GResultgoogle.search.Result object associated with the search result. This method allows the caller to specify a built-in, system defined text label value which invites the user to copy a result, or to specify a label more meaningful to the calling application. When using the system defined labels, the value is automatically translated in the language that the rest of the control is running in.

  • object - supplies an application level object that defines the context that the specified method will be called in.
  • method - supplies the method to call. For instance, if this method is called as .setOnKeepCallback(foo, MyObject.prototype.myKeephandler), when a user clicks on the keep label, a call to foo.myKeephandler() is called.
  • opt_keepLabel - supplies an optional text label that sits beneath each search result which, when clicked, triggers a callback into the specified object/method. Valid values include:
    • GSearchControlgoogle.search.SearchControl.KEEP_LABEL_SAVE - a label value of "save"
    • GSearchControlgoogle.search.SearchControl.KEEP_LABEL_KEEP - a label value of "keep"
    • GSearchControlgoogle.search.SearchControl.KEEP_LABEL_INCLUDE - a label value of "include"
    • GSearchControlgoogle.search.SearchControl.KEEP_LABEL_COPY - a label value of "copy" (default)
    • GSearchControlgoogle.search.SearchControl.KEEP_LABEL_BLANK - a blank label value is used, this works well when all you want is the copy graphic (selectable via css)
    • Any other value - the value passed becomes the label. The caller is responsible for localization.
  • returns - n/a

.setResultSetSize(switchTo)

This method is called to select the number of results returned by each of the searchers. This can be a scalar from 1 to 8 (inclusive), or it can be an enumeration. From the sample applications, you have probably seen the more/less twiddle control at the top of the search control. This method is used by that twiddle control.

  • switchTo - supplies a scalar value between 1 and 8 or an enumeration which indicates the desired number of search results to return for each configured searcher. Valid values include:
    • A scalar between 1 and 8
    • GSearchgoogle.search.Search.LARGE_RESULTSET - request a large number of results (typically 8 results)
    • GSearchgoogle.search.Search.SMALL_RESULTSET - request a small number of results (typically 4 results)
    • google.search.Search.FILTERED_CSE_RESULTSET - request up to 10 results. This will only work for Web Search queries scoped to a Filter Custom Search engine, otherwise an error will be returned.
  • returns - n/a

.cancelSearch()

This method is used to tell the search control to ignore all incoming search result completions. The internal state used by this method is reset, to allow searches each time a new search is requested. The intended use of this method is to help applications cope with ui flashing that can occur as slow input triggers inadvertent searches. By using this method each time input is sensed, previous searches based on partial input can easily be ignored.

  • returns - n/a

.clearAllResults()

This method is used to clear all of the search results out of the search control.

  • returns - n/a

.setLinkTarget(linkTarget)

This method is called to set the link target used for links embedded in search results. The default value is GSearchgoogle.search.Search.LINK_TARGET_BLANK which specifies that links will open in a new browser window. When this method is called, a search control wide link target setting is established. This effects all searchers that are currently attached to the search control as well as all searchers that are subsequently added to the control.

  • linkTarget - supplies the target frame that links should open within, valid values include:
    • GSearchgoogle.search.Search.LINK_TARGET_BLANK - links will open in a new window, e.g., <A href=... target=_blank ...>
    • GSearchgoogle.search.Search.LINK_TARGET_SELF - links will open in the same window and frame, e.g., <A href=... target=_self ...>
    • GSearchgoogle.search.Search.LINK_TARGET_TOP - links will open in the topmost frame, e.g., <A href=... target=_top ...>
    • GSearchgoogle.search.Search.LINK_TARGET_PARENT - links will open in either the topmost frame, or replace the current frame, e.g., <A href=... target=_parent ...>
    • anything-else - links will open in the specified frame or window, e.g., <A href=... target=anything-else ...>
  • returns - n/a

.setSearchCompleteCallback(object, method)

This method is used to inform the search control that the caller would like to be notified when a search completes. Note, the granularity of this call is the searcher level, NOT the search control level. What this means is that if your search control contains 5 searchers and you execute a search, as each searcher completes, your callback will be called. Note also, that not all searches will result in completion so be careful not to code deadlocks where you assume that a single completion will occur for each search.

  • object - supplies an application level object that defines the context that the specified method will be called in.
  • method - supplies the method to call. For instance, if this method is called as .setSearchCompleteCallback(foo, MyObject.prototype.mySearchComplete), when a search completes, a call to foo.mySearchComplete(searchControl, searcher) is called. The first argument of the callback, searchControl supplies the search control, and the second argument searcher supplies the searcher object that just completed a search.
  • returns - n/a

.setSearchStartingCallback(object, method)

This method is used to inform the search control that the caller would like to be notified right before a search begins. Note, the granularity of this call is the searcher level, NOT the search control level. What this means is that if your search control contains 5 searchers and you execute a search, as each searcher is told to begin searching, your method will be called.

  • object - supplies an application level object that defines the context that the specified method will be called in.
  • method - supplies the method to call. For instance, if this method is called as .setSearchStartingCallback(foo, MyObject.prototype.mySearchStarting), when a search begins, a call to foo.mySearchStarting(searchControl, searcher, query) is called. The first argument of the callback, searchControl supplies the search control, the second argument searcher supplies the searcher that is about to start a search, and the third argument query supplies the query.
  • returns - n/a

.setNoResultsString(str)

Normally, when a search produces no results, the search control slot for the searcher is left empty. This method allows the caller to specify a string that supplies a default "result". The system contains a value of GSearchControlgoogle.search.SearchControl.NO_RESULTS_DEFAULT_STRING which you can use. This is a localized string that means "No Results" in all supported locales.

  • str - supplies a string value that is used when a search yields no results..
  • returns - n/a

GSearchControlgoogle.search.SearchControl - Static methods

Static method Description

.inlineCurrentStyle(node, opt_deep?)

This utility function is used to clone the current computed style for the specified html node (or tree if opt_deep is specified) and inline the current style into the node. In some instances this function is useful, mainly in conjunction with an on keep handler where the application wishes to preserve a set of html styles while passing a piece of html from one application to another, where the receiving application does not have the associated style sheet. The simplest example of this scenario is in the case of an email application where the email application is using the Google Search API to allow users to clip search results into a message composition window where they will be emailed as html to another user. The recipient's email application in some cases will have no knowledge of Google Search API and will therefore not normally carry its style sheet. To account for this, we provide this method so the originating email application can inline the current styles so that the recipient can read the message with full fidelity.

  • node - supplies and html node whose style should be inlined
  • opt_deep - if specified, the inline operation is recursive inlining the styles for the current node and its descendants.
  • returns - n/a

Note: this method is not currently implemented on the Safari web browser.

GSearchControl google.search.SearchControl - Public Properties

This object does not expose any public properties.

GSearchFormgoogle.search.SearchForm

Applications that use the GSearchgoogle.search.Search objects in standalone form, rather than under control of the GSearchControlgoogle.search.SearchControl will often have a need to capture and process user-generated search requests. The GSearchFormgoogle.search.SearchForm() object is a light weight object that is designed for exactly this use case. It provides applications with a text input element, a search button, an optional clear button, as well as all standard branding.

GSearchFormgoogle.search.SearchForm - Constructor

Constructor Description

GSearchFormgoogle.search.SearchForm(enableClear, element)

Creates a new search form object. The search form object supplies user interface elements, methods, properties, and callbacks designed to allow applications to control a collection of GSearchgoogle.search.Search() objects. The user interface and capabilities match whats available to applications using the GSearchControlgoogle.search.SearchControl()) (in fact, the GSearchControlgoogle.search.SearchControl() is internally based on this object.

The expected order of operations is:

  • sf = new GSearchFormgoogle.search.SearchForm(true/false, container);
  • sf.setOnSubmitCallback(object, method);
  • optional - sf.setOnClearCallback(object, method);

Once these steps have occurred, the search form is active and ready to begin receiving and processing user input.

The method accepts a required enableClear argument as well as a required element argument

  • enableClear - when true, the search form should contain a clear button, otherwise, no clear button is created
  • element - supplies the HTML node that should act as a container for this form

GSearchFormgoogle.search.SearchForm - Methods

Method Description

.setOnSubmitCallback(object, method)

This method registers an object/method combination that is called when the search form is "submitted". This event occurs when the user clicks on the search button, or when the user hits enter while focused on the text input element. When this occurs, the specified object becomes the active object and the specified method is called. The argument passed to the method is this search form.

A typical method might look like this:

App.prototype.onSubmit = function(form) {
  if (form.input.value) {
    this.localSearcher.execute(form.input.value);
  }
  return false;
}
                

Note in the above example that the search form is passed to the method, and that the method returns false indicating that it has processed the submit event.

  • object - supplies an application level object that defines the context that the specified method will be called in.
  • method - supplies the method to call. The method is passed a reference to this form and must return false.

.setOnClearCallback(object, method)

This method registers an object/method combination that is called when the clear button in the search form is pressed. It is an error to call this method if the search form was created without a clear button. When this occurs, the specified object becomes the active object and the specified method is called. The argument passed to the method is this search form.

A typical method might look like this:

App.prototype.onClear = function(form) {
  this.myClearFunction();
  return false;
}
                

Note in the above example that the search form is passed to the method, and that the method returns false indicating that it has processed the clear event.

  • object - supplies an application level object that defines the context that the specified method will be called in.
  • method - supplies the method to call. The method is passed a reference to this form and must return false.

.execute(opt_string?)

This method allows an application to "submit" the form. This involves optionally setting the form's text input element and then calling the registered on-submit callback method established using .setOnSubmitCallback().

  • opt_string - if present, supplies a string value that is placed in the form's text input element prior to invoking the on-submit callback method.
  • returns - n/a

GSearchFormgoogle.search.SearchForm - Static methods

This object does not expose any static methods.

GSearchFormgoogle.search.SearchForm - Public Properties

The following collection of public properties are exposed by the google.search.SearchForm.

Property Description

.input

This property is the text input element for the form. Applications are free to read and write this property at will. Typical use is that in an on-submit callback handler, an application will read form.input.value and then process this string, typically by calling .execute() on a searcher under its control.

.userDefinedCell

The search form's internal structure is a pair of HTML tables. The upper table contains the text input element, the localized search button, and an optional clear button. The lower table contains an application specific free cell, the left hand cell in the table, as well as a right aligned set of Google branding, including both text and an image. This property, the .userDefinedCell property is the DOM node of the table cell designed to hold application specific content. An application is free to use this space to deposit information in close proximity to the search form and aligned with the standard Google branding.

Searchers

GSearchgoogle.search.Search

An instance of the GSearchgoogle.search.Search class provides the ability to execute searches and receive results from a specific search service. This object is not directly used; it is a base class which service-specific searchers inherit from. 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 expected usage of this object is in conjunction with the GSearchControlgoogle.search.SearchControl where the search control provides both user interface and coordination. That said, it is perfectly acceptable for you to use this object independently, but just make sure you are not attempting to share the same instance of a searcher object between your application logic and a search control object.

GSearchgoogle.search.Search - Constructor

Constructor Description

GSearchgoogle.search.Search()

Creates a new searcher object. Note: Since this is a base class, it is unlikely that applications will make direct use of this constructor and instead will use the constructor as a side effect of creating a service specific searcher object (e.g., GwebSearchgoogle.search.WebSearch).

GSearchgoogle.search.Search - Methods

Method Description

.setResultSetSize(indicator)

This method is called to select the number of results returned by each of the searchers. This can be a scalar from 1 to 8 (inclusive), or it can be an enumeration.

  • switchTo - supplies a scalar value between 1 and 8 or an enumeration which indicates the desired number of search results to return for each configured searcher. Valid values include:
    • A scalar between 1 and 8
    • GSearchgoogle.search.Search.LARGE_RESULTSET - request a large number of results (typically 8 results)
    • GSearchgoogle.search.Search.SMALL_RESULTSET - request a small number of results (typically 4 results)
    • google.search.Search.FILTERED_CSE_RESULTSET - request up to 10 results. This will only work for Web Search queries scoped to a Filter Custom Search engine, otherwise an error will be returned.
  • returns - n/a

.getResultSetSize()

This method returns the current result set size, the value established by the previous method.

  • Returns an enumeration or scalar which indicates the current number of search results to return. Valid values include:
    • A scalar between 1 and 8
    • GSearchgoogle.search.Search.LARGE_RESULTSET - large number of results (typically 8 results)
    • GSearchgoogle.search.Search.SMALL_RESULTSET - small number of results (typically 4 results)
    • google.search.Search.FILTERED_CSE_RESULTSET - up to 10 results (only available for Filtered Custom Search engines)

.clearResults()

Upon successful completion of a search, the searcher object holds on to a collection of search results which describe the outcome of a particular search. This method is used to reset the searcher, clearing out all results. This method is implicitly called prior to the execution of a new search.

  • returns - n/a

.execute(query)

This method is called to begin a new search. The query argument supplies the search term. Upon completion, the object becomes populated with the corresponding set of results, and the registered search completion handler is called.

  • query - supplies the query term used to perform the search
  • returns - n/a

.setSearchCompleteCallback(object, method, opt_arguments?)

This method is used to register an object and method to notify on the completion of a search. Applications may optionally pass in a context argument using opt_arguments which is then passed to the specified method.

  • object - supplies an application level object that defines the context that the specified method will be called in.
  • method - supplies the method to call. For instance, if this method is called as .setSearchCompleteCallback(foo, MyObject.prototype.mySearchCompleteHandler), when a search on this searcher completes, a call to foo.mySearchCompleteHandler(opt_arguments?) is called.
  • returns - n/a

.setUserDefinedLabel(label)

This method is used to set a user defined label that should be used when this searcher is added to a search control. By calling this function, the user defined label specified will be used in the result section header or tab instead of the standard, built in labels. Expected usage is in conjunction with site restricted searching where it is both appropriate and expected that applications will indicate that they have programmed in restrictions by changing the standard label.

  • label - supplies a user defined label that replaces "Web", "Blog", etc. in the results section header.
  • returns - n/a

.setUserDefinedClassSuffix(classSuffix)

This method is used to set a user defined class suffix for the search results section, and for the collection of search results produced by this searcher in the search control. The motivation for this method is to allow applications to set unique styling for the results and header of a particular set of search results. Assuming this method is called with a value of "siteSearch", a class of gsc-resultsRoot-siteSearch will be applied to the DIV element that wraps the header and results associated with this searcher. Note, this is in addition to the generic gsc-resultsRoot class.

  • classSuffix - supplies a user defined class suffix that is appended to gsc-resultsRoot-. This class is added to the DIV element that wraps the header and results associated with this searcher.
  • returns - n/a

.setLinkTarget(linkTarget)

This method is called to set the link target used for links embedded in search results. The default value is GSearchgoogle.search.Search.LINK_TARGET_BLANK which specifies that links will open in a new browser window. When a searcher is added to a search control, the search control makes an implicit call to this method using the current link target setting for the search control. This means that if your application needs a searcher to operate with a different link target setting than the setting established by the search control, you need to call this method after adding the searcher to the search control.

  • linkTarget - supplies the target frame that links should open within, valid values include:
    • GSearchgoogle.search.Search.LINK_TARGET_BLANK - links will open in a new window, e.g., <A href=... target=_blank ...>
    • GSearchgoogle.search.Search.LINK_TARGET_SELF - links will open in the same window and frame, e.g., <A href=... target=_self ...>
    • GSearchgoogle.search.Search.LINK_TARGET_TOP - links will open in the topmost frame, e.g., <A href=... target=_top ...>
    • GSearchgoogle.search.Search.LINK_TARGET_PARENT - links will open in either the topmost frame, or replace the current frame, e.g., <A href=... target=_parent ...>
    • anything-else - links will open in the specified frame or window, e.g., <A href=... target=anything-else ...>
  • returns - n/a

.setNoHtmlGeneration()

There are times when your application is not using the search control and is only using a small set of properties from a search result and you are displaying these in a highly customized format. When this is the case, a small optimization is available to your application. The searcher can be programmed to NOT generate an .html property leaving you with only the raw properties valid in a result.

  • n/a - no input arguments
  • returns - n/a

.setQueryAddition(term)

This method allows the caller to set (or clear) an optional, additional query term that is appended to all queries flowing through the searcher. Applications will typically use this to the provide alternative results with mild variations from the original search term. For example, assuming a GwebSearchgoogle.search.WebSearch() based searcher, calling this function as search.setQueryAddition("filetype:pdf");, and then executing a query for "google", will result in the following query "google filetype:pdf". When using this API, we highly recomend using .setUserDefinedLabel() so that you can indicate to your users that their query has been modified. This is the same general advice we give when using .setSiteRestriction().

  • term - supplies an expression that is appended to each query flowing through this searcher (note, you do not need to supply a space). When the value of term is "", the effect of this API is canceled; queries are not modified.
  • returns - n/a

.createResultHtml(result)

This method allows the caller to either create or re-generate the .html property of the specified result. Sometimes this is needed when the caller had previously used .setNoHtmlGeneration(), or when the caller is reloading a result object from its own storage system.

  • result - supplies a result object. It's .html property will be deleted and regenerated as a result of this call. If the result does not contain a .html property, one will be created.
  • returns - n/a

.gotoPage(page)

After a search completes, a cursor property may become visible on the searcher option. This is a function of the number of search results available as well as the capabilities of the underlying searcher. If the cursor property is present, then this method allows you to fetch another bundle of search results. Applications specify which page by using the page argument. This value is then used to index the cursor.pages array which ultimately is used to compute the value of the &start url argument.

  • page - supplies the page number of the results that the application wants. This value is range checked relative to the .cursor.pages property and no operation is performed if the page is out of range or if the underlying searcher does not have a cursor property.
  • returns - n/a

GSearchgoogle.search.Search - Static methods

Static method Description

.scaleImage(width, height, imageScaler, opt_img)

This method is a static helper function that you can use to proportionally scale an image. You pass in the width and height of the current image, as well as an imageScaler object (containing a .width and .height property) and the function will calculate and return a proportionally scaled imageScaler object. You can then use this object's .height and .width property to build an image element.

Internally, the GvideoSearchgoogle.search.VideoSearch object defines an image scaler which it uses to scale the thumbnails. It's designed to maintain a 4x3 aspect ratio and is defined as follows.

// imageScaling defaults 4x3 100x75 image
this.imageScaler = {width:100,height:75};
                

When building the thumbnail img element, it computes the scaled height and width of the thumbnail image as follows:

// scale the thumbnail image using the searcher's .imageScaler.
// By default this is a 4x3 100x75 image,
// but its settable using .setVideoResultsTbHeight as well
var scaled = GSearchgoogle.search.Search.scaleImage(result.tbWidth,
                                result.tbHeight,  this.imageScaler);

// scaled.height and scaled.width now contain
// the values needed to proportionally scale the thumbnail
                

  • width - the original width of the image
  • height - the original height of the image
  • imageScaler - an imageScaler object which specifies in its .height property and its .width property the desired height/width box that the image should fit within.
  • opt_img - supplies and optional img object. If specified, its .height and .width properties are set by this call.
  • returns - an imageScaler object whose .height and .width properties contain the dimensions of the proportionally scaled image

.getBranding(opt_element?, opt_orientation?)

This method is a static helper function that returns a "powered by Google" HTML DOM branding node to your application, and optionally attaches it to your document as the only child of the specified optional element. The purpose of this method is to ensure that your application has a simple way to comply with branding requirements in situations where using with the search form in the GSearchControlgoogle.search.SearchControl or in the GSearchFormgoogle.search.SearchForm is not appropriate for your application.

The branding node, by default, is designed for a horizontal orientation and works well underneath a search form, above or below a collection of results, etc. In some cases, a vertical orientation of the branding is needed. As an example of this, consider a vertically oriented Video Bar. In this case, since the branding needs are so narrow, vertical orientation of the branding is needed (see the "powered by Google" branding at the bottom of the Video Bar). This API by default delivers horizontal orientation, but as an application, you can easily request vertical.

  • opt_element - an optional argument which, if supplied, specifies the HTML DOM node that will be populated with a "powered by Google" branding element.
  • opt_orientation - an optional argument which, if supplied, specifies the orientation of the branding node. Valid values include:
    • GSearchgoogle.search.Search.HORIZONTAL_BRANDING - request horizontal orientation
    • GSearchgoogle.search.Search.VERTICAL_BRANDING - request vertical orientation
  • returns - a "powered by Google" HTML DOM node that you are free to attach or clone onto your document.

.setOnLoadCallback(handler)

This method is a static helper function that registers the specified handler function to be called once the document containing this call loads. Previous documentation recomended that you use the body element's onload attribute (e.g., <body onload="OnLoad()">). While this is a fine way to go when you are in complete control of the page and all code loaded by the page, this approach can cause problems with some runtimes that destroy your body.onload handler. The setOnLoadCallback() approach does not have these problems and therefore is our recomended way of registiring a callback that calls your code upon document load (a point in time when the Search APIs are fully loaded and ready for use).

  • handler - a required function that will be called once the containing document is loaded and when the search API is ready for use.
  • returns - n/a

GSearchgoogle.search.Search - Properties

The following collection of public properties are exposed by all objects that implement this interface. Unless otherwise stated, these properties are assumed to be read-only.

Property Description

.results["]

This property contains an array of search result objects, one for each result. Each time a search executes, this property is cleared, and each time a search completes, the array is populated. If there are no results to report, the .length property of this array will be set to 0.

.cursor

This optional property is present once a search completes successfully. When present, the property specifies how an application can request additional search results for the current query term, the estimated result count, the current page, and the url that can be used to vector to a search results page hosted at Google. The property has the following structure:

  • .pages["] - supplies an array used by .gotoPage() in order to retrieve a bundle of results. Each entry in the array is an object with the following structure:
    • .start - supplies the value that will be used in the &start url argument to request a bundle of results
    • .label - supplies a text label associated with the entry e.g., "1", "2", "3", or "4"
  • .estimatedResultCount - supplies the estimated number of results that match the current query. Note that this value will not necessarily match the similar value thats visible on the Google.com search properties.
  • .currentPageIndex - supplies the index into the pages array of the current set of results.
  • .moreResultsUrl - supplies a url to a Google hosted search page that contains additional search results.

Note: Web Search supports 8 pages, for a maximum total of 64 results.

GwebSearchgoogle.search.WebSearch

This object implements the GSearchgoogle.search.Search interface over the Google Web Search service. Upon completion of a search it delivers a collection of GwebResult objects.

GwebSearchgoogle.search.WebSearch - Constructor

Constructor Description

GwebSearchgoogle.search.WebSearch()

The constructor is used to create an instance of a searcher object designed to provide search results from the Google Web Search service.

GwebSearchgoogle.search.WebSearch - Methods

Method Description

.setSiteRestriction(site, opt_refinement, opt_moreResultsTemplate)

This method is used to restrict the set of web search results returned by this searcher. To restrict to www.amazon.com, simply call this method passing in a value of "www.amazon.com". To clear site restrictions, pass in a value of null. The following snippet demonstrates this setting of a set restriction to "amazon.com".

var siteSearch = new GwebSearchgoogle.search.WebSearch();
siteSearch.setSiteRestriction("amazon.com");
                

This method also allows the caller to restrict searches to a Google Custom Search Engine. Instead of specifying a URL path to this method, pass in the Custom Search Engine ID. The following snippet demonstrates setting a site restriction to a custom search engine whose id is 000455696194071821846:reviews.

var siteSearch = new GwebSearchgoogle.search.WebSearch();
siteSearch.setSiteRestriction("000455696194071821846:reviews");
                

When used in this manner, an optional Custom Search Engine Refinement may be supplied using the opt_refinement. Using this mechanism you are able to site restrict to a subset of your search engine. The value specified in opt_refinement must match a Custom Search Engine Refinement label associated with the specified search engine (see the code snippet below).

var cseId = "017576662512468239146:omuauf_lfve";
var siteSearch = new GwebSearchgoogle.search.WebSearch();
siteSearch.setSiteRestriction(cseId, "Lectures");
                

Custom search engines often include a customized search results landing page. In order to support this, when Custom Search Engine site restrictions are in effect, an optional opt_moreResultsTemplate value may be supplied. This specifies a URL template that will be used to generate the "More results" link at the bottom of a set of search results. The URL template must include a placeholder of "__QUERY__" and "__HL__". When generating the "More results" link, the system will replace these placeholders with the current query term and UI language.

The latest addition to Custom Search Engines is the ability to use Linked Custom Search Engines. In order to support this, the site argument has been extended so that it supports all of the options and modes listed above, in addition to the new anonymous object mode of specifying a site restriction. When the site argument is an object, one of the following properties may be present (listed in priority order meaning that if you supply multiple properties, the first one that we test for, in the order listed below, wins):

  • siteUrl - The search is relative to the supplied url
  • cseId - The search is relative to the supplied custom search engine id (e.g., 000455696194071821846:reviews)
  • crefUrl - The search is relative to linked custom search engine pointed to by the supplied url.

When either cseId or crefUrl is specified, an optional Custom Search Engine Refinement may be supplied using the opt_refinement. Using this mechanism you are able to site restrict to a subset of your search engine. The value specified in opt_refinement must match a Custom Search Engine Refinement label associated with the specified search engine (see the code snippet below).

searcher = new google.search.WebSearch();
searcher.setSiteRestriction(
  {
    crefUrl : "http://www.google.com/cse/samples/vegetarian.xml"
  },
  "recipes");
                
  • site - supplies a site restriction setting in the form of a partial url (e.g., "www.amazon.com", "google.com", etc.), or a custom search engine id (e.g., "000455696194071821846:reviews", "000455696194071821846:shopping", etc.) Alternatively, this can contain an anonymous object as described above.
  • opt_refinement - when site refers to a Custom Search Engine, the value of this optional argument specifies a Custom Search Engine Refinement
  • opt_moreResultsTemplate - when site refers to a Custom Search Engine, the value of this optional argument specifies a URL template that will be used to construct the "More results" link that appears underneath a set of search results in the search control. The URL template must include a placeholder of "__QUERY__" and "__HL__". When generating the "More results" link, the system will replace these placeholders with the current query term and UI language.
  • returns - n/a

.setRestriction(type, opt_value)

This method is used to specify or clear a restriction on the set of results returned by this searcher. In order to establish a restriction, both type and opt_value must be supplied and valid. In order to clear a restriction, supply a valid value for type and either specify null for the value of opt_value, or do not supply this. This API currently supports the following restriction types:

  • GSearchgoogle.search.Search.RESTRICT_SAFESEARCH - When this is specified as the value of type, the web search results will be restricted to images based on the safesearch value. Valid optional values for this type are as follows:
    • GSearchgoogle.search.Search.SAFESEARCH_STRICT - apply strict filtering for both explicit text and explicit images (the default behavior)
    • GSearchgoogle.search.Search.SAFESEARCH_MODERATE - apply filtering for explicit images
    • GSearchgoogle.search.Search.SAFESEARCH_OFF - do not apply safe search filtering
    The following code snippet demonstrates how to turn safe search filtering off.
    var searcher = new google.search.WebSearch();
    searcher.setRestriction(google.search.Search.RESTRICT_SAFESEARCH,
                            google.search.Search.SAFESEARCH_OFF);
  • GSearchgoogle.search.Search.RESTRICT_EXTENDED_ARGS New Args! - When this is specified, the value is an object containing name value pairs where the name may be one of lr, gl, or filter and the value for each is the value associated with the cgi argument as documented below.

    For example, the following code seqence restricts a web searcher to German and turns off the duplicate content filter

    searcher = new google.search.WebSearch()
    searcher.setRestriction(google.search.Search.RESTRICT_EXTENDED_ARGS,
                            { "lr" : "lang_de", "filter" : "0"});

Result Objects

Result objects are produced using a JSON encoding of server search requests. As a result, we have chosen not to implement formal Javascript objects, and instead dynamically create these objects from their serialized form. While there is no formal implementation of the objects, they exist, and we document them as if there was a backing Javascript implementation. The impact of all this is minimal. All that it means is that there is no named constructor. For each result, it's as if the system called new Object() and then proceeded to set formal properties on that object. The results are documented below in terms of their properties.

For all objects, there are two common properties:

  • .GsearchResultClass - specifies the type of result.
  • .html - supplies the root of an html element that may be cloned and attached somewhere into the application's DOM hierarchy.

Result Styling

The .html property discussed above is built with CSS styling in mind. As a result, each piece of semantic information is enclosed in HTML markup with an appropriate set of class markers. This allows you to use this HTML in conjunction with your own custom CSS rules that style the HTML to meet your needs.

As you will see in the sections that follow, each search result is enclosed in a div element marked with a generic search result class of gs-result, as well as a result type specific class e.g., gs-webResult, gs-localResult, etc. This structure allows you to easily define generic CSS rules that are applied to all results, as well as type specific rules.

In addition to this structure, when a result is managed by the GSearchControlgoogle.search.SearchControl, each result is enclosed in a div element marked with a generic search control result class of gsc-result, as well as a result type specific class e.g., gsc-webResult, gsc-localResult, etc. Each section of results is further wrapped in a div element marked with a generic search control results class of gsc-results, as well as a result type specific class e.g., gsc-webResult, gsc-localResult, etc.

The net result of this structure is the following skeleton:

<!-- A collection of web search results in the search control -->
<div class="gsc-results gsc-webResult">

  <!-- A single web result in the search control -->
  <div class="gsc-result gsc-webResult">

    <!-- A single web result, full structure defined below -->
    <div class="gs-result gs-webResult"></div>
  </div>
  ...
</div>

<!-- Similar pattern for local, blog, etc. -->
<div class="gsc-results gsc-localResult"></div>
<div class="gsc-results gsc-blogResult"></div>
      

Result Object - Common Properties

Common Property Description

.GsearchResultClass

Indicates the "type" of result.

  • GwebSearchgoogle.search.WebSearch.RESULT_CLASS - indicates GwebResult

.html

Supplies the root of an html element that may be cloned and attached somewhere into the application's DOM hierarchy. We expect that this is the primary property that applications will be concerned with and that their typical interaction will involve cloning this node and attaching it into their DOM hierarchy. We expect that they will use css to control styling and to control which elements are displayed. For instance, we expect the following fragment to be common across all applications that wish to copy and paste search results delivered through the Google Search API.

// clone the .html node from the result
var node = result.html.cloneNode(true);

// attach the node into my dom
container.appendChild(node);

GwebResult

This object is produced by the GwebSearchgoogle.search.WebSearch object. It is available in that object's .results["] array.

This object is indicated by a .GsearchResultClass value of GwebSearchgoogle.search.WebSearch.RESULT_CLASS.

GwebResult - Properties

In addition to the common properties described above, the following object specific properties are available.

Property Description

.unescapedUrl

Supplies the raw URL of the result.

.url

Supplies an escaped version of the above URL.

.visibleUrl

Supplies a shortened version of the URL associated with the result. Typically displayed in green, stripped of a protocol and path.

.title

Supplies the title value of the result.

.titleNoFormatting

Supplies the title, but unlike .title, this property is stripped of html markup (e.g., <b>, <i>, etc.).

.content

Supplies a brief snippet of information from the page associated with the search result.

.cacheUrl

Supplies a url to Google's cached version of the page responsible for producing this result. This property may be null indicating that there is no cache, and it might be out of date in cases where the search result has been saved and in the mean time, the cache has gone stale. For best results, this property should not be persisted.

GwebResult CSS Structure

The following fragment of HTML illustrates the structure of a Web Search result's .html property. The purpose of this skeleton is to show you the major structural components so that you can alter the styling and display of a result. For instance, if you want to supress the "snippet", a CSS rule of #mycontrol .gs-webResult .gs-snippet { display : none; } would do the trick.

<div class="gs-result gs-webResult">

  <!-- Note, a.gs-title can have embedded HTML
  // so make sure to account for this in your rules.
  // For instance, to change the title color to red,
  // use a rule like this:
  // a.gs-title, a.gs-title * { color : red; }
  -->
  <div class="gs-title">
    <a class="gs-title"></a>
  </div>
  <div class="gs-snippet"></div>

  <!-- The default CSS rule has the -short URL visible and
   // the -long URL hidden.
   //
   // If you want to reverse this, use a rule like:
   // #mycontrol .gs-webResult .gs-visibleUrl-short { display:none; }
   // #mycontrol .gs-webResult .gs-visibleUrl-long { display:block; }
  -->
  <div class="gs-visibleUrl gs-visibleUrl-short"></div>
  <div class="gs-visibleUrl gs-visibleUrl-long"></div>
</div>
        

Flash and other Non-Javascript Environments

For Flash developers, and those developers that have a need to access the Search API from other Non-Javascript environments, the API exposes a simple RESTful interface. In all cases, the method supported is GET and the response format is a JSON encoded result set with embedded status codes. Applications that use this interface must abide by all existing terms of service. An area to pay special attention to relates to correctly identifying yourself in your requests. Applications MUST always include a valid and accurate http referer header in their requests.

Developers are also encouraged to make use of the userip parameter (see below) to supply the IP address of the end-user on whose behalf you are making the API request. Doing so will help distinguish this legitimate server-side traffic from traffic which doesn't come from an end-user.

Like the core Javascript interface, this interface is exposed through a uniform URL containing a mix of both standard and searcher specific CGI arguments. Your application can use an http stack of it's choosing. The only requirements are that you must be able to construct a properly constructed URL with all necessary CGI arguments, that you send an http referer header that accurately identifies your application, and that you are able to process the JSON encoded response.

Standard URL Base Address'

Each search endpoint is accessed through a standard URL. The following table lists the URL used to access each service.

Searcher Base Url
Web Search https://ajax.googleapis.com/ajax/services/search/web

Standard URL Arguments

Each request contains a mix of standard URL arguments and an optional set of searcher specific arguments. This section describes the standard arguments that are uniform across all searchers and that convey virtually identical semantic information to each searcher. In some cases, an argument is optional. This is indicated with a ? following the name of the argument. In all cases, the value of a CGI argument must be properly escaped (e.g., via the functional equivalent of Javascript's encodeURIComponent() method).

The following table lists the standard URL arguments. Additional sections appear below that highlight searcher specific arguments.

Argument Example Description
q q=Paris%20Hilton This argument supplies the query, or search expression, that is passed into the searcher.
v v=1.0 This argument supplies protocol version number. The only valid value at this point in time is 1.0.
userip? userip=192.168.0.1 This argument supplies the IP address of the end-user on whose behalf the request is being made. Requests that include it are less likely to be mistaken for abuse. In choosing to utilize this parameter, please be sure that you're in compliance with any local laws, including any laws relating to disclosure of personal information being sent.
rsz? rsz=4 This optional argument supplies the number of results that the application would like to recieve. Values can be any integer between 1 and 8. Alternately, a value of small indicates a small result set size or 4 results. A value of large indicates a large result set or 8 results. Finally, for filter Custom Search Engines, a value of filtered_cse will return 10 results. If this argument is not supplied, a value of small is assumed.
hl? hl=fr This optional argument supplies the host language of the application making the request. If this argument is not present then the system will choose a value based on the value of the Accept-Language http header. If this header is not present, a value of en is assumed.
start? start=4 This optional argument supplies the start index of the first search result. Each successful response contains a cursor object (see below) which includes an array of pages. The start property for a page may be used as a valid value for this argument. For reference, a sample cursor object is shown below:
"cursor": {
  "pages": [
    { "start": "0", "label": 1 },
    { "start": "4", "label": 2 },
    { "start": "8", "label": 3 },
    { "start": "12","label": 4 } ],
  "estimatedResultCount": "48758",
  "currentPageIndex": 0,
  "moreResultsUrl": "http://www.google.com/search..."
}
      
callback? callback=foo This optional argument alters the standard response format. When supplied, instead of producing a simple JSON encoded object, the system produces a Javascript function call response where the value of callback specifies the name of the function called in the response.
callbackFunction(
  {"responseData" : {
      "results" : [],
      "cursor" : {}
    },
    "responseDetails" : null | string-on-error,
    "responseStatus" : 200 | error-code
});
      
context? context=bar This optional argument is related to the context argument. When both are supplied, the value of context alters the normal response format associated with callback. The new format is:
callbackFunction(
  contextValue,    // the context arg value
  responseObject,  // the collection of results and cursor
  responseStatus,  // 200 on success, non-200 on failure
  errorDetails)    // error string for non-200 response
      

Standard Response Format

As discussed briefly in the previous section, there are two major variations in the response format. When the callback and context arguments are not supplied, the response format is a simple JSON object:

{
  "responseData" : {
    "results" : [],
    "cursor" : {}
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
}

In the JSON fragment above, note that the responseData property contains a results array and an optional cursor. These are identical both semantically and structurally to the results returned through the JavaScript Searchers layer. The responseStatus property contains a value of 200 on success and a non-200 http error status code on failure. If there is a failure, responseDetails contains a diagnostic string.

By using the callback argument, applications can easily request a JavaScript callback::

callback({
  "responseData" : {
    "results" : [],
    "cursor" : {}
  },
  "responseDetails" : null | string-on-error,
  "responseStatus" : 200 | error-code
});

If the application supplies both callback and context arguments, the response is encoded as a JavaScript procedure call. In this mode of operation, the value of callback becomes the procedure call target, the value of context is passes as the first argument, the value of responseData from above is passes as the second argument, the response status is passed as the third argument, and the final argument is either null or a diagnostic string.

foo('bar',{
 "results": [
  {
   "GsearchResultClass": "GwebSearch",
   "unescapedUrl": "http://en.wikipedia.org/wiki/Paris_Hilton",
   "url": "http://en.wikipedia.org/wiki/Paris_Hilton",
   "visibleUrl": "en.wikipedia.org",
   "cacheUrl": "http://www.google.com/search?q\u003dcache:TwrPfhd22hYJ:en.wikipedia.org",
   "title": "\u003cb\u003eParis Hilton\u003c/b\u003e - Wikipedia, the free encyclopedia",
   "titleNoFormatting": "Paris Hilton - Wikipedia, the free encyclopedia",
   "content": "In 2006, she released her debut album \u003cb\u003eParis\u003c/b\u003e..."
  },
  {
   "GsearchResultClass": "GwebSearch",
   "unescapedUrl": "http://www.imdb.com/name/nm0385296/",
   "url": "http://www.imdb.com/name/nm0385296/",
   "visibleUrl": "www.imdb.com",
   "cacheUrl": "http://www.google.com/search?q\u003dcache:1i34KkqnsooJ:www.imdb.com",
   "title": "\u003cb\u003eParis Hilton\u003c/b\u003e",
   "titleNoFormatting": "Paris Hilton",
   "content": "Self: Zoolander. Socialite \u003cb\u003eParis Hilton\u003c/b\u003e was..."
  },
  ...
 ],
 "cursor": {
  "pages": [
   { "start": "0", "label": 1 },
   { "start": "4", "label": 2 },
   { "start": "8", "label": 3 },
   { "start": "12","label": 4 }
  ],
  "estimatedResultCount": "59600000",
  "currentPageIndex": 0,
  "moreResultsUrl": "http://www.google.com/search?oe\u003dutf8..."
 }
}
, 200, null)

Web Search Specific Arguments

The Web Search system supports a number of optional arguments which are all listed below:

Argument Description
cx? This optional argument supplies the unique id for the Custom Search Engine that should be used for this request (e.g., cx=000455696194071821846:reviews).
cref? This optional argument supplies the url of a linked Custom Search Engine specification that should be used to satisfy this request (e.g., cref=http%3A%2F%2Fwww.google.com%2Fcse%2Fsamples%2Fvegetarian.xml).
safe? This optional argument supplies the search safety level which may be one of:
  • safe=active - enables the highest level of safe search filtering
  • safe=moderate - enables moderate safe search filtering (default)
  • safe=off - disables safe search filtering
lr? This optional argument allows the caller to restrict the search to documents written in a particular language (e.g., lr=lang_ja). This list contains the permissible set of values.
filter? New! This optional argument controls turning on or off the duplicate content filter:
  • filter=0 - Turns off the duplicate content filter
  • filter=1 - Turns on the duplicate content filter (default)
gl? New! This optional argument allows the caller to tailor the results to a specific country. The value should be a valid country code (e.g. uk, de, etc.). If this argument is not present, then the system will use a value based on the domain used to load the API (e.g. https://www.google.com/jsapi). If the API loader was not used, a value of "us" is assumed.

Searcher and Drawing Options

GsearcherOptionsgoogle.search.SearcherOptions

When adding a searcher to the search control, the GsearcherOptionsgoogle.search.SearcherOptions object may be specified. If it is, it supplies various options used to control certain aspects of the related searcher. This object is implemented mainly as a property bag which is only loosley connected to a certain class of searcher. Some of its properties apply uniformly to all searchers, while some apply only to specific types of searchers. It is up to the application to use this properly, setting the right options and using them in the proper way.

This object allows the caller to control the default expansion mode (i.e., how the search results are displayed in the searchers section upon search completion), where on the web page the search results are displayed, as well as a variety of searcher specific options. The fragment that follows demonstrates how to use the searcher options class to set searcher options.

// create a searcher options object
// set up for open expansion mode
// load a searcher with these options
var options = new GsearcherOptionsgoogle.search.SearcherOptions();
options.setExpandMode(GSearchControlgoogle.search.SearchControl.EXPAND_MODE_OPEN);
searchControl.addSearcher(new GwebSearchgoogle.search.WebSearch(), options);
        

Once a searcher options object has been used in an .addSearcher() call, changing its properties has an undefined effect. The intended use is to set up an options object, use it when adding a searcher, and then never touch it again.

GsearcherOptionsgoogle.search.SearcherOptions - Constructor

Constructor Description

GsearcherOptionsgoogle.search.SearcherOptions()

The constructor is used to create an instance of a searcher options object. This object provides various configuration settings used by the search control.

GsearcherOptionsgoogle.search.SearcherOptions - Methods

Method Description

.setExpandMode(expandMode)

This method is used to communicate to the searcher the desired expansion mode of results, upon search completion.

  • expandMode - supplies the expansion mode for the associated searcher results section. Valid values include:
    • GSearchControlgoogle.search.SearchControl.EXPAND_MODE_CLOSED - The results section is closed showing no results. Clicking on the twiddle allows the user to "open" the results section seeing all results returned for the current search.
    • GSearchControlgoogle.search.SearchControl.EXPAND_MODE_OPEN - The results section is open showing all results.
    • GSearchControlgoogle.search.SearchControl.EXPAND_MODE_PARTIAL - The results section is partially open showing a small fraction of the results. Typically this means that only a single result is displayed.
  • returns - n/a

.setRoot(element)

This method is used to instruct the search control to draw the search results for the associated searcher in the container element provided rather than in the default container allocated during the execution of the search controls' .draw() method.

  • element - Supplies an html container element, which is typically a div element, that the search control is to use as a container for the results for the associated searcher.
  • returns - n/a

.setVideoResultsTbHeight(height)

This method allows the caller to specify an alternate default scaling factor that is applied to video search results as they are displayed by the search control. Note, the height supplied has an impact on the resulting width of the video as well. The system maintains a 4x3 aspect ratio for videos so the resulting width of the video is height * 1.33. The result is an imageScaler object (see GSearchgoogle.search.Search.scaleImage). Using this function has an impact on the .gs-videoResult td div.gs-image-box CSS rule within gsearch.css, so make sure that if you are adjusting video sizes you make compatible changes to your over-ride of this rule.

  • height - supplies the maximum height, in pixels, that the video's thumbnail should be scaled to before rendering by the search control. A maximum value of 100px is enforced by the API.
  • returns - n/a

.setImageResultsTbHeight(height)

This method allows the caller to specify an alternate default scaling factor that is applied to image search results as they are displayed by the search control. Note, the height supplied has an impact on the resulting width of the image as well. The system maintains a 4x3 aspect ratio for images so the resulting width of the image is height * 1.33. The result is an imageScaler object (see GSearch.scaleImage). Using this function has an impact on the .gs-imageResult CSS rule (width property) as well as .gs-imageResult .gs-image-box CSS rule (height property). The default image dimensions are 112x84, hence the 114x86 CSS rules (2px larger to account for a 1px border). Make sure that if you are adjusting image sizes you make compatible changes to your over-ride of these rules.

  • height - supplies the maximum height, in pixels, that the images's thumbnail should be scaled to before rendering by the search control. A maximum value of 100px is enforced by the API.
  • returns - n/a

.setNoResultsString(str)

Normally, when a search produces no results, the search control slot for the searcher is left empty. This method allows the caller to specify a string that supplies a default "result". The system contains a value of GSearchControlgoogle.search.SearchControl.NO_RESULTS_DEFAULT_STRING which you can use. This is a localized string that means "No Results" in all supported locales.

  • str - supplies a string value that is used when a search yields no results..
  • returns - n/a

GdrawOptionsgoogle.search.DrawOptions

When asking a search control to draw, you must specify a container for the control to draw within. In addition to this required parameter, the search control's .draw() method also accepts an optional GdrawOptionsgoogle.search.DrawOptions object. This object allows applications to request linear or tabbed layout (with linear being the default). Additionally, this object allows the application to request that the "search form" (i.e., the input element, button, controls, etc.) associated with driving the search be decoupled from the set of search results. This is accomplished by using the .setSearchFormRoot() method and supplying a container of your own that should host the search form.

As a more advanced mode of the above, this object allows applications to request that the search control not create a search form at all and instead use an application supplied text input element. When this option is specified, the search control takes control of the input element, grabbing onkeyup and onpaste events. Over time the list of events that the control latches on to may change. By handing an input element to the search control, the application is simply claiming responsibility for placement of the element as well as styling. Once the input element has been handed to the control, the application should not interact with the element other than to read its value if needed.

The following fragment demonstrates how to use this object to request that the search control draw itself in "tabbed" mode.

// create a drawOptions object
var drawOptions = new GdrawOptionsgoogle.search.DrawOptions();
drawOptions.setDrawMode(GSearchControlgoogle.search.SearchControl.DRAW_MODE_TABBED);
searchControl.draw(element, drawOptions);
        

The following fragment demonstrates how to use this object to request that the search form be decoupled from the set of search results.

...
<div id="searchForm">Loading...</div>
...
var searchFormElement = document.getElementById("searchForm");
var drawOptions = new GdrawOptionsgoogle.search.DrawOptions();
drawOptions.setSearchFormRoot(searchFormElement);
searchControl.draw(element, drawOptions);
        

GdrawOptions - Constructor

Constructor Description

GdrawOptionsgoogle.search.DrawOptions()

The constructor is used to create an instance of a draw options object. This object provides various configuration settings used by the search control during its draw phase. Specifically, it provides control over tabbed vs. linear mode, as well as providing an application with a way to hand an input element off to the search control. The default setting for a newly constructed draw options object is linear mode with search control owned/created text input element.

GdrawOptionsgoogle.search.DrawOptions - Methods

Method Description

.setInput(inputElement)

This method is used to hand an input element off to the search control. Instead of creating its own text input element for capturing search queries, the control will use this application provided input element.

When this option is specified, the search control takes control of the input element, grabbing onkeyup and onpaste events. Over time the list of events that the control latches on to may change. By handing an input element to the search control, the application is simply claiming responsibility for placement of the element as well as styling. Once the input element has been handed to the control, the application should not interact with the element other than to read its value if needed.

  • inputElement - supplies an input element that should be used by the search control.
  • returns - n/a

.setDrawMode(drawMode)

This method is used to instruct the search control to draw the search results in either "tabbed" or "linear" mode.

  • drawMode - A value of GSearchControlgoogle.search.SearchControl.DRAW_MODE_LINEAR is used to specify linear drawing mode. A value of GSearchControlgoogle.search.SearchControl.DRAW_MODE_TABBED is used to specify tabbed drawing mode.
  • returns - n/a

.setSearchFormRoot(element)

This method is used to indicate that you would like the "search form" placed in the DOM container specified by "element" rather than in its default location near the search results.

  • element - supplies a container that the "search form" will be placed within.
  • returns - n/a

.setAutoComplete(enabled)

Indicate that you would like the key presses in the input box to trigger requests for auto completions on the query typed so far. Before completions will be available, you must configure the custom search engine at www.google.com/cse to enable autocompletions. This feature is currently only available for filter Custom Search Engines.

  • enabled - true to turn on requests for auto complete, false to disable the requests.
  • returns - n/a

GXXX - Properties

The following collection of public properties are exposed by this object. Unless otherwise stated, these properties are assumed to be read-only.

Property Description

.property

Description

.property

Description

.property

Description

.property

Description

GXXX

Description

GXXX - Constructor

Constructor Description

GXXX()

Description

GXXX - Methods

Method Description

.method()

description

  • arg - supplies a
  • returns - n/a

.method()

description

  • arg - supplies a
  • returns - n/a

.method()

description

  • arg - supplies a
  • returns - n/a

.method()

description

  • arg - supplies a
  • returns - n/a

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.