My favorites | 中文(简体) | Sign in

开发人员指南

Google AJAX 搜索 API 是一种 Javascript 库，使您可以将 Google 搜索嵌入您的网页和其他网络应用程序中。对于 Flash 和其他非 Javascript 环境，该 API 将显示一个原始 RESTful 界面新增！，其返回的经过 JSON 编码的结果可用大多数语言和运行时轻松处理。

Google AJAX 搜索 API 提供了简单的网络对象，可以通过许多 Google 服务（网页搜索、本地搜索、视频搜索、博客搜索、资讯搜索、图书搜索、图片搜索和专利搜索）执行内联搜索。如果您的网页旨在帮助用户创建内容（例如留言板、博客等），该 API 可以通过使用户将搜索结果直接复制到他们的消息中来支持这些活动。

此 API 是新开发的，它的功能集主要取决于其客户的积极参与。请通过加入 Google AJAX 搜索 API 论坛提供有关此 API 的反馈并加以讨论，来帮助我们完善此 API 及其功能。


Google AJAX 搜索 API 目前使用 Google AJAX API 载入程序。通过使用此载入程序，可以更加轻松地在同一网页上使用多个 Google AJAX API 并统一这些 API 的名称空间。如果您不想更改代码，那么它将不会被破坏，并且旧名称空间将继续起作用。更多相关信息：

目录

读者
简介
Google AJAX 搜索 API 的 Hello World
使用 Google AJAX API 载入程序
浏览器兼容性
API 更新
实例
基本知识
SearchControl 模式
搜索器对象
搜索器选项
保存搜索结果
设置网站限制
搜索控件回调
自定义搜索框
高级标记
高级示例
API 概述
设计搜索结果样式新增！
Flash 和其他非 Javascript 环境新增！
代码段
类参考
疑难解答

读者

此文档适用于熟悉 JavaScript 编程和面向对象编程概念的用户。您可以在网络上找到许多 JavaScript 教程

简介

Google AJAX 搜索 API 的“Hello, World”

查看简单的实例是开始学习此 API 的最简单方法。以下网页显示了对于“VW GTI”的内联搜索结果的集合。搜索结果包括本地搜索结果、网页搜索结果、视频搜索结果、博客搜索结果、资讯搜索结果、图片搜索结果、专利搜索结果新增！和图书搜索结果。 

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Hello World - Google AJAX Search API Sample</title>
    <script src="http://www.google.com/jsapi"
        type="text/javascript"></script>
    <script language="Javascript" type="text/javascript">
    //<![CDATA[
    google.load('search', '1');
    
    function OnLoad() {
      // Create a search control
      var searchControl = new google.search.SearchControl();

      // Add in a full set of searchers
      var localSearch = new google.search.LocalSearch();
      searchControl.addSearcher(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());

      // Set the Local Search center point
      localSearch.setCenterPoint("New York, NY");

      // tell the searcher to draw itself and tell it where to attach
      searchControl.draw(document.getElementById("searchcontrol"));

      // execute an inital search
      searchControl.execute("VW GTI");
    }
    google.setOnLoadCallback(OnLoad);

    //]]>
    </script>
  </head>
  <body>
    <div id="searchcontrol">Loading</div>
  </body>
</html>

您可以下载此示例以对其进行编辑和调试。

