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.

.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

.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

.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

.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

.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

.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

.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 AJAX 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 AJAX 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.

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

.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.

.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

.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.

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).

.setResultSetSize(indicator)

This method is called to select the number of results returned by this specific searcher. Note, this is not a scalar. It is an enumeration that indicates either a small number of results, or a large number of results. In the future, this method may be enhanced to support medium and extra large result sets.

• indicator - supplies an enumeration which indicates the desired number of search results to return. Valid values include:
  • 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

.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

.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

.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

.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(). Please visit our sample for more information.

• 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

.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

.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

.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 AJAX 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

.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.

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.

.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". A more complete sample is available at Site Restrictions Sample.

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. A more complete sample is available at Custom Search Engine Sample.

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). A more complete sample is available at Curriculum Search Sample.

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. This sample demonstrates the use of this mechanism for the main, left hand tab: Curriculum Search Sample.

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. See this sample for details.

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

GlocalSearchgoogle.search.LocalSearch()

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

.setCenterPoint(location)

This method establishes a center point that is used to scope search results. It accepts a single variant which may be a string, a GMap2google.maps.Map2, or a GLatLnggoogle.maps.LatLng. In the case of a string, an attempt is made to resolve the string into a GLatLnggoogle.maps.LatLng.

• location - supplies a center point designation used to scope local searches. this argument is a variant and may specify:
  • a GMap2google.maps.Map2 which is noted by the presence of a getCenter() property. When this is the case, the center point of the specified map is captured and then used to scope search results.
  • a GLatLnggoogle.maps.LatLng which is noted by the presence of an x property. When this is the case, the value of this point is captured and used as the center point to scope local searches.
  • a string which specifies an address by name. When this argument is presented, searches are scoped as if the user performed a Google Local Search specifying near location as part of their search expression. Note: The string location is resolved into a GLatLnggoogle.maps.LatLng asynchronously so if this method is used, searches are made relative to this location once the geocoding operation completes with success.
• 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_TYPE - When this is specified as the value of type, supplying an opt_value of:
  • GlocalSearchgoogle.search.LocalSearch.TYPE_BLENDED_RESULT - return a mix of both KML results and normal, local listings and geocodes.
  • GlocalSearchgoogle.search.LocalSearch.TYPE_KMLONLY_RESULTS - return only KML results and geocode results.
  • GlocalSearchgoogle.search.LocalSearch.TYPE_LOCALONLY_RESULTS - return only LOCAL listing results results and geocode results (note: this is the default behavior and is identical to the historical behavior of the API).

This method accepts the following arguments:

• type - supplies the type of restriction to establish:
  • GSearchgoogle.search.Search.RESTRICT_TYPE
• opt_value - supplies the value for the specified restriction type. If the value is null, then the specified restriction is cleared and the default behavior is restored. Otherwise, the value must be valid relative to the value of type and, if so, establishes a restriction. See above.

.resizeStaticMapUrl(result, height, width, opt_zoom?)

This utility function is designed to resize the image associated with the staticMapUrl property of the specified result. Upon completion, this property is replaced with a new value that represents the re-sized static map image. An optional zoom parameter may be passed allowing both the size and zoom level to be manipulated by this method. The default size of a static map image is 150px x 100px with a moderate zoom level of GlocalSearchgoogle.search.LocalSearch.STATIC_MAP_ZOOM_DEFAULT. The Static Map Tile sample demonstrates one way to use this method (see the snippet below).

var img = document.createElement("img");
google.search.LocalSearch.resizeStaticMapUrl(result, 80, 120);
img.src = result.staticMapUrl;
img.title = result.titleNoFormatting;
                

