Google Web Search API (Deprecated)
Class Reference
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 the new Custom Search API.
The Google Search API is a JavaScript API implemented in the following classes.
Check to show old class name and namespace scheme (e.g. GwebSearch,etc.)
Table of Contents
- The Search Control
- GSearchControl google.search.SearchControl
- GSearchForm google.search.SearchForm
- google.search.CustomSearchControl
- Searchers
- GSearch google.search.Search
- GwebSearch google.search.WebSearch
- Searcher and Drawing Options
- GsearcherOptions google.search.SearchOptions
- GdrawOptions google.search.DrawOptions
- Result Objects
- GwebResult
- Result Styling
- GwebResult CSS Structure
- Flash and other Non-Javascript Environments
- Web Search Specific Arguments New Args!
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 |
|---|---|
|
Creates a new search control object. The search control object is a container for searchers, objects which implement the The expected order of operations is:
Once these steps have occurred, the search control is active and ready to begin performing searches. |
GSearchControlgoogle.search.SearchControl - Methods
| Method | Description |
|---|---|
|
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
|
|
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 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.
|
|
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
|
|
This method causes the search control to initiate a sequence of parallel searches across all of the searchers configured into the control. If the 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.
|
|
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
|
|
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.
|
|
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.
|
|
This method is used to clear all of the search results out of the search control.
|
|
This method is called to set the link target used for links embedded in search results. The default value is
|
|
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.
|
|
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.
|
|
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 - Static methods
| Static method | Description |
|---|---|
|
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.
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 |
|---|---|
|
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 The expected order of operations is:
Once these steps have occurred, the search form is active and ready to begin receiving and processing user input. The method accepts a required
|
GSearchFormgoogle.search.SearchForm - Methods
| Method | Description |
|---|---|
|
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.
|
|
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.
|
|
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
|
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 |
|---|---|
|
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 |
|
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 |
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 |
|---|---|
|
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., |
GSearchgoogle.search.Search - Methods
| Method | Description |
|---|---|
|
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.
|
|
This method returns the current result set size, the value established by the previous method.
|
|
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.
|
|
This method is called to begin a new search. The
|
|
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
|
|
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.
|
|
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
|
|
This method is called to set the link target used for links embedded in search results. The default value is
|
|
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.
|
|
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
|
|
This method allows the caller to either create or re-generate the
|
|
After a search completes, a
|
GSearchgoogle.search.Search - Static methods
| Static method | Description |
|---|---|
|
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 // 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
|
|
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 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.
|
|
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.,
|
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 |
|---|---|
|
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 |
|
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:
|
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 |
|---|---|
|
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 |
|---|---|
|
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 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 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 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 The latest addition to Custom Search Engines is the ability to use Linked Custom Search Engines. In order to support this, the
When either searcher = new google.search.WebSearch(); searcher.setSiteRestriction( { crefUrl : "http://www.google.com/cse/samples/vegetarian.xml" }, "recipes");
|
|
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
|
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 |
|---|---|
|
Indicates the "type" of result.
|
|
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 |
|---|---|
|
Supplies the raw URL of the result. |
|
Supplies an escaped version of the above URL. |
|
Supplies a shortened version of the URL associated with the result. Typically displayed in green, stripped of a protocol and path. |
|
Supplies the title value of the result. |
|
Supplies the title, but unlike |
|
Supplies a brief snippet of information from the page associated with the search result. |
|
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. In addition, we ask, but do not require, that each request contains a valid API Key. By providing a key, your application provides us with a secondary identification mechanism that is useful should we need to contact you in order to correct any problems. Read more about the usefulness of having an API key
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. |
| key? | key=your-key | This optional argument supplies the application's key. If specified, it must be a valid key associated with your site which is validated against the passed referer header. The advantage of supplying a key is so that we can identify and contact you should something go wrong with your application. Without a key, we will still take the same appropriate measures on our side, but we will not be able to contact you. It is definitely best for you to pass a key. |
| 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:
|
| 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:
|
| 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 |
|---|---|
|
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 |
|---|---|
|
This method is used to communicate to the searcher the desired expansion mode of results, upon search completion.
|
|
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'
|
|
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
|
|
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
|
|
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
|
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 |
|---|---|
|
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 |
|---|---|
|
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
|
|
This method is used to instruct the search control to draw the search results in either "tabbed" or "linear" mode.
|
|
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.
|
|
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.
|