要在网站中使用该搜索 API，您需要添加 Google AJAX API 载入程序的网址 (http://www.google.com/jsapi)。该库允许您通过 google.load('api', 'version') 载入各种 API。点击此处可了解详细信息。在尝试使用搜索控件功能前，请始终确保在

Google AJAX Search API 使用的主要对象是 SearchControl 的实例，其可以跨搜索服务集合（表示为该对象的子对象）调整搜索。

正如您在上述示例中看到，使用 addSearcher() 方法将类型 LocalSearch、WebSearch、VideoSearch、BlogSearch、NewsSearch、ImageSearch、PatentSearch 和 BookSearch 的子对象添加到搜索控件中，这些搜索器对象可确定该搜索控件会在哪些搜索服务中执行搜索。

该搜索控件通过对 SearchControl 方法的调用在网页中显示自身；此方法还可以将该搜索控件绑定到您的网页上（在 DOM 中）。draw()默认情况下，搜索控件将绘制“线性”布局；您还可以指示该控件绘制“标签式”布局。这些绘制模式将在稍后进行讨论。

除了标签式布局选项，该搜索控件还使您可以轻松将“搜索框”与搜索结果集分开。此功能的一个用途是在网页的侧边栏中显示搜索框，并使结果堆叠在该页面的中心。

用户通过将搜索词语输入到搜索控件的文本字段中，然后按 ENTER 键或者单击位于输入字段右侧的搜索按钮开始搜索。搜索控件将在请求的 Google 服务中自动开始并行搜索。您也可以通过调用搜索控件的 execute() 方法，传递搜索词语的参数以编程方式开始搜索。

使用 Google AJAX API 载入程序

Google AJAX Search API 目前与 Google AJAX API 载入程序完全集成。该载入程序使您可以使用一个 API 密钥为所有受支持的 Google AJAX API（包括 Google 地图 API 和 Google AJAX Feed API）载入所有 API。Google AJAX API 载入程序还指定了一个通用的名称空间方案，以便可以更加轻松地将不同的 Google API 一起使用。请注意，将继续支持旧的名称空间方案，因此现有的应用程序无需更新。

Google AJAX API 载入程序的使用较为简单。更改您的应用程序以使用该载入程序包括以下步骤：

  • 从 http://www.google.com/uds 载入通用载入程序，而不是从 http://www.google.com/jsapi 载入 AJAX Search API。可以传递现有的 Google AJAX Search API 密钥，如下所示：
    • <script type="text/javascript" src="http://www.google.com/jsapi?key=ABCDEFG"></script>
  • 通过使用 google.load 方法载入 AJAX Search API，如下所示：google.load 方法为要载入的特定 API 和版本号获取一个参数：
    • <script type="text/javascript">
  google.load("search", "1");
</script>
  • 为当前在 Google AJAX Search API 中使用的所有类、方法和属性使用 google.search.* 名称空间，使用此名称空间替换 G 前缀。例如，使用 Google AJAX API 载入程序时 GSearchControl 对象将被映射到 google.search.SearchControl。
    • <html>
  <head>
    <script src="http://www.google.com/jsapi?key=ABCDEFG"
        type="text/javascript"></script>
    <script type="text/javascript">
      google.load("search", "1");

      // Call this function when the page has been loaded
      function initialize() {
        var searchControl = new google.search.SearchControl();
        searchControl.addSearcher(new google.search.WebSearch());
        searchControl.addSearcher(new google.search.NewsSearch());
        searchControl.draw(document.getElementById("searchcontrol"));
      }
      google.setOnLoadCallback(initialize);
    </script>

  </head>
  <body>
    <div id="searchcontrol"></div>
  </body>

</html>
  • 使用 google.setOnLoadCallback（而不是 GSearch.setOnLoadCallback）记录文档载入后要被调用的指定处理程序函数。
  • AJAX Search API 具有一些可选的载入程序设置。新增！
    • 动态载入 - 请参考动态载入文档。
    • 不载入 CSS - 如果您不想载入默认的 CSS，请将 "nocss" 设置为 true。 
      google.load("search", "1", {"nocss" : true});
    • 不载入旧名称空间 - 如果不想使用旧名称空间（GSearch、GSearchControl 等），请将 "nooldnames" 设置为 true。 
      google.load("search", "1", {"nooldnames" : true});
      注意：大多数示例仍然使用旧名称空间，因此使用此设置这些示例将无法运行。此设置仅适用于不希望其名称空间被 Google AJAX Search API 搅乱的自定义应用程序。
    • 特定 UI 语言 - 如果您想指定 UI 组件（SearchControl、标记等）的语言（而不是由系统自动检测），请将 "language" 设置为特定的语言代码（例如 en、es、zh-CN、pt-PT 等） 
      google.load("search", "1", {"language" : "en"});

    • http://code.google.com/apis/ajax/documentation/ 上提供了有关使用 Google AJAX API 载入程序的完整文档。

    浏览器兼容性

    Google AJAX 搜索 API 目前支持 Firefox 1.5+、IE 6、Safari、Opera 9+ 和 Chrome。

    API 更新

    google.load('search', '1.0'); 中的第二个参数包含此 API 的预期版本级别（在此情况下为“1.0”版）。当对此 API 进行重大更新时，我们将递增版本号并在 AJAX Search API 讨论组中发布通知。请留意更新时所需的任何代码更改，并在适用时将您的网址更新为新版本的网址。

    新版本发布后，Google 将长期（预期为几个月）同时支持新旧两种版本。此阶段到期后，将不再接受使用旧 API 的客户请求，因此请在您注意到新版本时尽快更改代码。

    Google AJAX Search API 团队还将使用最新的错误修正和性能改进来定期更新该 API，这种情况下无需版本更新。通常，这些修正对您是显而易见的，但是我们可能会无意中破坏某些 API 客户端。请使用 AJAX Search API 讨论组报告此类问题。

    实例

    注意：以下每个实例仅显示了相关的 Javascript 代码，而不是完整的 HTML 文件。可以将代码插入先前显示的大体 HTML 文件中，也可以通过单击实例后面的链接下载每个实例的完整 HTML 文件。

    基本知识

    以下示例（与先前 Hello World 代码示例中的 Javascript 代码相同）将创建一个搜索控件，并将其配置为在本地搜索、网页搜索、视频搜索、博客搜索、资讯搜索、图片搜索、专利搜索和图书搜索中进行搜索，然后将该控件放置在您的网页上。 

    // 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"));

    查看示例 (helloworld.html)

    SearcherControl 绘制模式

    可以对搜索控件进行编程，使其以不同的绘制模式显示。google.search.DrawOptions 对象通过其 setDrawMode() 方法控制此特性。此方法使用以下参数：

    • google.search.SearchControl.DRAW_MODE_LINEAR
    • google.search.SearchControl.DRAW_MODE_TABBED
    要实际设置搜索控件对象的绘制模式，请将 google.search.DrawOptions 对象作为参数传递至该搜索控件的 draw() 方法。 

    // 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);

    查看示例 (tabbed.html)

    通过此方法可用的另一个通用选项可以将“搜索框”与搜索结果集分开。google.search.DrawOptions 对象通过其 setSearchFormRoot() 方法控制此特性。此方法将接受一个 DOM 元素，其将用作该搜索框的容器。 

    // create a drawOptions object
var drawOptions = new google.search.DrawOptions();
drawOptions.setSearchFormRoot(document.getElementById("searchForm"));

searchControl.draw(element, drawOptions);

    查看示例 (searchformroot.html)

    搜索器对象

    搜索控件对象的 addSearcher() 方法可以确定该搜索控件执行的搜索服务。此方法使用两个参数，一个参数用于指定服务对象，另一个参数用于指定该服务的选项。目前支持以下搜索器对象（服务）：

    • google.search.LocalSearch
    • google.search.WebSearch
    • google.search.VideoSearch
    • google.search.BlogSearch
    • google.search.NewsSearch
    • google.search.ImageSearch
    • google.search.BookSearch
    • google.search.PatentSearch新增！
    考虑到 Google AJAX Search API 正在开发过程中，受支持的服务列表将不断变化。

    google.search.SearcherOptions

    将各个搜索器添加到搜索控件后，可选的第二个参数（google.search.SearcherOptions 对象）可以控制每个服务的默认扩展模式，这将影响在网页上的该服务位置中将显示多少搜索结果。扩展模式可以为以下模式之一：

    google.search.SearchControl.EXPAND_MODE_OPEN
    在对象中尽可能完整显示的结果。
    google.search.SearchControl.EXPAND_MODE_CLOSED
    结果被从视图中隐藏，除非通过使用 UI 元素（例如箭头）打开。
    google.search.SearchControl.EXPAND_MODE_PARTIAL
    结果显示为“开放”扩展模式的子集。
    // 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);

    控制扩展模式

    以下实例说明了搜索控件的使用，其中每个搜索器均以不同的扩展模式运行。请注意，如果要以标签式模式绘制搜索器，则忽略扩展模式。在这种情况下，搜索器将始终处于开放模式。 

    // 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);

    查看示例 (expandmode.html)。

    控制搜索器结果位置

    在某些应用程序中，需要将给定服务的搜索结果投影到网页上的任意位置。可以通过使用服务对应的搜索器对象的 setRoot() 方法支持此运行模式。 

    // 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);

    查看示例 (somewhere-else.html)

    保存搜索结果

    到目前为止，这些示例已着重介绍了在您的网页上嵌入搜索结果（仅用于显示），但无法将这些结果存储到其他应用程序中。虽然这是 Google AJAX Search API 非常合适的用途，但是它没有展示出其真正的潜在功能。Google AJAX Search API 旨在使用户可以向其他人分发搜索结果（主要通过内容创建应用程序，如博客帖子、留言板等）。

    google.search.SearchControl 对象通过其 setOnKeepCallback() 方法提供此功能。使用此方法，应用程序可以指定一个每当用户想要通过单击结果下面的“复制”链接保存该搜索结果时调用的对象和方法。

    仅当应用程序已调用 setOnKeepCallback() 方法时才会有此链接。当用户点击此链接时，已记录的回调将接收一个表示搜索结果的 GResult 实例。此搜索结果对象包含许多搜索器特定的属性，以及一个统一的 html 属性（包含表示整个搜索结果的 HTML 元素）。处理该回调的最简单方法是复制 html 节点并将其附加到您应用程序的 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);
}

    查看示例 (keephandling.html)

    设置网站限制

    在某些情况下，您可能想要将网页搜索、新闻搜索或博客搜索限制到特定网站或博客。当您应用此类限制时，通常您可能还想在关联的搜索结果区域上设置自己的自定义标签，并且可能想为此结果区域设计不同的样式。

    可以通过使用由搜索器选项提供的方法组合支持所有这些功能。以下示例演示了 .setUserDefinedLabel()、.setUserDefinedClassSuffix() 和 .setSiteRestriction() 的使用。该示例创建一个搜索控件，其中 google.search.WebSearch 的一个实例是限制为仅返回来自 amazon.com 的结果的网站，使用“Amazon.com”作为搜索区域标签，并将一些自定义 CSS 样式（粗体标题、橙色钩子按钮等）应用于此区域。还演示了一个类似的区域（显示 google.search.BlogSearch 和 google.search.NewsSearch 上的网站限制）。 

    <style type="text/css">