• result - supplies the result object whose static map image is to be re-sized. Upon completion, the staticMapUrl property of this result object is modified.
• height - supplies the height, in pixels, of the new image. Note, the default height is 100 pixels.
• width - supplies the width, in pixels, of the new image. Note, the default width is 150 pixels.
• opt_zoom - supplies an optional zoom level for the map. If no zoom level is specified, the value is unchanged, with the default value being GlocalSearchgoogle.search.LocalSearch.STATIC_MAP_ZOOM_DEFAULT. Valid values include GlocalSearchgoogle.search.LocalSearch.STATIC_MAP_ZOOM_CLOSEST to GlocalSearchgoogle.search.LocalSearch.STATIC_MAP_ZOOM_FARTHEST.
• returns - the new value of staticMapUrl is returned.

The ytchannel: predicate allows your application to perform a search and get only video results from the specified channel. For example, a search expression of ytchannel:BarackObamadotcomwill return a collection of videos from the BarackObamadotcom YouTube Channel. By providing an additional, optional expression right after the ytchannel directive, your application can search for the expression within the selected channel, e.g., ytchannel:BarackObamadotcom oil.

The ytfeed:most_viewed and ytfeed:recently_featured predicates are identical to ytfeed:top_rated. They differ in that they target different YouTube special feeds.

GvideoSearchgoogle.search.VideoSearch()

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

.setResultOrder(orderBy)

The default behavior of this searcher is to return results ordered by their relevance. In some cases, it is useful to see results ordered by date. This method may be used to change the result order.

• orderBy - supplies the desired result order:
  • GSearchgoogle.search.Search.ORDER_BY_RELEVANCE - This is the default and indicates that results should be returned in order of their relevance.
  • GSearchgoogle.search.Search.ORDER_BY_DATE - This value indicates that results should be returned in publication date order.
• returns - n/a

GblogSearchgoogle.search.BlogSearch()

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

.setSiteRestriction(site)

This method is used to restrict the set of blog search results returned by this searcher. To restrict results to all blog results on blogspot.com, simply call this method with a value of "blogspot.com". To restrict results to the Nintendo DS blog on Live Journal, simply call with "http://community.livejournal.com/nintendo_ds/". To clear site restrictions, pass in a value of null.

• site - supplies a site restriction setting e.g., "blogspot.com", "http://community.livejournal.com/nintendo_ds/", etc.
• returns - n/a

GnewsSearchgoogle.search.NewsSearch()

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

.setSiteRestriction(site)

This method is used to restrict the set of news search results returned by this searcher. To restrict results to all news results from the Seattle Times, simply call this method with a value of "Seattle Times". To restrict results to results from CNN, simply call with "CNN". The pattern is that the title of the news source is separated by either spaces or underscore (e.g., "_"). To clear site restrictions, pass in a value of null.

• site - supplies a site restriction setting e.g., "Seattle Times", "CNN", etc.
• returns - n/a

.setRestriction(type, value)

This method is used to restrict the set of news search results returned by this searcher above and beyond normal site restrictions. The first argument, type specifies the type of restriction desired, and then the value is type specific. A value of null, always clears the selected restriction.

• type - supplies the type of restriction. The only currently supported value is GSearchgoogle.search.Search.RESTRICT_EXTENDED_ARGS
• value - supplies the value for the restriction, or null to clear the restriction. With a type of GSearchgoogle.search.Search.RESTRICT_EXTENDED_ARGS, this argument specifies an object containing name value pairs where the name may be one of geo, qsid, topic, or ned and the value for each is the value associated with the cgi argument as documented in the below.

  For example, the following code seqence restricts a news searcher to the business topic in the German edition of Google News:

  searcher = new google.search.NewsSearch()
  searcher.setRestriction(google.search.Search.RESTRICT_EXTENDED_ARGS,
                          { "topic" : "b", "ned" : "de"});
                    

• returns - n/a

GbookSearchgoogle.search.BookSearch()

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

.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_TYPE - When this is specified as the value of type, supplying an opt_value of GbookSearchgoogle.search.BookSearch.TYPE_FULL_VIEW_BOOKS will restrict the results to only "Full View Books". Supplying a value of GbookSearchgoogle.search.BookSearch.TYPE_ALL_BOOKS allows the searcher to return all books. Note, this is the default and the behavior in effect when the GSearchgoogle.search.Search.RESTRICT_TYPE restriction is cleared.
• GSearchgoogle.search.BookSearch.USER_LIST - When this is specified as the value of type, the value of opt_value is used to specify a user's library. Queries will be restricted to only those books present in this library. Supplying a value of null clears this restriction, allowing searches to see all books in all libraries. Note, this is the default behavior.

