English ▼ | Sign out 
Google AJAX Search API
Google Custom Search Control Documentation
Class Reference
The Google AJAX Search API is a JavaScript API implemented in the following classes.
Check to show old class name and namespace scheme (e.g. GwebSearch, GlocalSearch, etc.)
Table of Contents
- The Search Control
- GSearchControlgoogle.search.SearchControl
- GSearchForm google.search.SearchForm
- google.search.CustomSearchControlNew!
- google.maps.LocalSearch
- GSmapSearchControl
- GSvideoBar
- GSnewsBar
- GSvideoSearchControl
- GSbookBar (experimental)
- GSblogBar
- Searchers
- GSearchgoogle.search.Search
- GwebSearchgoogle.search.WebSearchNew Args!
- GlocalSearchgoogle.search.LocalSearch
- GvideoSearchgoogle.search.VideoSearch
- GblogSearchgoogle.search.BlogSearch
- GnewsSearchgoogle.search.NewsSearch
- GbookSearchgoogle.search.BookSearch (experimental)
- GimageSearchgoogle.search.ImageSearchNew Args!
- GpatentSearchgoogle.search.PatentSearch
- Result Objects
- GwebResult
- GlocalResult
- GvideoResult
- GblogResult
- GnewsResult
- GbookResult (experimental)
- GimageResult
- GpatentResult
- Result Styling
- GwebResult CSS Structure
- GlocalResult CSS Structure
- GvideoResult CSS Structure
- GblogResult CSS Structure
- GnewsResult CSS Structure
- GbookResult CSS Structure (experimental)
- GimageResult CSS Structure
- GpatentResult CSS Structure
- Flash and other Non-Javascript Environments
- Web Search Specific ArgumentsNew Args!
- Local Search Specific Arguments
- Video Search Specific Arguments
- Blog Search Specific Arguments
- News Search Specific Arguments
- Book Search Specific Arguments (experimental)
- Image Search Specific ArgumentsNew Args!
- Patent Search Specific Arguments
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. 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. 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 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.
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) { 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) { 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 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.
|
| | 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.
|
| | For some classes of searchers (e.g., GlocalSearchgoogle.search.LocalSearch()), there is a requirement that attribution be displayed alongside the set of search results. When using the search control, this is included in the search control logic "for free". If you are using a raw searcher, caputuring and presenting proper attribution is up to you. This method is designed to provide you with an attribution node (or null if no attribution is required) which you can then display appropriately. The display of attribution is only required while actively displaying a set of search results immediately after a search. The following snippet demonstrates a simple use of this API. var attribution = GlocalSearchgoogle.search.LocalSearch.getAttribution();
|
| | 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 When building the thumbnail // scale the thumbnail image using the searcher's .imageScaler.
|
| | 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(); 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(); When used in this manner, an optional Custom Search Engine Refinement may be supplied using the var cseId = "017576662512468239146:omuauf_lfve"; 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();
|
| | 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
|
GlocalSearchgoogle.search.LocalSearch
This object implements the GSearchgoogle.search.Search interface over the Google Local Search service. Upon completion of a search it delivers a collection of GlocalResult objects.
This object is designed to produce search results relative to a geographic region. The object provides an API that allows applications to scope this geographic region by supplying a location string (city/state, a zipcode, an address), or by providing a GLatLnggoogle.maps.LatLng() object (see Google Maps), or by providing a GMap2google.maps.Map2() object (see Google Maps). The preferred interface is either a GLatLnggoogle.maps.LatLng() or a GMap2google.maps.Map2(). You may have noticed in the samples the presence of a "set location" control in the stack of local search results. This UI is implemented through coordination between the search control, and this object. The map projected through the search control scopes all search results, and its initial value (center point) is established by programming this object. The search control does not maintain preferences on center point. This is the responsibility of the application using this API.
Note: If no location is specified, this object scopes search results to the San Francisco, CA area. A more elaborate default is certainly being considered, something that takes into account the geographic region of the user.
GlocalSearchgoogle.search.LocalSearch - Constructor
| Constructor | Description |
|---|---|
| | The constructor is used to create an instance of a searcher object designed to provide search results from the Google Local Search service. |
GlocalSearchgoogle.search.LocalSearch - Methods
| Method | Description |
|---|---|
| | This method establishes a center point that is used to scope search results. It accepts a single variant which may be a string, a
|
| | The default behavior of this searcher is to co-mingle address lookup results (e.g., NY, NY) with local search results. There are situations where this co-mingled approach is not the desired behavior. For instance, suppose the searcher is centered in Santa Barbara, CA and the user is searching for "Cava". With co-mingled results, the first search result is actually an address match against "Cava Close, Aberdeen City, AB15 UK". The second result is "Cava Restaurant & Bar". Using this method, applications are able to disable and enable address lookup producing either strictly search results, or address lookup results co-mingled with search results. In this case, if address lookup is disabled, the first result would be "Cava Restaurant & Bar".
|
| | 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 This API currently supports the following restriction types:
This method accepts the following arguments:
|
GlocalSearchgoogle.search.LocalSearch - Static Methods
| Static Method | Description |
|---|---|
| | This utility function is designed to resize the image associated with the var img = document.createElement("img");
|
| | This utility function is designed to create a static map image from the caller supplied collection of points. The points may be in the form of a collection of search result objects, a collection of objects containing a numeric // demonstrate computeStaticMapUrl with simple point array
|
GvideoSearchgoogle.search.VideoSearch
This object implements the GSearchgoogle.search.Search interface over the Google Video Search service. Upon completion of a search it delivers a collection of GvideoResult objects.
It is important to note that this searcher is designed to access both YouTube and Google Video. For the most part, the differences in the result format and player are minimal. In some cases, applications, through specialized query predicates, can directly access YouTube Channels and Special Feeds. The following YouTube only query predicates are supported
YouTube Query Predicates
| Predicate | Description |
|---|---|
ytchannel:name-of-channel expression? | The |
ytfeed:top_rated[.this_week | .this_month | .all_time] | The |
ytfeed:{most_viewed, recently_featured}[this_week | .this_month | .all_time] | The |
GvideoSearchgoogle.search.VideoSearch - 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. |
GvideoSearchgoogle.search.VideoSearch - Methods
| Method | Description |
|---|---|
| | 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.
|
GblogSearchgoogle.search.BlogSearch
This object implements the GSearchgoogle.search.Search interface over the Google Blog Search service. Upon completion of a search, it delivers a collection of GblogResultgoogle.search.BlogResult objects.
GblogSearchgoogle.search.BlogSearch - Constructor
| Constructor | Description |
|---|---|
| | The constructor is used to create an instance of a searcher object designed to provide search results from the Google Blog Search service. |
GblogSearchgoogle.search.BlogSearch - Methods
| Method | Description |
|---|---|
| | 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
|
| | 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.
|
GnewsSearchgoogle.search.NewsSearch
This object implements the GSearchgoogle.search.Search interface over the Google News service. Upon completion of a search it delivers a collection of GnewsSearchgoogle.search.NewsResult objects.
GnewsSearchgoogle.search.NewsSearch - Constructor
| Constructor | Description |
|---|---|
| | The constructor is used to create an instance of a searcher object designed to provide search results from the Google News service. |
GnewsSearchgoogle.search.NewsSearch - Methods
| Method | Description |
|---|---|
| | 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
|
| | 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.
|
| | 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,
|
GbookSearchgoogle.search.BookSearch (experimental)
This object implements the GSearchgoogle.search.Search interface over the Google Book Search service. Upon completion of a search it delivers a collection of GbookResult objects.
GbookSearchgoogle.search.BookSearch - Constructor
| Constructor | Description |
|---|---|
| | The constructor is used to create an instance of a searcher object designed to provide search results from the Google Book Search service. |
GbookSearchgoogle.search.BookSearch - Methods
| Method | Description |
|---|---|
| | 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 This API currently supports the following restriction types:
|
GimageSearchgoogle.search.ImageSearch
This object implements the GSearchgoogle.search.Search interface over the Google Image Search service. Upon completion of a search it delivers a collection of GimageSearchgoogle.search.ImageSearch objects. Note: Results can be restricted to the LIFE photo archive by including source:life as part of the query (experimental).
GimageSearchgoogle.search.ImageSearch - Constructor
| Constructor | Description |
|---|---|
| | The constructor is used to create an instance of a searcher object designed to provide search results from the Google Image Search service. |
GimageSearchgoogle.search.ImageSearch - Methods
| Method | Description |
|---|---|
| | 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
This API currently supports the following restriction types:
var searcher = new google.search.ImageSearch(); |
| | This method is used to restrict the set of image search results returned by this searcher. To restrict to www.photobucket.com, simply call this method passing in a value of "www.photobucket.com". To clear site restrictions, pass in a value of var siteSearch = new GimageSearchgoogle.search.ImageSearch(); |
GpatentSearchgoogle.search.PatentSearch
This object implements the GSearchgoogle.search.Search interface over the Google Patent Search service. Upon completion of a search it delivers a collection of GpatentResultgoogle.search.PatentResult objects.
GpatentSearchgoogle.search.PatentSearch - Constructor
| Constructor | Description |
|---|---|
| | The constructor is used to create an instance of a searcher object designed to provide search results from the Google Patent Search service. |
GpatentSearchgoogle.search.PatentSearch - Methods
| Method | Description |
|---|---|
| | 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 This API currently supports the following restriction types:
|
| | 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.
|
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:
class="gsc-results gsc-webResult">
class="gsc-result gsc-webResult">
class="gs-result gs-webResult">
...
class="gsc-results gsc-localResult">class="gsc-results gsc-blogResult">
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 AJAX Search API. // clone the .html node from the result |
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.
class="gs-result gs-webResult">
class="gs-snippet">
class="gs-visibleUrl gs-visibleUrl-short">
class="gs-visibleUrl gs-visibleUrl-long">
GlocalResult
This object is produced by the GlocalSearchgoogle.search.LocalSearch object. It is available in that object's .results[] array.
This object is indicated by a .GsearchResultClass value of GlocalSearchgoogle.search.LocalSearch.RESULT_CLASS.
GlocalResult - Properties
In addition to the common properties described above, the following object specific properties are available.
| Property | Description |
|---|---|
| | 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. |
| | Supplies the title, but unlike |
| | Supplies a url to a Google Maps Details page associated with the search result. |
| | Supplies the latitude value of the result. This may be used to construct a |
| | Supplies the longitude value of the result. This may be used to construct a |
| | Supplies the street address and number for the given result. Note: In some cases, this property may be set to "" if the result has no known street address. |
| | Supplies the city name for the result. Note: In some cases, this property may be set to "". |
| | Supplies a region name for the result (e.g., in the U.S., this is typically a state abbreviation, in other regions it might be a province, etc.) Note: In some cases, this property may be set to "". |
| | Supplies a country name for the result. Note: In some cases, this property may be set to "". |
| | Supplies an array of phone number objects where each object contains a |
| | Supplies an array consisting of the mailing address lines for this result, for instance: |
| | Supplies a url that can be used to provide driving directions from the center of the set of search results to this search result. Note, in some cases this property may be missing or null. Always wrap access within a a test of |
| | 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 |
| | Supplies a url that can be used to provide driving directions from this search result to a user specified location. Note, in some cases this property may be missing or null. Always wrap access within a a test of |
| | 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 |
| | This property indicates the type of this result which can either be |
| | For "kml" results, this property contains a content snippet associated with the KML result. For "local" results, this property is the empty string. |
GlocalResult CSS Structure
The following fragment of HTML illustrates the structure of a Local 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 "address", a CSS rule of #mycontrol .gs-localResult .gs-address { display : none; } would do the trick.
class="gs-result gs-localResult">
class="gs-snippet">
class="gs-address">
class="gs-street">
class="gs-city">
class="gs-region">
class="gs-country">
class="gs-phone">
class="gs-directions-to-from">
class="gs-label">
class="gs-spacer">
GvideoResult
This object is produced by the GvideoSearchgoogle.search.VideoSearch object. It is available in that object's .results[] array.
This object is indicated by a .GsearchResultClass value of GvideoSearchgoogle.search.VideoSearch.RESULT_CLASS.
GvideoResult - Properties
In addition to the common properties described above, the following object specific properties are available.
| Property | Description |
|---|---|
| | Supplies the title of the video result. |
| | Supplies the title, but unlike |
| | Supplies a snippet style description of the video clip. |
| | Supplies the url of a playable version of the video result. |
| | Supplies the published date of the video (rfc-822 format). |
| | Supplies the name of the video's publisher, typically displayed in green below the video thumbnail, similar to the treatment used for visibleUrl in the other search result objects. |
| | The approximate duration, in seconds, of the video. |
| | Supplies the width, in pixels, of the video thumbnail. |
| | Supplies the height, in pixels, of the video thumbnail. |
| | Supplies the url of a thumbnail image which visually represents the video. |
| | 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 |
| | If present, this property supplies the YouTube user name of the author of the video. |
| | If present, this property supplies a count of the number of plays for this video. |
| | If present, this property supplies the rating of the video on a scale of 1 to 5. |
GvideoResult CSS Structure
The following fragment of HTML illustrates the structure of a Video 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-videoResult .gs-snippet { display : none; } would do the trick.
class="gs-result gs-videoResult">
class="gs-image-box">
class="gs-text-box">
class="gs-text-box">
class="gs-snippet">
class="gs-publishedDate">
GblogResult
This object is produced by the GblogSearchgoogle.search.BlogSearch object. It is available in that object's .results[] array.
This object is indicated by a .GsearchResultClass value of GblogSearchgoogle.search.BlogSearch.RESULT_CLASS.
GblogResult - Properties
In addition to the common properties described above, the following object specific properties are available.
| Property | Description |
|---|---|
| | Supplies the title of the blog post returned as a search result. |
| | Supplies the title, but unlike |
| | Supplies the URL to the blog post referenced in this search result. |
| | Supplies a snippet of content from the blog post associated with this search result. |
| | Supplies the name of the author that wrote the blog post. |
| | Supplies the URL of the blog which contains the post. Typically, this URL is displayed in green, beneath the blog search result and is linked to the blog. |
| | Supplies the published date (rfc-822 format) of the blog post referenced by this search result. |
GblogResult CSS Structure
The following fragment of HTML illustrates the structure of a Blog 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-blogResult .gs-snippet { display : none; } would do the trick.
class="gs-result gs-blogResult">
class="gs-publishedDate">
class="gs-relativePublishedDate">
class="gs-snippet">
GnewsResult
This object is produced by the GnewsSearchgoogle.search.NewsSearch object. It is available in that object's .results[] array.
This object is indicated by a .GsearchResultClass value of GnewsSearchgoogle.search.NewsSearch.RESULT_CLASS.
GnewsResult - Properties
In addition to the common properties described above, the following object specific properties are available.
| Property | Description |
|---|---|
| | Supplies the title of the news story returned as a search result. |
| | Supplies the title, but unlike |
| | Supplies the raw URL of the result. |
| | Supplies an escaped version of the above URL. |
| | 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. |
| | Supplies a snippet of content from the news story associated with this search result. |
| | Supplies the name of the publisher of the news story. |
| | Contains the location of the news story. This is a list of locations in most specific to least specific order where the components are separated by ",". Note, there may only be one element in the list. A typical value for this property is "Edinburgh,Scotland,UK" or possibly "USA". |
| | Supplies the published date (rfc-822 format) of the news story referenced by this search result. |
| | This property is optional. It only appears in a result when the story also has a set of closely related stories. In this case, the
|
| | 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
|
| | This property is optional. When present, it indicates the language of the news story. |
GnewsResult (all quotes) - Properties
When your news search request makes use of the qsid argument to request quotes. The standard result format is altered to include quotes specific properties. In addition to the common properties described above, the following object specific properties are available.
| Property | Description |
|---|---|
| | A value of |
| | Supplies the raw URL of the result. |
| | Supplies an escaped version of the above URL. |
| | Supplies the name of the person that the quote is attributed to. |
| | Supplies a snippet of content from the news story that includes the quotes. |
| | Supplies the name of the publisher of the news story. |
GnewsResult CSS Structure
The following fragment of HTML illustrates the structure of a News 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-newsResult .gs-snippet { display : none; } would do the trick.
class="gs-result gs-newsResult">
class="gs-publisher">
class="gs-publishedDate">
class="gs-relativePublishedDate">
class="gs-snippet">
GbookResult (experimental)
This object is produced by the GbookSearchgoogle.search.BookSearch object. It is available in that object's .results[] array.
This object is indicated by a .GsearchResultClass value of GbookSearchgoogle.search.BookSearch.RESULT_CLASS.
GbookResult - Properties
In addition to the common properties described above, the following object specific properties are available.
| Property | Description |
|---|---|
| | Supplies the title of the book. |
| | Supplies the title, but unlike |
| | Supplies the raw URL of the result. |
| | Supplies an escaped version of the above URL. |
| | Supplies the list of authors of the book. |
| | Supplies the identifier associated with the book. This is typically an ISBN. |
| | Supplies the year that the book was published. |
| | Supplies the number of pages contained within the book. |
| | 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 |
GbookResult CSS Structure
The following fragment of HTML illustrates the structure of a Book 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 style the "page count" as bold, a CSS rule of #mycontrol .gs-bookResult .gs-pageCount { font-weight : bold; } would do the trick.
class="gs-result gs-bookResult">
class="gs-image-box">
class="gs-image-box gs-book-image-box">
class="gs-row1">
class="gs-pages">
class="gs-page-edge">
class="gs-text-box">
class="gs-text-box">
class="gs-author">
class="gs-publishedDate">
class="gs-pageCount">
GimageResult
This object is produced by the GimageSearchgoogle.search.ImageSearch object. It is available in that object's .results[] array.
This object is indicated by a .GsearchResultClass value of GimageSearchgoogle.search.ImageSearch.RESULT_CLASS.
GimageResult - Properties
In addition to the common properties described above, the following object specific properties are available.
| Property | Description |
|---|---|
| | Supplies the title of the image, which is usually the base filename. |
| | Supplies the title, but unlike |
| | Supplies the raw URL of the image. |
| | Supplies an escaped version of the above URL. |
| | Supplies a shortened version of the URL associated with the result, typically displayed in green and stripped of a protocol and path. |
| | Supplies the URL of the page containing the image. |
| | Supplies the width of the image in pixels. |
| | Supplies the height of the image in pixels. |
| | Supplies the width, in pixels, of the image thumbnail. |
| | Supplies the height, in pixels, of the image thumbnail. |
| | Supplies the url of a thumbnail image. |
| | Supplies a brief snippet of information from the page associated with the search result. |
| | Supplies the same information as |
GimageResult CSS Structure
The following fragment of HTML illustrates the structure of an Image 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 style the "image size as" as bold, a CSS rule of #mycontrol .gs-imageResult .gs-size { font-weight : bold; } would do the trick.
class="gs-result gs-imageResult">
class="gs-text-box">
class="gs-snippet">
class="gs-size">
class="gs-visibleUrl">
GpatentResult
This object is produced by the GpatentSearchgoogle.search.PatentSearch object. It is available in that object's .results[] array.
This object is indicated by a .GsearchResultClass value of GpatentSearchgoogle.search.PatentSearch.RESULT_CLASS.
GpatentResult - Properties
In addition to the common properties described above, the following object specific properties are available.
| Property | Description |
|---|---|
| | Supplies the title of the patent result. |
| | Supplies the title, but unlike |
| | Supplies a snippet style description of the patent. |
| | Supplies the raw URL of the result. |
| | Supplies an escaped version of the above URL. |
| | Supplies the application filing date of the patent (rfc-822 format). |
| | Supplies the patent number for issued patents, and the application number for filed, but not yet issued patents. |
| | Supplies the status of the patent which can either be |
| | Supplies the assignee of the patent. |
| | Supplies the url of a thumbnail image which visually represents the patent. |
GpatentResult CSS Structure
The following fragment of HTML illustrates the structure of a Patent 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-patentResult .gs-snippet { display : none; } would do the trick.
class="gs-result gs-patentResult">
class="gs-image-box">
class="gs-text-box">
class="gs-text-box">
class="gs-patent-info gs-metadata">
class="gs-patent-number">
class="gs-publishedDate">
class="gs-author">
class="gs-snippet">
Flash and other Non-Javascript Environments
For Flash developers, and those developers that have a need to access the AJAX 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 use. 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 | http://ajax.googleapis.com/ajax/services/search/web |
| Local Search | http://ajax.googleapis.com/ajax/services/search/local |
| Video Search | http://ajax.googleapis.com/ajax/services/search/video |
| Blog Search | http://ajax.googleapis.com/ajax/services/search/blogs |
| News Search | http://ajax.googleapis.com/ajax/services/search/news |
| Book Search | http://ajax.googleapis.com/ajax/services/search/books |
| Image Search | http://ajax.googleapis.com/ajax/services/search/images |
| Patent Search | http://ajax.googleapis.com/ajax/services/search/patentNew! |
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=small | This optional argument supplies the number of results that the application would like to recieve. 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. 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": {
|
| 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( |
| 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(
|
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. http://www.google.com/jsapi). If the API loader was not used, a value of "us" is assumed. |
Local Search Specific Arguments
The Local Search system supports a number of optional arguments which are all listed below:
| Argument | Description |
|---|---|
| sll? | This optional argument supplies the search center point for a local search. It's value is a comma separated latitude/longitude pair, e.g., sll=48.8565,2.3509. |
| sspn? | This optional argument supplies a bounding box that the local search should be relative to. When using a Google Map, the sspn value can be computed using: myMap.getBounds().toSpan().toUrlValue(); (e.g., sspn=0.065169,0.194149). |
| mrt? | This optional argument specifies which type of listing the user is interested in. Valid values include:
localonly is used. |
Video Search Specific Arguments
The Video Search system supports a number of optional arguments which are all listed below:
| Argument | Description |
|---|---|
| scoring? | This optional argument tells the video search system how to order results. Results may be ordered by relevance (which is the default) or by date. To select ordering by relevance, do not supply this argument. To select ordering by date, set scoring as scoring=d. |
Blog Search Specific Arguments
The Blog Search system supports a number of optional arguments which are all listed below:
| Argument | Description |
|---|---|
| scoring? | This optional argument tells the blog search system how to order results. Results may be ordered by relevance (which is the default) or by date. To select ordering by relevance, do not supply this argument. To select ordering by date, set scoring as scoring=d. |
News Search Specific Arguments
The News Search system supports a number of optional arguments which are all listed below:
| Argument | Description |
|---|---|
| scoring? | This optional argument tells the news search system how to order results. Results may be ordered by relevance (which is the default) or by date. To select ordering by relevance, do not supply this argument. To select ordering by date, set scoring as scoring=d. |
| geo? | This optional argument tells the news search system to scope search results to a particular location. With this argument present, the query argument (q) becomes optional. Note, this is a very new feature and locally scoped query coverage is somewhat sparse. You must supply either a city, state, country, or zip code as in geo=Santa%20Barbara or geo=British%20Columbia or geo=Peru or geo=93108. Note that this optional argument cannot be used with the topic argument. |
| qsid? | This optional argument tells the news search system to scope search results to include only quote typed results (rather than classic news article style results). With this argument present, the query argument (q) becomes optional. The value of this argument designates a prominent individual whose quotes have been recognized and classified by the Google News search service. For instance, Barack Obama has a qsid value of tPjE5CDNzMicmM and John McCain has a value of lE61RnznhxvadM. Note, this is a very new feature and we currently do not have a good search or descovery mechanism for these qsid values.. |
| topic? | This optional argument tells the news search system to scope search results to a particular topic. The value of the argument specifies the topic in the current or selected edition:
query. If both a query and topic are specified, the query will be ignored. It is also not possible to scope a topic using the geo argument. Topics vary slightly from edition to edition. E.g., in African editions like Namibia or Zimbabwe |
| ned? | This optional argument tells the news search system which edition of news to pull results from. Values include:
&ned argument in the browser's address bar. |
Book Search Specific Arguments (experimental)
The Book Search system supports a number of optional arguments which are all listed below:
| Argument | Description |
|---|---|
| as_brr? | This optional argument tells the book search system to restrict the search to "full view" books, or all books. A value of as_brr=1 restricts the search to only those books that are viewable in full. The default case is all books and that is indicated by not specifying this argument. |
| as_list? | This optional argument tells the book search system to restrict the search to the specified user-defined library. |
Image Search Specific Arguments
The Image Search system supports a number of optional arguments which are all listed below. Additionally, results can be restricted to the LIFE photo archive by including source:life as part of the query, as in q=source%3Alife+query+terms (experimental).
| Argument | Description |
|---|---|
| safe? | This optional argument supplies the search safety level which may be one of:
|
| imgsz? | This optional argument tells the image search system to restrict the search to images of the specified size, where size can be one of:
|
| imgc? | This optional argument tells the image search system to restrict the search to images of the specified colorization, where colorization can be one of:
|
| imgcolor?New!
(experimental) | This optional argument tells the image search system to filter the search to images of the specified color:
|
| imgtype?
(experimental) | This optional argument tells the image search system to restrict the search to images of the specified type:
|
| as_filetype? | This optional argument tells the image search system to restrict the search to images of the specified filetype, where filetype can be one of:
|
| as_rights? | This optional argument tells the image search system to restrict the search to images labeled with the given licenses, where rights can be one or more of:
&as_rights=(cc_publicdomain|cc_attribute|cc_sharealike).-(cc_noncommercial|cc_nonderived) Note: Images returned with this filter may still have conditions on the license for use. Please remember that violating copyright is strictly prohibited by the API Terms of Use. For more details, see this article. |
| as_sitesearch? | This optional argument tells the image search system to restrict the search to images within the specified domain, e.g., as_sitesearch=photobucket.com. Note: This method restricts results to images found on pages at the given URL. |
Patent Search Specific Arguments
The Patent Search system supports a number of optional arguments which are all listed below:
| Argument | Description |
|---|---|
| as_psrg? | This optional argument tells the patent search system to restrict the search to ONLY patents that having been issued, skipping all patents that have only been filed. When specified, that value must be 1 as in &as_psrg=1 |
| as_psra? | This optional argument tells the patent search system to restrict the search to ONLY patents that only been filed, skipping over all patents that have been issued. When specified, that value must be 1 as in &as_psrg=1 |
| scoring? | This optional argument tells the patent search system how to order results. Results may be ordered by relevance (which is the default) or by date. To select ordering by relevance, do not supply this argument. To select ordering by descending date where the newest result is first, set scoring as scoring=d. To select ordering by ascending date where the oldest result is first, set scoring as scoring=ad. |
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. View example (searchformroot.html)
|
No comments:
Post a Comment