/* customize checkbox for -siteSearch section and
 * set section title and keep label to bold
 */
.gsc-resultsRoot-siteSearch .gsc-keeper {
  background-image : url('../../css/orange_check.gif');
  font-weight : bold;
}
.gsc-resultsRoot-siteSearch .gsc-title { font-weight : bold; }
...

// site restricted web search with custom label
// and class suffix
var siteSearch = new google.search.WebSearch();
siteSearch.setUserDefinedLabel("Amazon.com");
siteSearch.setUserDefinedClassSuffix("siteSearch");
siteSearch.setSiteRestriction("amazon.com");
searchControl.addSearcher(siteSearch);

// site restricted web search using a custom search engine
siteSearch = new google.search.WebSearch();
siteSearch.setUserDefinedLabel("Product Reviews");
siteSearch.setSiteRestriction("000455696194071821846:reviews");
searchControl.addSearcher(siteSearch);

    查看示例 (sitesearch.html)

    搜索控件回调

    在某些情况下，您想要使用该搜索控件（因为它提供了您需要的所有 UI），但是您需要在获得搜索结果时查看并处理部分搜索结果。该搜索控件提供了一对回调，从而使您不必使用 google.search.Search 层（在该层您具有此功能，但是需要对此 UI 负责）。您可以使用这些回调来请求在搜索执行之前和搜索完成之后通知您。请注意，您不能依靠已完成搜索中的给定执行结果。可能永远不会完成搜索，因此请勿将您自己编码为死锁。以下典型示例说明了当您想在附近的地图上绘制本地搜索结果时出现死锁的情况。

    以下代码段演示了此功能的使用。 

    searchControl.setSearchCompleteCallback(this, App.prototype.OnSearchComplete);