• type - supplies the type of restriction to establish:
  • GSearchgoogle.search.Search.RESTRICT_TYPE
  • GSearchgoogle.search.BookSearch.USER_LIST
• opt_value - supplies the value for the specified restriction type. If the value is null, then the specified restriction is cleared. Otherwise, the value must be valid relative to the value of type and, if so, establishes a restriction. See above.

GimageSearchgoogle.search.ImageSearch()

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

.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 be 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 the opt_value argument.

This API currently supports the following restriction types:

• GSearchgoogle.search.Search.RESTRICT_SAFESEARCH - When this is specified as the value of type, the image 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
  • GSearchgoogle.search.Search.SAFESEARCH_MODERATE - apply filtering for explicit images (the default behavior)
  • 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.ImageSearch();
  searcher.setRestriction(google.search.Search.RESTRICT_SAFESEARCH,
                          google.search.Search.SAFESEARCH_OFF);
                  

• GimageSearchgoogle.search.ImageSearch.RESTRICT_IMAGESIZE - When this is specified as the value of type, the image search results will be restricted to images with certain pixel dimensions. Valid optional values for this type are as follows:
  • GimageSearchgoogle.search.ImageSearch.IMAGESIZE_SMALL - restrict to small images, icons
  • GimageSearchgoogle.search.ImageSearch.IMAGESIZE_MEDIUM - restrict to medium images
  • GimageSearchgoogle.search.ImageSearch.IMAGESIZE_LARGE - restrict to large images
  • GimageSearchgoogle.search.ImageSearch.IMAGESIZE_EXTRA_LARGE - restrict to extra large images
  The following code snippet demonstrates how to retrieve only icon sized images.

  var searcher = new google.search.ImageSearch();
  searcher.setRestriction(google.search.ImageSearch.RESTRICT_IMAGESIZE,
                          google.search.ImageSearch.IMAGESIZE_SMALL);
                  

• GimageSearchgoogle.search.ImageSearch.RESTRICT_COLORIZATION - When this is specified as the value of type, the image search results will be restricted to images with certain colorization. Valid optional values for this type are as follows:
  • GimageSearchgoogle.search.ImageSearch.COLORIZATION_GRAYSCALE - restrict to grayscale images
  • GimageSearchgoogle.search.ImageSearch.COLORIZATION_COLOR - restrict to color images
  The following code snippet demonstrates how to retrieve only grayscale images.

  var searcher = new google.search.ImageSearch();
  searcher.setRestriction(google.search.ImageSearch.RESTRICT_COLORIZATION,
                          google.search.ImageSearch.COLORIZATION_GRAYSCALE);
                  

• GimageSearchgoogle.search.ImageSearch.RESTRICT_COLORFILTER (experimental)^New! - When this is specified as the value of type, the image search results will be filtered based on the selected color. Valid optional values for this type are as follows:
  • GimageSearchgoogle.search.ImageSearch.COLOR_BLACK
  • GimageSearchgoogle.search.ImageSearch.COLOR_BLUE
  • GimageSearchgoogle.search.ImageSearch.COLOR_BROWN
  • GimageSearchgoogle.search.ImageSearch.COLOR_GRAY
  • GimageSearchgoogle.search.ImageSearch.COLOR_GREEN
  • GimageSearchgoogle.search.ImageSearch.COLOR_ORANGE
  • GimageSearchgoogle.search.ImageSearch.COLOR_PINK
  • GimageSearchgoogle.search.ImageSearch.COLOR_PURPLE
  • GimageSearchgoogle.search.ImageSearch.COLOR_RED
  • GimageSearchgoogle.search.ImageSearch.COLOR_TEAL
  • GimageSearchgoogle.search.ImageSearch.COLOR_WHITE
  • GimageSearchgoogle.search.ImageSearch.COLOR_YELLOW
  The following code snippet demonstrates how to filter on the color red.

  var searcher = new google.search.ImageSearch();
  searcher.setRestriction(google.search.ImageSearch.RESTRICT_COLORFILTER,
                          google.search.ImageSearch.COLOR_RED);
                  

