English ▼ | Sign out 
Google AJAX Search API
Google Custom Search Control Documentation
Developer's Guide
The Google AJAX Search API is a Javascript library that allows you to embed Google Search in your web pages and other web applications. For Flash, and other Non-Javascript environments, the API exposes a raw RESTful interface that returns JSON encoded results that are easily processed by most languages and runtimes.
The Google AJAX Search API provides simple web objects that perform inline searches over a number of Google services (Web Search, Local Search, Video Search, Blog Search, News Search, Book Search (experimental), Image Search, and Patent Search). If your web page is designed to help users create content (e.g. message boards, blogs, etc.), the API is designed to support these activities by allowing them to copy search results directly into their messages.
This API is new, and its feature set is largely determined by active involvement of its customers. Please join us in helping to shape the API and features by participating in the Google AJAX Search API discussion group to give feedback and discuss the API.
Table of Contents
Audience
This documentation is designed for people familiar with Javascript programming and object-oriented programming concepts. There are many Javascript tutorials available on the Web
Introduction
The "Hello, World" of Google AJAX Search API
The easiest way to start learning about this API is to see a simple example. The following web page displays a collection of inline search results for a "VW GTI." The search results include Local, Web, Video, Blog, News, Image, Patent, and Book Search results.
xmlns="http://www.w3.org/1999/xhtml">
http-equiv="content-type" content="text/html; charset=utf-8"/>
</span><span class="pln">Hello World - Google AJAX Search API Sample</span><span class="tag">
id="searchcontrol">Loading
You can download this example to edit and play around with it.
To use the search API within your web site, you will need to include the URL for the Google AJAX APIs loader (http://www.google.com/jsapi). This library allows you to load various APIs via google.load('api', 'version'). You can learn more here. Always be sure to include this library within a
google.load method as shown below. The google.load method takes an argument for the specific API and version number to load:google.search.* namespace for all classes, methods and properties you currently use in the Google AJAX Search API, replacing the G prefix with this namespace. For example, the GSearchControl object is mapped to google.search.SearchControl when using the Google AJAX API loader:
id="searchcontrol">
google.setOnLoadCallback to register the specified handler function to be called once the document loads instead of GSearch.setOnLoadCallback.- Dynamic loading - see the dynamic loading documentation.
- Don't load CSS - if you don't want to load the default CSS then set
"nocss"totrue.google.load("search", "1", {"nocss" : true});
- Don't load old namespace - if you don't want the old namespace (GSearch, GSearchControl, etc...) then set
"nooldnames"totrue.google.load("search", "1", {"nooldnames" : true});
Note: Most of the samples still use the old namespace so they will not work with this setting. This is only for custom applications that don't want their namespace to be cluttered with Google AJAX Search API. - Specific UI language - if you want to specify the language for the UI components (SearchControl, branding, etc...) instead of having it auto-detected then set
"language"to the specific language code such as: en, es, zh-CN, pt-PT, and etc...google.load("search", "1", {"language" : "en"});
Full documentation for using the Google AJAX API loader is available at http://code.google.com/apis/ajax/documentation/.
Browser Compatibility
The Google AJAX Search API currently supports Firefox 1.5+, IE 6, Safari, Opera 9+, and Chrome.
API Updates
The second argument within the google.load('search', '1.0'); contains the expected version level of this API (in this case version "1.0"). When we do a significant update to the API, we will "up" the version number and post a notice on the AJAX Search API discussion group. Take note of any required code changes when this occurs, and update your URLs to the new version when they are compliant.
After a new version is released, Google will support both old and new versions concurrently for a period of time, anticipated to be several months. After this period expires, client requests using the old API will no longer be accepted, so change your code as soon as you notice a new version.
The Google AJAX Search API team will also periodically update the API with recent bug fixes and performance enhancements without requiring a version update. For the most part, these fixes should remain transparent to you, but we may inadvertently break some API clients. Please use the AJAX Search API discussion group to report such issues.
Examples
Note: each of the following examples shows only relevant Javascript code, not a full HTML file. You can plug the code into the skeleton HTML file shown earlier, or you can download the full HTML file for each example by clicking the link after the example.
The Basics
The following example (identical to the Javascript code within the earlier Hello World code sample) creates a search control, configures it to search across Local Search, Web Search, Video Search, Blog Search, News Search, Image Search, Patant Search and Book Search (experimental), and then places the control on your page.
// create a search control
var searchControl = new google.search.SearchControl(null);
// add in a full set of searchers
searchControl.addSearcher(new google.search.LocalSearch());
searchControl.addSearcher(new google.search.WebSearch());
searchControl.addSearcher(new google.search.VideoSearch());
searchControl.addSearcher(new google.search.BlogSearch());
searchControl.addSearcher(new google.search.NewsSearch());
searchControl.addSearcher(new google.search.ImageSearch());
searchControl.addSearcher(new google.search.BookSearch());
searchControl.addSearcher(new google.search.PatentSearch());
// tell the searcher to draw itself and tell it where to attach
// Note that an element must exist within the HTML document with id "search_control"
searchControl.draw(document.getElementById("search_control"));
View example (helloworld.html)
SearcherControl Draw Modes
The search control can be programmed to display in different draw modes. The google.search.DrawOptions object controls this behavior through its setDrawMode() method. This method takes the following arguments:
google.search.SearchControl.DRAW_MODE_LINEARgoogle.search.SearchControl.DRAW_MODE_TABBED
google.search.DrawOptions object as a parameter to the search control's draw() method. // create a drawOptions object
var drawOptions = new google.search.DrawOptions();
// tell the searcher to draw itself in linear mode
drawOptions.setDrawMode(google.search.SearchControl.DRAW_MODE_LINEAR);
searchControl.draw(element, drawOptions);
// tell the searcher to draw itself in tabbed mode
drawOptions.setDrawMode(google.search.SearchControl.DRAW_MODE_TABBED);
searchControl.draw(element, drawOptions);
Another common option available through this method is the ability to decouple the "search form" from the set of search results. The google.search.DrawOptions object controls this behavior through its setSearchFormRoot() method. This method accepts a DOM element which will act as the container for the search form.
// create a drawOptions object
var drawOptions = new google.search.DrawOptions();
drawOptions.setSearchFormRoot(document.getElementById("searchForm"));
searchControl.draw(element, drawOptions);
View example (searchformroot.html)
Searcher Objects
The addSearcher() method of the search control object determines which search services the search control operates. This method takes two arguments, one which specifies the service object, and a second argument specifying options for the service. The following searcher objects (services) are currently supported:
google.search.LocalSearchgoogle.search.WebSearchgoogle.search.VideoSearchgoogle.search.BlogSearchgoogle.search.NewsSearchgoogle.search.ImageSearchgoogle.search.BookSearch(experimental)google.search.PatentSearch
google.search.SearcherOptions
When adding individual searchers to the search control, an optional second parameter, the google.search.SearcherOptions object, controls each service's default expansion mode, which affects how search results are displayed in that service's location on the web page. The expansion mode may be one of the following:
google.search.SearchControl.EXPAND_MODE_OPEN- Results are displayed as fully as possible within the object.
google.search.SearchControl.EXPAND_MODE_CLOSED- Results are hidden from view, unless opened through use of a UI element (e.g. an arrow).
google.search.SearchControl.EXPAND_MODE_PARTIAL- Results are shown as a subset of the "open" expansion mode.
// create a searcher options object
// set up for open expansion mode
// load a searcher with these options
var options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_OPEN);
searchControl.addSearcher(new google.search.WebSearch(), options);
Controlling Expansion Mode
The following example demonstrates the use of a search control in which each searcher is operating in a different expansion mode. Note that if the searcher is being drawn in tabbed mode, expansion mode is ignored. In that case, the searcher always operates in open mode.
// local search, partial
options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_PARTIAL);
searchControl.addSearcher(new google.search.LocalSearch(), options);
// web search, open
options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_OPEN);
searchControl.addSearcher(new google.search.WebSearch(), options);
View example (expandmode.html).
Controlling Searcher Results Location
In some applications, it is desirable to project search results for a given service into an arbitrary location on the web page. This mode of operation is supported by using the setRoot() method of the service's corresponding searcher object.
// web search, open, alternate root
var options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_OPEN);
options.setRoot(document.getElementById("somewhere_else"));
searchControl.addSearcher(new google.search.WebSearch(), options);
View example (somewhere-else.html)
Keeping a Search Result
The samples so far have focused on embedding search results on your page for display only, without the capability to store those results to another application. While this is a perfectly appropriate use of the Google AJAX Search API, it does not demonstrate its true potential. The Google AJAX Search API is designed to allow users to distribute search results to others, primarily through content creation applications like blog posts, message boards, etc.
The google.search.SearchControl object provides this functionality through its setOnKeepCallback() method. Using this method, applications specify an object and method that is called whenever a user indicates the wish to save a search result by clicking the "Copy" link below the result.
This link is only provided if applications have called setOnKeepCallback() method. When a user clicks the link, the registered callback receives a GResult instance representing the search result. This search results object contains a number of searcher specific properties, as well as a uniform html property that contains an HTML element representing the entire search result. The simplest way to handle the callback is to clone the html node and attach it to a node in your application's DOM.
// establish a keep callback
searchControl.setOnKeepCallback(this, MyKeepHandler);
function MyKeepHandler(result) {
// clone the result html node
var node = result.html.cloneNode(true);
// attach it
var savedResults = document.getElementById("saved_results");
savedResults.appendChild(node);
}
View example (keephandling.html)
Setting Site Restrictions
In some situations, you might want to restrict a web search, news search, or blog search to a specific site or blog. When you apply restrictions like this, you would typically also want to set your own custom label on the associated section of search results, and you might want to style this section of results differently.
All of these capabilities are supported by using a combination of methods exposed by the searcher options. The following sample demonstrates the use of .setUserDefinedLabel(), .setUserDefinedClassSuffix(), and .setSiteRestriction(). The sample creates a search control where one instance of google.search.WebSearch is site restricted to only return results from amazon.com, uses "Amazon.com" as the search section label, and applies some amount of custom css styling to this section (bold title, orange keeper button, etc.). A similar section showing site restrictions on a google.search.BlogSearch and on google.search.NewsSearch is also demonstrated.
No comments:
Post a Comment