searchControl.setSearchStartingCallback(this, App.prototype.OnSearchStarting);


App.prototype.OnSearchComplete = function(sc, searcher) {

  // if we have local search results, put them on the map
  if ( searcher.results && searcher.results.length > 0) {
    for (var i = 0; i < searcher.results.length; i++) {
      var result = searcher.results[i];

      // if this is a local search result, then proceed...
      if (result.GsearchResultClass == GlocalSearch.RESULT_CLASS ) {
        ...

App.prototype.OnSearchStarting = function(sc, searcher, query) {
  alert("The Query is: " + query);
  ...

    以下示例是对这些 API 更加完整的演示。它显示了如何使用这两个回调处理本地搜索结果以及如何将其放置在附近的地图上。查看示例 (sc-callbacks.html)

    自定义搜索框

    使用 google.search.SearchControl 时，您的应用程序还可以使用集成的“搜索框”。此框提供了一个文本输入元素、一个搜索按钮、一个清除按钮以及“Google 标记”。如果您的应用程序未使用此搜索控件，而是使用原始的 google.search.Search 层，则 google.search.SearchForm() 对象正好适合您。使用此对象，您可以获得所有好处以及搜索框（集成到该搜索控件中，但是打包为独立对象，从而使您可以控制其特性和位置）的标记。

    以下代码段演示了此功能的使用。 

    // create a search form without a clear button
// bind form submission to my custom code
var container = document.getElementById("searchFormContainer");
this.searchForm = new google.search.SearchForm(false, container);
this.searchForm.setOnSubmitCallback(this, App.prototype.newSearch);

// called on form submit
App.prototype.newSearch = function(form) {
  if (form.input.value) {
    this.searchControl.execute(form.input.value);
  }
  return false;
}

    以下示例演示了该对象的使用：查看示例 (places.html)

    高级标记

    使用 google.search.SearchControl 或 google.search.SearchForm 时，会自动向您的用户显示“由 Google 提供支持”标记。它们可以使您的网站提供的搜索服务与 Google 相关联。当您的应用程序没有使用这些框的任意一种时，仍然要向您的用户传达 Google 标记，这一点很重要。google.search.Search.getBranding() 方式旨在帮助您实现此操作。此方法接受一个 HTML DOM 元素并将“由 Google 提供支持”标记附加带该元素中。或者，向您返回“由 Google 提供支持”HTML DOM 元素，以便您可以直接附加该元素。

    以下代码段演示了此功能的使用。 

    // attach "powered by Google" branding
google.search.Search.getBranding(document.getElementById("branding"));
...
<div id="branding">Loading...</div>

    以下示例演示了该对象的使用：查看示例 (branding.html)

    其他示例

    其他用法示例演示了许多概念，但是都是在更大的应用程序代码段中。

    API 概述

    Google AJAX 搜索 API 由几类对象组成：

    • google.search.SearchControl - 此类可以通过大量搜索器对象提供用户界面和协调，其中每个搜索器对象都旨在执行搜索并返回特定类的结果（网页搜索、本地搜索等）。
    • google.search.Search - 这是一个基本类，所有“搜索器”均继承自该类。它定义了所有搜索器服务都必须应用的界面。
    • GResult - 此基本类可以封装由搜索器对象生成的搜索结果。
    • google.search.SearcherOptions - 此类可以在将搜索器对象添加到搜索控件时配置其特性。

    建议您通过以下模式使用这些类：

    // create a searcher object
var sc = new google.search.SearchControl();

// add one or more searchers, specifying options as needed
var options = new google.search.SearcherOptions();
options.setExpandMode(google.search.SearchControl.EXPAND_MODE_OPEN);
sc.addSearcher(new google.search.WebSearch(), options);
...

// activate the search control by calling it's .draw() method
sc.draw(document.getElementById("myDiv"));

    只要您遵循了这些基本步骤，搜索控件便会激活。绘制搜索控件后便不能再添加其他搜索器，并且不能修改搜索器选项。如果您需要更改搜索控件的特性，则必须构造并激活一个新的搜索控件。

    有关详细信息，请参考 Search API 类参考。

    设计搜索结果样式新增！

    每个搜索结果均包括一个默认的 .html 属性，请记住该属性是使用 CSS 样式构建的。因此，每段语义信息均包含在 HTML 标记中，并且具有一组适当的类标记。这使您可以使用此 HTML 连同您自己的自定义 CSS 规则（设计 HTML 的样式），从而满足您的需求。

    正如您将在以下部分中看到的，每个搜索结果均包含在一个 div 元素（使用常规 gs-result 搜索结果类以及结果类型特定的类 [例如 gs-webResult、gs-localResult 等] 进行标记）中。此结构使您可以轻松定义常规 CSS 规则（其应用于所有结果）以及类型特定的规则。

    除了此结构之外，当结果由 google.search.SearchControl 进行管理时，每个结果均包含在 div 元素（使用常规 gsc-result 搜索结果类以及结果类型特定的类 [例如 gsc-webResult、gsc-localResult 等] 进行标记）中。每部分结果将进一步包括在 div 元素（使用常规 gsc-results 搜索结果类以及结果类型特定的类 [例如 gsc-webResult、gsc-localResult 等] 进行标记）中。

    此结构的净结果为以下概要： 

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

    有关每个搜索结果的 CSS 结构的详细信息，请参考以下部分。

    Flash 和其他非 Javascript 环境新增！

    对于 Flash 开发人员以及需要从其他非 Javascript 环境中访问 AJAX Search API 的开发人员，该 API 提供了一个简单的 RESTful 界面。在所有情况下，支持的方法均为 GET，响应格式为 JSON 已编码结果集（具有嵌入的状态代码）。使用此界面的应用程序必须遵守所有现有的使用条款。需要特别注意的是要在您的请求中正确标识自己。应用程序必须始终在其请求中包含一个有效且准确的 http 参考标头。此外，我们要求（但不命令）每个请求包含一个有效的 API 密钥。通过提供密钥，您的应用程序可以向我们提供辅助的身份机制，这在我们需要联系您以纠正问题时会很有用。

    熟悉此界面最简单的方法便是亲自实践。请使用命令行工具 curl 或 wget 执行以下命令： 

    curl -e http://www.my-ajax-site.com \
        'http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton'

    此命令将针对 /ajax/services/search/webParis Hilton () 执行一次网页搜索 (q=Paris%20Hilton)。响应具有 Content-Type 的 text/javascript; charset=utf-8。您可以从以下的响应中看到 responseData 等同于基本搜索对象文档中描述的 results 和 cursor属性。 

    {"responseData": {
 "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": "\[1\] In 2006, she released her debut album..."
  },
  {
   "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..."
  },
  ...
 ],
 "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\u0026ie\u003dutf8..."
 }
}
, "responseDetails": null, "responseStatus": 200}

    除此响应格式以外，该协议也支持标准的 JSON-P 样式的回调，可通过指定 callback 参数来触发这类回调。此参数存在时，会将 JSON 对象作为参数传递到指定的回调中。 

    curl -e http://www.my-ajax-site.com \
 'http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton&callback=processResults'

    此命令执行网络搜索（与先前的搜索相同），但是已更改为传递 callback。正确使用此参数后，将会在响应中返回 Javascript 调用（而不是返回 JSON 对象），JSON 对象会通过 results 参数传递。 

    processResults({"responseData": {
 "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": "\[1\] In 2006, she released her debut album..."
  },
  {
   "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..."
  },
  ...
 ],
 "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\u0026ie\u003dutf8..."
 }
}
, "responseDetails": null, "responseStatus": 200})

    最后，该协议还支持 callback 和 context 参数。指定了这些网址参数后，响应将作为直接 Javascript 调用 与callback(context, results, status, details, unused) 的签名一起进行编码。请注意以下命令和响应中的细微差别。 

    curl -e http://www.my-ajax-site.com \
 'http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton&callback=foo&context=bar'

    此命令执行网页搜索（与先前的搜索相同），但是已更改为传递 callback 和 context。正确使用这些参数时，将在响应中返回 Javascript 调用（而不是 JSON 对象），并且通过 results 参数传递 JSON 对象。 

    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)

    代码段新增！

    以下小节提供了演示从 Flash、Java 和 php 进行 API 访问的代码段。如果对处理 JSON 响应有任何疑问，请务必访问 JSON.org 网站，并密切关注网页的第二部分，其中引用了各种 JSON 库。有关如何通过 REST API 来实现前面小节中所描述的各种 Google API 服务的详细信息，请参见到基础网址的表格映射方法。

    Flash 访问

    以下代码段演示了如何从 Flash 向 AJAX 搜索 API 发送请求。请注意使用 ActionScript 3.0 (AS3) 核心库中的 JSON。 

    var service:HTTPService = new HTTPService();