• GimageSearchgoogle.search.ImageSearch.RESTRICT_FILETYPE - When this is specified as the value of type, the image search results will be restricted to images only of a certain filetype, e.g. JPG. Valid optional values for this type are as follows:
  • GimageSearchgoogle.search.ImageSearch.FILETYPE_JPG - restrict to only jpeg images
  • GimageSearchgoogle.search.ImageSearch.FILETYPE_PNG - restrict to only png images
  • GimageSearchgoogle.search.ImageSearch.FILETYPE_GIF - restrict to only gif images
  • GimageSearchgoogle.search.ImageSearch.FILETYPE_BMP - restrict to only bmp images
  The following code snippet demonstrates how to retrieve only images of type PNG.

  var searcher = new google.search.ImageSearch();
  searcher.setRestriction(google.search.ImageSearch.RESTRICT_FILETYPE,
                          google.search.ImageSearch.FILETYPE_PNG);
                  

• GimageSearchgoogle.search.ImageSearch.RESTRICT_IMAGETYPE (experimental) - When this is specified as the value of type, the image search results will be restricted to images of certain types. Valid optional values for this type are as follows:
  • GimageSearchgoogle.search.ImageSearch.IMAGETYPE_FACES - restrict to images with faces in them
  • GimageSearchgoogle.search.ImageSearch.IMAGETYPE_PHOTO - restrict to photos
  • GimageSearchgoogle.search.ImageSearch.IMAGETYPE_CLIPART - restrict to clipart images
  • GimageSearchgoogle.search.ImageSearch.IMAGETYPE_LINEART - restrict to images of line drawings
  The following code snippet demonstrates how to retrieve face images.

  var searcher = new google.search.ImageSearch();
  searcher.setRestriction(google.search.ImageSearch.RESTRICT_IMAGETYPE,
                          google.search.ImageSearch.IMAGETYPE_FACES);
                  

var searcher = new google.search.ImageSearch();
searcher.setRestriction(google.search.ImageSearch.RESTRICT_IMAGETYPE,
                        google.search.ImageSearch.IMAGETYPE_FACES);
searcher.setRestriction(google.search.ImageSearch.RESTRICT_FILETYPE,
                        google.search.ImageSearch.FILETYPE_JPG);
searcher.setRestriction(google.search.ImageSearch.RESTRICT_COLORIZATION,
                        google.search.ImageSearch.COLORIZATION_GRAYSCALE);
searcher.execute('Carmen Electra');
                

GpatentSearchgoogle.search.PatentSearch()

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

.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_TYPE - When this is specified as the value of type, supplying an opt_value of GpatentSearchgoogle.search.PatentSearch.TYPE_ISSUED_PATENTS will restrict the results to only patents that have been issued. Supplying a value of GpatentSearchgoogle.search.PatentSearch.TYPE_APPLICATIONS allows the searcher to return filed, but not yet issued patents. And finally, supplying a value of GpatentSearchgoogle.search.PatentSearch.TYPE_ANY_STATUS allows the searcher a mix of issued and filed patents. Note, this is the default and the behavior in effect when the GSearchgoogle.search.Search.RESTRICT_TYPE restriction is cleared.

• type - supplies the type of restriction to establish:
  • GSearchgoogle.search.Search.RESTRICT_TYPE
• opt_value - supplies the value for the specified restriction type. If the value is null, then the specified restriction is cleared. Otherwise, the value must be valid relative to the value of type and, if so, establishes a restriction. See above.

.GsearchResultClass

Indicates the "type" of result.

