本文档介绍了如何使用 Custom Search JSON API。
发出请求
Custom Search JSON API 中的 REST(即表征状态传输)与传统 REST 略有不同。该 API 不提供对资源的访问权限,而是对服务的访问权限。因此,该 API 提供了充当服务端点的单个 URI。
您可以通过向相应 URI 发送 HTTP GET
请求来检索特定搜索的结果。您将搜索请求的详细信息作为查询参数传入。Custom Search JSON API URI 的格式为:
https://www.googleapis.com/customsearch/v1?[parameters]
每个搜索请求都需要三个查询 [parameters]
:
- API 密钥 - 使用
key
查询参数来标识您的应用。 可编程搜索引擎 ID - 使用
cx
可指定用于执行此搜索的可编程搜索引擎。必须使用控制面板创建搜索引擎。注意:搜索引擎 ID (cx) 可以采用不同的格式(例如 8ac1ab64606d234f1)搜索查询 - 使用
q
查询参数指定您的搜索表达式。
所有其他查询参数都是可选的。
以下示例展示了如何在测试可编程搜索引擎中搜索 lectures:
GET https://www.googleapis.com/customsearch/v1?key=INSERT_YOUR_API_KEY&cx=017576662512468239146:omuauf_lfve&q=lectures
查询参数
您可以在请求中传递两种类型的参数:
- API 特有的参数 - 定义搜索的属性,例如搜索表达式、结果数量、语言等。
- 标准查询参数 - 定义请求的技术方面,例如 API 密钥。
所有参数值都需要经过网址编码。
API 专属查询参数
如需了解专门适用于 Custom Search JSON API 并用于定义搜索请求的请求参数,请参阅参考文档。
标准查询参数
系统参数中介绍了适用于所有 Custom Search JSON API 操作的查询参数。
响应数据
如果请求成功,服务器将返回 200 OK
HTTP 状态代码以及 JSON 格式的响应数据。您可以在引用中查找响应数据结构。
响应数据是一个 JSON 对象,其中包含以下三种属性:
- 描述请求的搜索(也可能是相关的搜索请求)的元数据
- 描述可编程搜索引擎的元数据
- 搜索结果
如需详细了解每个属性,请参阅参考文档。
搜索请求元数据
搜索元数据包括:
url
属性,该属性包含有关用于此请求中返回结果的 OpenSearch 模板的信息。queries
属性:这是一个描述可能搜索特征的对象数组。数组中每个对象的名称要么是 OpenSearch 查询角色的名称,要么是此 API 定义的两个自定义角色之一:previousPage
和nextPage
。可能的查询角色对象包括:request
:描述当前结果集的查询的元数据。- 此角色会一直存在于响应中。
- 该组一直只有一个元素。
nextPage
:描述用于下一页结果的查询的元数据。- 如果当前结果是最后一页,则此角色不存在。 注意 :此 API 最多仅返回前 100 个结果。
- 如果此角色出现,则会保持自身的组只包含一个元素。
previousPage
:描述用于上一页结果的查询的元数据。- 如果当前结果在第一页中,则此角色不会出现。
- 如果存在,则始终是一个只包含一个元素的数组。
搜索引擎元数据
context
属性包含描述执行搜索查询的搜索引擎的元数据。它包含搜索引擎的名称,以及它提供的任何用于优化搜索的构面对象。
搜索结果
items
数组包含实际搜索结果。搜索结果包括描述结果的网址、标题和文本摘要。此外,它们可以包含结构化摘要信息(如果适用)。
如果搜索结果包含 promotions
属性,则它包含一组促销活动。
JavaScript 中的 REST
您可以通过 callback
查询参数和回调函数,使用 JavaScript 中的 REST 调用 Custom Search JSON API。这样,您无需编写任何服务器端代码,即可编写显示可编程搜索引擎数据的丰富应用。
以下示例使用此方法显示查询 cars 的第一页搜索结果:
<html>
<head>
<title>Custom Search JSON API Example</title>
</head>
<body>
<div id="content"></div>
<script>
function hndlr(response) {
for (var i = 0; i < response.items.length; i++) {
var item = response.items[i];
// Make sure HTML in item.htmlTitle is escaped.
document.getElementById("content").append(
document.createElement("br"),
document.createTextNode(item.htmlTitle)
);
}
}
</script>
<script src="https://www.googleapis.com/customsearch/v1?key=YOUR-KEY&cx=017576662512468239146:omuauf_lfve&q=cars&callback=hndlr">
</script>
</body>
</html>