service.url = 'http://ajax.googleapis.com/ajax/services/search/web';
service.request.v = '1.0';
service.request.q = 'Paris Hilton';
service.resultFormat = 'text';
service.addEventListener(ResultEvent.RESULT, onServerResponse);
service.send();

private function onServerResponse(event:ResultEvent):void {
  try {
    var json:Object = JSON.decode(event.result as String);
    // now have some fun with the results...
  } catch(ignored:Error) {
  }
}

    Java 访问

    以下代码段演示了如何从 Java 向 AJAX 搜索 API 发送请求。请注意使用 http://www.json.org/java/ 中的 json 库。 

    URL url = new URL("http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton");
URLConnection connection = url.openConnection();
connection.addRequestProperty("Referer", "http://www.mysite.com/index.html");

String line;
StringBuilder builder = new StringBuilder();
BufferedReader reader = new BufferedReader(new InputStreamReader(connection.getInputStream()));
while((line = reader.readLine()) != null) {
 builder.append(line);
}

JSONObject json = new JSONObject(builder.toString());
// now have some fun with the results...

    Php 访问

    以下代码段演示了如何从 php 向 AJAX 搜索 API 发送请求。请注意，此示例假定使用 PHP 5.2。对于较早安装的 PHP，请参考此注释。 

    $url = "http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=Paris%20Hilton";

// sendRequest
// note how referer is set manually
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_REFERER, "http://www.mysite.com/index.html");
$body = curl_exec($ch);
curl_close($ch);

// now, process the JSON string
$json = json_decode($body);
// now have some fun with the results...

    有关此界面的完整文档，请参考类参考手册。

    疑难解答

    如果您在使用代码时遇到问题：

    • 请确保您的 API 密钥有效。
    • 查找错别字。请注意，JavaScript 语言区分大小写。
    • 使用 JavaScript 调试器。在 Firefox 中，您可以使用 JavaScript 控制台或 FireBug。在 IE 中，您可以使用 Microsoft 脚本调试器。
    • 搜索 AJAX Search API 讨论组。如果找不到可以解答您问题的帖子，请将您的问题连同演示该问题的网页链接一起发布到该讨论组。