• GwebSearchgoogle.search.WebSearch.RESULT_CLASS - indicates GwebResult
• GlocalSearchgoogle.search.LocalSearch.RESULT_CLASS - indicates GlocalResult
• GvideoSearchgoogle.search.VideoSearch.RESULT_CLASS - indicates GvideoResult
• GblogSearchgoogle.search.BlogSearch.RESULT_CLASS - indicates GblogResult
• GnewsSearchgoogle.search.NewsSearch.RESULT_CLASS - indicates GnewsResult
• GbookSearchgoogle.search.BookSearch.RESULT_CLASS - indicates GbookResult
• GimageSearchgoogle.search.ImageSearch.RESULT_CLASS - indicates GimageResult
• GpatentSearchgoogle.search.PatentSearch.RESULT_CLASS - indicates GpatentResult

.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 AJAX Search API.

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

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

.unescapedUrl

Supplies the raw URL of the result.

.visibleUrl

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

.titleNoFormatting

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

.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.

.title

Supplies the title for the result. In some cases, the title and the streetAddress are the same. This typically occurs when the search term is a street address such as 1231 Lisa Lane, Los Altos, CA.

.url

Supplies a url to a Google Maps Details page associated with the search result.

.lng

Supplies the longitude value of the result. This may be used to construct a GPoint using the following code snippet:
p = new GPoint(parseFloat(result.lng), parseFloat(result.lat));

.city

Supplies the city name for the result. Note: In some cases, this property may be set to "".

.country

Supplies a country name for the result. Note: In some cases, this property may be set to "".

.addressLines[]

Supplies an array consisting of the mailing address lines for this result, for instance: ["1600 Amphitheatre Pky", "Mountain View, CA 94043"] or ["Via del Corso, 330", "00186 Roma (RM), Italy"]. To correctly render an address associated with a result, either use the .html property of the result directly or iterate through this array and display each addressLine in turn.

.ddUrlToHere

Supplies a url that can be used to provide driving directions from a user specified location to this search result. Note, in some cases this property may be missing or null. Always wrap access within a a test of if (result.ddUrlToHere && result.ddUrlToHere != null).

.staticMapUrl

Supplies a url to a static map image representation of the current result. The image is 150px wide by 100px tall with a single marker representing the current location. Expected usage is to hyperlink this image using the url property. The image may be resized using GlocalSearchgoogle.search.LocalSearch.resizeStaticMapUrl(). The Static Map Tile sample demonstrates one way to use this property.

.content

For "kml" results, this property contains a content snippet associated with the KML result. For "local" results, this property is the empty string.

.title

Supplies the title of the video result.

.content

Supplies a snippet style description of the video clip.

.published

Supplies the published date of the video (rfc-822 format).

.duration

The approximate duration, in seconds, of the video.

.tbHeight

Supplies the height, in pixels, of the video thumbnail.

.playUrl

If present, supplies the url of the flash version of the video that can be played inline on your page. To play this video simply create an <embed> element on your page using this value as the src attribute and using application/x-shockwave-flash as the type attribute. If you want the video to play right away, make sure to append &autoPlay=true to the url.

.viewCount

If present, this property supplies a count of the number of plays for this video.

.title

Supplies the title of the blog post returned as a search result.

.postUrl

Supplies the URL to the blog post referenced in this search result.

.author

Supplies the name of the author that wrote the blog post.

.publishedDate

Supplies the published date (rfc-822 format) of the blog post referenced by this search result.

.title

Supplies the title of the news story returned as a search result.

.unescapedUrl

Supplies the raw URL of the result.

.clusterUrl

When a news result has a set of related stories, this URL is available and non-null. In this situation, the URL points to a landing page that points to all of the related stories.

.publisher

Supplies the name of the publisher of the news story.

.publishedDate

Supplies the published date (rfc-822 format) of the news story referenced by this search result.

.image{}

This property is optional. It only appears in a result when the system has determined that there is a good image that represents the cluster of news articles related to this result. It's important to note the the image relates to the cluster of news articles, not just the article that acts as the primary article for this result. Given this, it's very important for your related user interface to not mis-represent the image. You must always display the news source of the article, and the news source of the image as they are often different. You will notice that on Google News, the image is displayed off to the side with full attribution to the source, and that it's hyper-linked to the article associated with the image, not the article associated with the current result.

This property is optional. It does not always exist. It's best to check for .image == undefined before interacting with the property. When the property is present, it contains the following sub-properties:

• .title - supplies the title of the article associated with the image.
• .titleNoFormatting - same as above but stripped of HTML formatting.
• .url - supplies the URL of this image as it is found in the article.
• .originalContextUrl - supplies the URL of the article that contains this image. The image, when displayed, should normally link through this URL.
• .publisher - supplies the publisher of the news article containing the image. The suggested user interface is to display this under or in close proximity to the image, hyper linked through the .url property from above.
• .tbUrl - supplies the URL of a thumbnail of the image.
• .tbWidth - supplies the width of the image referenced above. The standard size of this image is 80 pixels wide and 50 pixels tall.
• .tbHeight - supplies the height of the image referenced above. The standard size of this image is 80 pixels wide and 50 pixels tall.

.GsearchResultClass

A value of GnewsSearch.quote indicates that this result contains quote related properties, not standard news result properties. The property set for these two result formats are very different, so it's advised that you pay close attention to this property whenever mixing standard and quote based news queries.

.url

Supplies an escaped version of the above URL.

.content

Supplies a snippet of content from the news story that includes the quotes.

.title

Supplies the title of the book.

.unescapedUrl

Supplies the raw URL of the result.

.authors

Supplies the list of authors of the book.

.publishedYear

Supplies the year that the book was published.

.thumbnailHtml

Supplies an html dom node that represents a thumbnail image of the book's cover. Note, if you want to use this property correctly, you must clone node it (e.g., var cover = res.thumbnailHtml.cloneNode(true);). Also, note that if you have supressed HTML generation (using .setNoHtmlGeneration()), this property is not available.

.title

Supplies the title of the image, which is usually the base filename.

.unescapedUrl

Supplies the raw URL of the image.

.visibleUrl

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

.width

Supplies the width of the image in pixels.

.tbWidth

Supplies the width, in pixels, of the image thumbnail.

.tbUrl

Supplies the url of a thumbnail image.

.contentNoFormatting

Supplies the same information as .content, only stripped of HTML formatting.

.title

Supplies the title of the patent result.

.content

Supplies a snippet style description of the patent.

.url

Supplies an escaped version of the above URL.

.patentNumber

Supplies the patent number for issued patents, and the application number for filed, but not yet issued patents.

.assignee

Supplies the assignee of the patent.

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

• safe=active - enables the highest level of safe search filtering
• safe=moderate - enables moderate safe search filtering (default)
• safe=off - disables safe search filtering

• filter=0 - Turns off the duplicate content filter
• filter=1 - Turns on the duplicate content filter (default)

• blended - request KML, Local Business Listings, and Geocode results
• kmlonly - request KML and Geocode results
• localonly - request Local Business Listings and Geocode results

• us - specifies the US edition
• uk - specifies the UK edition
• fr_ca - specifies the French Canadian edition
• etc.

• safe=active - enables the highest level of safe search filtering
• safe=moderate - enables moderate safe search filtering (default)
• safe=off - disables safe search filtering

• imgc=gray - restrict to grayscale images
• imgc=color - restrict to color images

• imgcolor=black
• imgcolor=blue
• imgcolor=brown
• imgcolor=gray
• imgcolor=green
• imgcolor=orange
• imgcolor=pink
• imgcolor=purple
• imgcolor=red
• imgcolor=teal
• imgcolor=white
• imgcolor=yellow

• imgtype=face - restrict to images of faces
• imgtype=photo - restrict to photos
• imgtype=clipart - restrict to clipart images
• imgtype=lineart - restrict to images of line drawings

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.

.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

.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

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.

.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

.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.

View example (searchformroot.html)

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