本页面指的是 Custom Search JSON API 的 XML 版本,它仅供 Google Site Search 客户使用。
概览
借助 Google WebSearch 服务,Google Site Search 客户可以在自己的网站上展示 Google 搜索结果。WebSearch 服务使用基于 HTTP 的简单协议来提供搜索结果。搜索管理员可以完全控制他们请求搜索结果的方式以及向最终用户呈现这些结果的方式。本文档介绍了 Google 搜索请求和结果格式的技术细节。
为了检索 Google WebSearch 结果,您的应用会向 Google 发送一个简单的 HTTP 请求。然后,Google 会返回 XML 格式的搜索结果。XML 格式的结果可让您自定义搜索结果的显示方式。
WebSearch 请求格式
请求概览
Google 搜索请求是一个标准的 HTTP GET
命令。它包含与您的查询相关的一系列参数。这些参数以“名称=值”对的形式包含在请求网址中,以和号 (&) 字符分隔。参数包括搜索查询等数据,以及用于标识发出 HTTP 请求的引擎的唯一引擎 ID (cx
)。WebSearch 或图片搜索服务会返回 XML 结果以响应您的 HTTP 请求。
查询字词
大多数搜索请求都包含一个或多个查询字词。查询字词在搜索请求中显示为参数的值。
查询字词可以指定几种类型的信息,以过滤和整理 Google 返回的搜索结果。查询可以指定:
- 要包含或排除的字词或词组
- 搜索查询中的所有字词(默认)
- 搜索查询中的确切词组
- 搜索查询中的任何字词或短语
- 在文档中的什么位置查找搜索字词
- 文档中的任何位置(默认)
- 仅在文档正文中
- 仅在文档标题中
- 仅在文档网址中
- 仅在文档的链接中
- 对文档本身的限制
- 包含或排除特定文件类型的文档(例如 PDF 文件或 Word 文档)
- 特殊网址查询,此类查询返回指定网址的相关信息,而不执行搜索
- 返回有关某个网址的一般信息(例如其开放目录类别、摘要或语言)的查询
- 返回链接到某个网址的一组网页的查询
- 返回一组与给定网址相似的网页的查询
默认搜索引擎
搜索查询参数值必须经过网址转义。请注意,您可以使用加号 ("+") 代替搜索查询中的任何空格序列。本文的网址转义部分将对此进行详细说明。
系统会使用 q 参数将搜索查询字词提交到 WebSearch 服务。搜索查询字词示例如下:
q=horses+cows+pigs
默认情况下,Google WebSearch 服务仅返回搜索查询中包含所有字词的文档。
请求参数
本部分列出了在发出搜索请求时可以使用的参数。这些参数分为两个列表。第一个列表包含与所有搜索请求相关的参数。第二个列表包含仅与高级搜索请求相关的参数。
以下三个请求参数是必填项:
- client 参数必须设置为
google-csbe
- output 参数用于指定返回的 XML 结果的格式;返回结果时,可以附上 (xml) 或不带 (
xml_no_dtd
) 对 Google DTD 的引用。建议将此值设置为xml_no_dtd
。注意:如果您不指定此参数,系统将以 HTML(而非 XML)形式返回结果。
- cx 参数,表示引擎的唯一 ID。
除了上述参数之外,最常用的请求参数还包括:
WebSearch 查询示例
以下示例展示了几个 WebSearch HTTP 请求,旨在说明如何使用不同的查询参数。有关不同查询参数的定义,请参阅本文档的 WebSearch 查询参数定义和高级搜索查询参数部分。
此请求查询查询字词“red Sox”(q=red+sox
) 的前 10 个结果 (start=0&num=10
)。该查询还指定结果应来自加拿大网站 (cr=countryCA
),并且应使用法语 (lr=lang_fr
) 编写。最后,该查询指定了 client、output 和 cx 参数的值,这三个都是必需的。
http://www.google.com/search?
start=0
&num=10
&q=red+sox
&cr=countryCA
&lr=lang_fr
&client=google-csbe
&output=xml_no_dtd
&cx=00255077836266642015:u-scht7a-8i
此示例使用一些高级搜索查询参数进一步自定义搜索查询。此请求使用 as_q 参数 (as_q=red+sox
) 而不是 q 参数。它还使用 as_eq 参数从搜索结果 (as_eq=yankees
) 中排除包含“扬基”一词的所有文档。
http://www.google.com/search?
start=0
&num=10
&as_q=red+sox
&as_eq=Yankees
&client=google-csbe
&output=xml_no_dtd
&cx=00255077836266642015:u-scht7a-8i
WebSearch 查询参数定义
c2coff | |||||||
---|---|---|---|---|---|---|---|
说明 | 可选。c2coff 参数可启用或停用简体中文和繁体中文搜索功能。 此参数的默认值为
|
||||||
示例 | q=google&c2coff=1 |
客户端 | |
---|---|
说明 | 强制要求。 |
示例 | q=google&client=google-csbe |
cr | |
---|---|
说明 | 可选。 Google WebSearch 通过分析以下各项来确定文档所在的国家/地区:
如需查看此参数的有效值列表,请参阅国家/地区 (cr) 参数值部分。 |
示例 | q=Frodo&cr=countryNZ |
cx | |
---|---|
说明 | 强制要求。 |
示例 | q=Frodo&cx=00255077836266642015:u-scht7a-8i |
filter | |||||||
---|---|---|---|---|---|---|---|
说明 | 可选。filter 参数可以启用或停用 Google 搜索结果的自动过滤功能。如需详细了解 Google 的搜索结果过滤器,请参阅本文档的自动过滤部分。
注意:默认情况下,Google 会对所有搜索结果应用过滤功能,以提高这些结果的质量。 |
||||||
示例 | q=google&filter=0 |
gl | |
---|---|
说明 | 可选。 在 WebSearch 请求中指定 |
示例 | 此请求会提升在英国撰写的文档的 WebSearch 结果: |
hl | |
---|---|
说明 | 可选。 如需了解详情,请参阅国际化查询和结果呈现的界面语言部分;如需了解受支持语言的列表,请参阅支持的界面语言。 |
示例 | 此请求定位到法语葡萄酒广告。(Vin 在法语中意为葡萄酒。) q=vin&ip=10.10.10.10&ad=w5&hl=fr |
高清 | |
---|---|
说明 | 可选。 |
示例 | 此请求搜索“披萨”和“奶酪”。该表达式与
|
ie | |
---|---|
说明 | 可选。 有关何时可能需要使用此参数的讨论,请参阅字符编码部分。 如需查看可能的 |
示例 | q=google&ie=utf8&oe=utf8 |
lr | |
---|---|
说明 | 可选。 Google WebSearch 通过分析以下各项来确定文档的语言:
如需查看此参数的有效值列表,请参阅语言 ( |
示例 | q=Frodo&lr=lang_en |
num | |
---|---|
说明 | 可选。
注意:如果搜索结果总数少于请求的结果数,将返回所有可用的搜索结果。 |
示例 | q=google&num=10 |
oe | |
---|---|
说明 | 可选。 有关何时可能需要使用此参数的讨论,请参阅字符编码部分。 如需查看可能的 |
示例 | q=google&ie=utf8&oe=utf8 |
output | |||||||
---|---|---|---|---|---|---|---|
说明 | 强制要求。
|
||||||
示例 | output=xml_no_dtd |
q | |
---|---|
说明 | 可选。 还有许多特殊查询字词可用作 Google 搜索控制台包含使用 注意:为 q 参数指定的值必须经过网址转义。 |
示例 | q=vacation&as_oq=london+paris |
安全 | |||||||||
---|---|---|---|---|---|---|---|---|---|
说明 | 可选。
如需详细了解此功能,请参阅使用安全搜索功能过滤成人内容部分。 |
||||||||
示例 | q=adult&safe=high |
start | |
---|---|
说明 | 可选。
|
示例 | start=10 |
sort | |
---|---|
说明 | 可选。 |
示例 |
|
ud | |
---|---|
说明 | 可选。 http://www.花井鮨.com 此参数的有效值为 如果 http://www.xn--elq438j.com. 注意:这是一项 Beta 版功能。 |
示例 | q=google&ud=1 |
高级搜索
图片下方列出的其他查询参数与高级搜索查询相关。 当您提交高级搜索时,多个参数的值(例如 as_eq、as_epq、as_oq 等)都会纳入该搜索的查询字词中。此图片显示了 Google 的“高级搜索”页面。在该图片上,每个高级搜索参数的名称都以red文本写在与该参数相对应的网页上的字段内部或旁边。
![](https://services.google.com/images/as_examples/advanced_search.jpg?authuser=1&hl=da)
高级搜索查询参数
as_dt | |
---|---|
说明 | 可选。 |
示例 | as_dt=i,as_dt=e |
as_epq | |
---|---|
说明 | 可选。 |
示例 | as_epq=abraham+lincoln |
as_eq | |
---|---|
说明 | 可选。 |
示例 |
|
as_lq | |
---|---|
说明 | 可选。 |
示例 |
|
as_nlo | |
---|---|
说明 | 可选。 |
示例 | 以下命令将搜索范围设置为 5 到 10(含 5 和 10):
|
as_nhi | |
---|---|
说明 | 可选。 |
示例 | 以下命令将搜索范围设置为 5 到 10(含 5 和 10):
|
as_oq | |
---|---|
说明 | 可选。 |
示例 |
|
as_q | |
---|---|
说明 | 可选。 |
示例 |
|
as_qdr | |
---|---|
说明 | 可选。
|
示例 |
以下示例请求的是过去一年的结果:
以下示例请求的是过去 10 天内的结果:
|
as_sitesearch | |
---|---|
说明 | 可选。借助 |
示例 |
|
特殊查询字词
Google WebSearch 允许使用一些特殊查询字词,以便访问 Google 搜索引擎的其他功能。这些特殊查询字词应包含在 q 请求参数的值中。与其他查询字词一样,特殊查询字词必须进行网址转义。一些特殊查询字词包含冒号 (:)。该字符还必须经过网址转义;其网址转义值为 %3A
。
反向链接 [link:] | |
---|---|
说明 |
您还可以使用 as_lq 请求参数提交 注意:使用 |
示例 |
|
布尔值 OR 搜索 [ OR ] | |
---|---|
说明 |
您还可以使用 as_oq 请求参数提交对一组字词中的任意字词的搜索。 注意:如果搜索请求指定查询“伦敦+OR+巴黎”,则搜索结果将包括至少包含这两个单词中一个词的文档。在某些情况下,搜索结果中的文档可能会同时包含这两个字词。 |
示例 | 搜索伦敦或巴黎: 用户输入:
london OR
paris 查询字词:q=london+OR+paris 搜索假期以及伦敦或巴黎: 查询字词:
q=vacation+london+OR+paris 搜索“度假”和“伦敦”、“巴黎”或“巧克力”之一: 查询字词:
q=vacation+london+OR+paris+OR+chocolates 搜索“度假”和“巧克力”,以及“北京”或“北京”,权重最低的巧克力: 查询字词:
q=vacation+london+OR+paris+chocolates 在同时包含伦敦或巴黎的文档中搜索度假、巧克力和鲜花: 查询字词:
q=vacation+london+OR+paris+chocolates+flowers 您可以搜索“度假”和“伦敦”或“巴黎”,还可以搜索“巧克力”或“花”: 查询字词: q=vacation+london+OR+paris+chocolates+OR+flowers |
排除查询字词 [-] | |
---|---|
说明 | 排除 (
当搜索字词具有多种含义时,排除查询字词非常有用。例如,“bass”一词可以返回关于鱼类或音乐的结果。如果您要查找有关鱼类的文档,可以使用排除查询字词从搜索结果中排除与音乐有关的文档。 您还可以使用 as_eq 请求参数从搜索结果中排除与特定字词或短语匹配的文档。 |
示例 | 用户输入: bass -music 查询字词: q=bass+%2Dmusic |
文件类型排除 [ -filetype: ] | |
---|---|
说明 |
注意:您可以在查询中添加更多 Google 支持的文件类型包括:
日后我们可能会添加更多文件类型。您可以随时通过 Google 的文件类型常见问题解答找到最新列表。 |
示例 | 以下示例返回提及“Google”但并非 PDF 文档的文档: 以下示例返回提及“Google”但排除 PDF 和 Word 文档的文档: |
文件类型过滤 [ filetype: ] | |
---|---|
说明 |
您可以在查询中添加更多 默认情况下,搜索结果将包含带有任意文件扩展名的文档。 Google 支持的文件类型包括:
日后我们可能会添加更多文件类型。您可以随时通过 Google 的文件类型常见问题解答找到最新列表。 |
示例 | 以下示例会返回提及“Google”的 PDF 文档: 以下示例返回提及“Google”的 PDF 和 Word 文档: |
包含查询字词 [+] | |
---|---|
说明 | 包含 (+) 查询字词指定搜索结果中包含的所有文档都必须包含某个字词或词组。如需使用包含查询字词,请在所有搜索结果中必须包含的字词或词组前面都加上“+”(一个加号)。
在识别搜索结果之前,您应在 Google 通常会舍弃的常见字词前面使用 |
示例 | 用户输入: Star Wars Episode +I 查询字词: q=Star+Wars+Episode+%2BI |
仅链接搜索,所有字词 [ allinlinks: ] | |
---|---|
说明 |
如果您的搜索查询包含
|
示例 | 用户输入:allinlinks: Google search 查询字词: q=allinlinks%3A+Google+search |
词组搜索 | |
---|---|
说明 | 使用词组搜索 (") 查询字词,您可以将词组用引号括起来或用连字符连接起来,从而搜索完整词组。
如果您要搜索名言佳句或专有名词,词组搜索尤其有用。 您还可以使用 as_epq 请求参数提交短语搜索。 |
示例 | 用户输入:"Abraham Lincoln" 查询字词: q=%22Abraham+Lincoln%22 |
纯文字搜索,所有字词 [allintext:] | |
---|---|
说明 |
如果您的搜索查询包含
|
示例 | 以下示例指定搜索结果中包含的所有文档的正文中必须包含“Google”和“search”这两个字词: 用户输入: allintext:Google search 查询字词: q=allintext%3AGoogle+search |
标题搜索,单个字词 [intitle:] | |
---|---|
说明 |
注意:您可以指定必须包含在文档标题中的多个单词,只需在每个单词前面加上
|
示例 | 此示例指定搜索结果中的所有文档的标题中必须出现“Google”一词,并且“搜索”一词必须出现在这些文档的标题、网址、链接或正文中的任意位置: |
标题搜索,所有字词 [allintitle:] | |
---|---|
说明 |
注意:在搜索查询的开头放置
|
示例 | 以下示例指定搜索结果中任何文档的标题中必须出现“Google”和“搜索”这两个词: |
网址搜索,单个字词 [inurl:] | |
---|---|
说明 |
|
示例 | 此示例指定搜索结果中的所有文档的网址中都必须出现“Google”一词,并且“搜索”一词必须出现在这些文档的标题、网址、链接或正文中的任意位置: |
网址搜索,所有字词 [allinurl:] | |
---|---|
说明 |
|
示例 | 以下示例指定搜索结果中的所有文档的网址中都必须包含“Google”和“搜索”字样: |
网络文档信息 [info:] | |
---|---|
说明 | 只要网址包含在 Google 的搜索索引中,
注意:使用 |
示例 | 用户输入: info:www.google.com 查询字词: q=info%3Awww.google.com |
图片查询示例
以下示例显示了几个图片 HTTP 请求,以说明如何使用不同的查询参数。本文档的“图片查询参数定义”部分提供了各种查询参数的定义。
此请求要求查询查询字词“monkey”(q=monkey
)(文件类型为 .png)的前 5 个结果 (start=0&num=5
)。最后,该查询会指定 client
、output
和 cx
参数的值,这三个都是必需参数。
http://www.google.com/cse? searchtype=image start=0 &num=5 &q=monkey &as_filetype=png &client=google-csbe &output=xml_no_dtd &cx=00255077836266642015:u-scht7a-8i
图片搜索查询参数
as_filetype | |
---|---|
说明 | 可选。返回指定类型的图片。允许使用的值包括: |
示例 | q=google&as_filetype=png |
imgsz | |
---|---|
说明 | 可选。返回指定尺寸的图片,其尺寸可以是以下其中一项:
|
示例 | q=google&as_filetype=png&imgsz=icon |
图片类型 | |
---|---|
说明 | 可选。返回以下某个类型的图片:
|
示例 | q=google&as_filetype=png&imgtype=photo |
图片代码 | |
---|---|
说明 | 可选。返回黑白、灰度或彩色图片:
|
示例 | q=google&as_filetype=png&imgc=gray |
图片颜色 | |
---|---|
说明 | 可选。返回特定主色的图片:
|
示例 | q=google&as_filetype=png&imgcolor=yellow |
as_rights | |
---|---|
说明 | 可选。基于许可的过滤条件。支持的值包括:
|
示例 | q=cats&as_filetype=png&as_rights=cc_attribute |
请求限制
下表列出了您发送给 Google 的搜索请求的相关限制:
组件 | 限值 | 备注 |
---|---|---|
搜索请求长度 | 2048 字节 | |
查询字词数量 | 10 | 在以下参数中包含字词:q、as_epq、as_eq、as_lq、as_oq、as_q |
结果数量 | 20 | 如果您将 num 参数设置为大于 20 的数字,则仅返回 20 个结果。若要获得更多结果,您需要发送多个请求,并随着每个请求增加 start 参数的值。 |
国际化查询和结果呈现
您可以通过 Google WebSearch 服务搜索多种语言的文档。您可以指定应该用来解读 HTTP 请求和对 XML 响应进行编码的字符编码(使用 ie 和 oe 搜索参数)。您还可以过滤结果,以仅包含使用特定语言编写的文档。
以下部分讨论了与使用多种语言进行搜索相关的问题:
字符编码
服务器以编码字节序列的形式向用户代理(例如浏览器)发送数据(例如网页)。然后,用户代理会将字节解码为字符序列。向 WebSearch 服务发送请求时,您可以为搜索查询和收到的 XML 响应指定编码方案。
您可以使用 ie 请求参数为 HTTP 请求中的字符指定编码机制。您也可以使用 oe 参数指定 Google 对 XML 响应进行编码时应使用的编码方案。如果您使用的编码方案不是 ISO-8859-1
(或 latin1
),请确保为 ie 和 oe 参数指定正确的值。
注意:如果您要提供多种语言的搜索功能,我们建议您对 ie 和 oe 参数使用 utf8
(UTF-8) 编码值。
有关可用于 ie 和 oe 参数的值的完整列表,请参阅字符编码方案附录。
有关字符编码的更多常规信息,请参阅 http://www.w3.org/TR/REC-html40/charset.html。
界面语言
您可以使用 hl 请求参数来标识图形界面的语言。hl 参数值可能会影响 XML 搜索结果,尤其是在未明确指定语言限制(使用 lr 参数)时的国际查询上。在这种情况下,hl 参数可能会以与用户输入语言相同的语言显示搜索结果。
我们建议您在搜索结果中明确设置 hl 参数,以确保 Google 为每个查询选择最优质的搜索结果。
如需查看 hl 参数的有效值的完整列表,请参阅支持的接口语言部分。
搜索以特定语言编写的文档
您可以使用 lr 请求参数限制搜索结果,使其仅显示使用特定语言或一组语言编写的文档。
lr 参数支持布尔值运算符,以便您指定搜索结果中应包含(或排除)的多种语言。
以下示例展示了如何使用布尔值运算符请求不同语言的文档。
对于以日语撰写的文档:
lr=lang_jp
对于以意大利语或德语撰写的文档:
lr=lang_it|lang_de
对于非匈牙利语或捷克语的文件:
lr=(-lang_hu).(-lang_cs)
有关 lr 参数可能值的完整列表,请参阅语言集合值部分;有关使用这些运算符的完整讨论,请参阅布尔值运算符部分。
简体中文和繁体中文搜索
简体中文和繁体中文是中文的两种书写变体。相同的概念在每个变体中的编写方式可能有所不同。给定其中一个变体中的查询后,Google WebSearch 服务可以返回同时包含这两个变体中的网页的结果。
要使用此功能,需要满足以下前提条件:
以下示例展示了您将在简体中文和繁体中文结果请求中包含的查询参数。(请注意,该示例未包含其他必需信息,例如客户端。)
search?hl=zh-CN &lr=lang_zh-TW|lang_zh-CN &c2coff=0
过滤结果
Google WebSearch 提供了多种搜索结果过滤方式:
自动过滤搜索结果
为了尽可能提供最佳搜索结果,Google 会使用以下两种技术自动过滤通常被视为不合适的搜索结果:
-
重复内容 - 如果多个文档包含相同的信息,搜索结果中只会包含这组文档中最相关的文档。
-
主机挤压 - 如果有多个搜索结果来自同一网站,Google 可能不会显示来自该网站的所有结果,或者这些结果在
中的排名可能会低于原本显示的排名。
我们建议您针对一般搜索请求保持这些过滤器启用状态,因为这些过滤器可显著提高大多数搜索结果的质量。不过,您可以在搜索请求中将 filter 查询参数设置为 0,从而绕过这些自动过滤器。
语言和国家/地区过滤
Google WebSearch 服务会返回所有 Web 文档的主索引中的结果。主索引包含按特定属性(包括语言和来源国家/地区)分组的文档子集合。
您可以使用 lr 和 cr 请求参数将搜索结果分别限制为使用特定语言编写或来自特定国家/地区的文档的子集合。
Google WebSearch 通过分析以下各项来确定文档的语言:
- 文档网址的顶级域名 (TLD)
- 文档中的语言元标记
- 文档正文中使用的主要语言
另请参阅 lr 参数的定义、有关搜索以特定语言编写的文档的部分,以及可用作 lr 参数值的语言集合值,详细了解如何根据语言限制结果。
Google WebSearch 通过分析以下各项来确定文档所在的国家/地区:
- 文档网址的顶级域名 (TLD)
- Web 服务器 IP 地址的地理位置
如需详细了解如何按出发国家/地区限制结果,另请参阅 cr 参数的定义以及可用作 cr 参数值的国家/地区集合值。
注意:您可以结合使用语言值和国家/地区值来自定义搜索结果。例如,您可以请求来自法国或加拿大的法语文档,或者请求来自荷兰但不英语的文档。lr 和 cr 参数均支持布尔值运算符。
使用安全搜索功能过滤成人内容
许多 Google 客户不想显示包含成人内容的网站的搜索结果。借助我们的安全搜索过滤器,您可以过滤掉包含成人内容的搜索结果并将它们消除。 Google 的过滤器使用专有技术来检查关键字、词组和网址。虽然任何过滤器都无法做到百分之百准确,但安全搜索功能可以从搜索结果中滤除绝大多数成人内容。
Google 会持续抓取网页并整合用户建议更新,以尽可能提供最新、最全面的安全搜索。
安全搜索功能支持以下语言:
荷兰语 英语 法语 德语 |
意大利语 葡萄牙语(巴西) 西班牙语 繁体中文 |
您可以使用 safe 查询参数调整 Google 针对成人内容过滤搜索结果的程度。 下表介绍了 Google 的安全搜索设置以及这些设置将如何影响您的搜索结果:
安全搜索级别 | 说明 |
---|---|
高价 | 启用更严格的安全搜索版本。 |
medium | 屏蔽包含色情内容和其他露骨色情内容的网页。 |
关闭 | 不会从搜索结果中滤除成人内容。 |
* 默认的安全搜索设置为关闭。
如果您已启用安全搜索功能,并且在搜索结果中发现包含冒犯性内容的网站,请将网站网址通过电子邮件发送至 safesearch@google.com,我们会调查该网站。
XML 结果
Google XML 结果 DTD
Google 使用相同的 DTD 来描述所有类型的搜索结果的 XML 格式。许多标记和属性适用于所有搜索类型。但是,某些标记仅适用于特定搜索类型。因此,DDD 中的定义可能比本文档中提供的定义没有严格限制。
本文档介绍了与 WebSearch 相关的 DTD 的这些方面。查看 DTD 时,如果您使用的是 WebSearch,则可以放心地忽略此处未记录的标记和属性。如果 DTD 和文档的定义不同,本文档会对此进行说明。
Google 可以返回 XML 结果,无论是否引用最新的 DTD。DTD 是帮助搜索管理员和 XML 解析器理解 Google 的 XML 结果的指南。由于 Google 的 XML 语法可能会不时发生变化,因此您不应将解析器配置为使用 DTD 来验证每个 XML 结果。
此外,您不应将 XML 解析器配置为在每次提交搜索请求时都提取 DTD。Google 更新 DTD 的频率较低,因此这些请求会产生不必要的延迟和带宽要求。
Google 建议您使用 xml_no_dtd 输出格式获取 XML 结果。 如果您在搜索请求中指定 xml output 格式,唯一的区别就是在 XML 结果中包含了以下行:
<!DOCTYPE GSP SYSTEM "google.dtd">
您可以访问 http://www.google.com/google.dtd 访问最新的 DTD。
请注意,DDD 中的部分功能目前可能不可用或不受支持。
关于 XML 响应
- 除非 XML 标记定义中另有说明,否则所有元素值都是适合显示的有效 HTML。
- 某些元素值是需要经过 HTML 编码才能显示的网址。
- 您的 XML 解析器应忽略未记录的属性和标记。 这样一来,如果 Google 向 XML 输出添加更多功能,您的应用无需修改便可继续运行。
- 某些字符作为值包含在 XML 标记中时,必须进行转义。您的 XML 处理器应该将这些实体转换回适当的字符。如果您没有正确转换实体,例如,浏览器可能会将 & 字符呈现为“&”。
XML 标准记录了这些字符;这些字符在下表中重现:
角色 转义形式 实体 字符代码 & 符号 & & &; 单引号 ' ' ' 双引号 " " "; 大于号 > > >; 小于号 < < <
常规和高级搜索查询的 XML 结果
常规/高级搜索:示例查询和 XML 结果
此示例 WebSearch 请求请求 10 条关于搜索字词“socer”(q=socer
) 的结果 (num=10
),“socer”一词在本示例中本来被特意拼写有误。
http://www.google.com/search?
q=socer
&hl=en
&start=10
&num=10
&output=xml
&client=google-csbe
&cx=00255077836266642015:u-scht7a-8i
此请求会生成以下 XML 结果。请注意,XML 结果中有几条注释,用于表示结果中未包含的某些标记的出现位置。
<?xml version="1.0" encoding="ISO-8859-1" standalone="no" ?>
<GSP VER="3.2">
<TM>0.452923</TM>
<Q>socer</Q>
<PARAM name="cx" value="00255077836266642015:u-scht7a-8i" original_value="00255077836266642015%3Au-scht7a-8i"/>
<PARAM name="hl" value="en" original_value="en"/>
<PARAM name="q" value="socer" original_value="socer"/>
<PARAM name="output" value="xml" original_value="xml"/>
<PARAM name="client" value="google-csbe" original_value="google-csbe"/>
<PARAM name="num" value="10" original_value="10"/>
<Spelling>
<Suggestion q="soccer"><b><i>soccer</i></b></Suggestion>
</Spelling>
<Context>
<title>Sample Vacation CSE</title>
<Facet>
<FacetItem>
<label>restaurants</label>
<anchor_text>restaurants</anchor_text>
</FacetItem>
<FacetItem>
<label>wineries</label>
<anchor_text>wineries</anchor_text>
</FacetItem>
</Facet>
<Facet>
<FacetItem>
<label>golf_courses</label>
<anchor_text>golf courses</anchor_text>
</FacetItem>
</Facet>
<Facet>
<FacetItem>
<label>hotels</label>
<anchor_text>hotels</anchor_text>
</FacetItem>
</Facet>
<Facet>
<FacetItem>
<label>nightlife</label>
<anchor_text>nightlife</anchor_text>
</FacetItem>
</Facet>
<Facet>
<FacetItem>
<label>soccer_sites</label>
<anchor_text>soccer sites</anchor_text>
</FacetItem>
</Facet>
</Context>
<RES SN="1" EN="10">
<M>6080</M>
/*
* The FI tag after the comment indicates that the result
* set has been filtered. If the number of results were exact, the
* FI tag would be replaced by an XT tag in the same format.
*/
<FI />
<NB>
/*
* Since the request is for the first page of results, the PU tag,
* which contains a link to the previous page of search results,
* is not included in this XML result. If the sample result did include
* a previous page of results, it would be listed here, in the same format
* as the NU tag on the following line
*/
<NU>/search?q=socer&hl=en&lr=&ie=UTF-8&output=xml&client=test&start=10&sa=N</NU>
</NB>
<R N="1">
<U>http://www.soccerconnection.net/</U>
<UE>http://www.soccerconnection.net/</UE>
<T>SoccerConnection.net</T>
<CRAWLDATE>May 21, 2007</CRAWLDATE>
<S><b>soccer</b>; players; coaches; ball; world cup;<b>...</b></S>
<Label>transcodable_pages</Label>
<Label>accessible</Label>
<Label>soccer_sites</Label>
<LANG>en</LANG>
<HAS>
<DI>
<DT>SoccerConnection.net</DT>
<DS>Post your <b>soccer</b> resume directly on the Internet.</DS>
</DI>
<L/>
<C SZ="8k" CID="kWAPoYw1xIUJ"/>
<RT/>
</HAS>
</R>
/*
* The result includes nine more results, each enclosed by an R tag.
*/
</RES>
</GSP>
常规/高级搜索:XML 标记
常规搜索请求的 XML 响应和高级搜索请求的 XML 响应均使用相同的一组 XML 标记。这些 XML 标记显示在上面的 XML 示例中,并在下面的表格中进行了说明。
以下 XML 标记按标记名称的字母顺序列出,每个标记定义都包含标记的说明、一个展示标记在 XML 结果中的显示方式以及标记内容格式的示例。如果该标记是另一个 XML 标记的子标记,或者该标记自身具有子标记或属性,则该标记的定义表中也会提供这些信息。
在下面的定义中,某些符号可能会显示在某些子标记旁边。这些符号及其含义如下:
* = 子标记的零个或多个实例
+ = 子标记的一个或多个实例
答案 | B | C | D | F | G | H | 左 | M | N | P | 问题 | R | 巧妙 | T | U | X |
anchor_text | |
---|---|
定义 | <anchor_text> 标记指定您应向用户显示的文本,以便标识与搜索结果集相关联的优化标签。由于优化标签会将非字母数字字符替换为下划线,因此您不应在界面中显示 <label> 标记的值。您应改为显示 <anchor_text> 标记的值。 |
示例 | <anchor_text>高尔夫球场</anchor_text> |
父标记 | FacetItem |
内容形式 | 文字 |
BLOCK | |
---|---|
定义 | 此标记将代码块的内容封装在推广结果的正文行中。每个块都有子标记 T、U 和 L。非空 T 标记表示该块包含文本;非空 U 和 L 标记表示该块包含链接(在 U 子标记中指定网址,在 L 子标记中指定定位文本)。 |
子标记 | T、U、L |
父标记 | BODY_LINE |
内容形式 | 空 |
BODY_LINE | |
---|---|
定义 | 此标记用于封装提升的结果正文中某一行的内容。每行正文都由几个 BLOCK 标记组成,要么包含一些文字,要么包含一个带有网址和定位文字的链接。 |
子标记 | 屏蔽* |
父标记 | SL_MAIN |
内容形式 | 空 |
C | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
定义 | <C> 标记表示 WebSearch 服务可以检索此搜索结果网址的缓存版本。您无法通过 XML API 检索缓存的网页,但可以将用户重定向到 www.google.com 获取此内容。 |
|||||||||
属性 |
|
|||||||||
示例 | <C SZ="6k" CID="kvOXK_cYSSgJ" /> | |||||||||
父标记 | HAS | |||||||||
内容形式 | 空 |
C2C | |
---|---|
定义 | <C2C> 标记表示结果引用了繁体中文网页。仅当启用简体中文和繁体中文搜索时,此标记才会显示。如需详细了解如何启用和停用此功能,请参阅 c2coff 查询参数定义。 |
内容形式 | 文字 |
上下文 | |
---|---|
定义 | <Context> 标记封装与一组搜索结果相关联的优化标签列表。 |
示例 | <Context> |
子标记 | title、Facet+ |
内容形式 | 容器 |
抓取日期 | |
---|---|
定义 | <CRAWLDATE> 标记用于标识上次抓取该网页的日期。系统不会为每个搜索结果页返回 |
示例 | <CRAWLDATE>2005 年 5 月 21 日</CRAWLDATE> |
父标记 | R |
内容形式 | 文字 |
DI | |
---|---|
定义 | <DI> 标记封装单个搜索结果的开放式目录管理系统 (ODP) 类别信息。 |
示例 | <DI> |
子标记 | DT?、DS? |
父标记 | HAS |
内容形式 | 空 |
DS | |
---|---|
定义 | <DS> 标记提供为 ODP 目录中的单个类别列出的摘要。 |
示例 | <DS>直接在互联网上发布您的足球简历。</DS> |
父标记 | DI |
内容形式 | 文本(可能包含 HTML) |
DT | |
---|---|
定义 | <DT> 标记用于为 ODP 目录中列出的单个类别提供标题。 |
示例 | <DT>SoccerConnection.net</DT> |
父标记 | DI |
内容形式 | 文本(可能包含 HTML) |
商品详情 | |
---|---|
定义 | <Facet> 标记包含 <FacetItem> 标记的逻辑分组。您可以使用可编程搜索引擎 XML 规范格式创建这些分组。如果您不创建这些分组,则 results_xml_tag_Context><Context> 标记最多包含四个 <Facet> 标记。每个 <Facet> 标记中的项将出于显示目的进行分组,但可能没有逻辑关系。 |
示例 | <Facet> |
子标记 | FacetItem+、title+ |
父标记 | 上下文 |
内容形式 | 容器 |
FacetItem | |
---|---|
定义 | <FacetItem> 标记包含与一组搜索结果关联的优化标签的相关信息。 |
示例 | <FacetItem> |
子标记 | label、anchor_text+ |
父标记 | 商品详情 |
内容形式 | FacetItem |
芬兰 | |
---|---|
定义 | <FI> 标记充当一个标记,指示是否针对搜索执行文档过滤。如需详细了解 Google 的搜索结果过滤器,请参阅本文档的自动过滤部分。 |
示例 | <FI /> |
父标记 | 反抗军 |
内容形式 | 空 |
Gmail 赞助广告 | |||||||
---|---|---|---|---|---|---|---|
定义 | <GSP> 标记封装 Google XML 搜索结果中返回的所有数据。“GSP”是“Google 搜索协议”的缩写。 |
||||||
属性 |
|
||||||
示例 | <GSP VER="3.2"> | ||||||
子标记 | PARAM+、Q、RES?、TM | ||||||
内容形式 | 空 |
HAS | |
---|---|
定义 | <HAS> 标记封装特定网址所支持的任何特殊搜索请求参数的相关信息。
注意:与 DTD 相比,WebSearch 的 <HAS> 定义的限制性更强。 |
子标记 | DI?L?、C?、RT? |
父标记 | R |
IS网址 | |
---|---|
定义 | 如果关联的搜索查询是网址,Google 会返回 <ISURL> 标记。 |
父标记 | Gmail 赞助广告 |
内容形式 | 空 |
L | |
---|---|
定义 | <L> 标记的存在表明 WebSearch 服务可以找到链接到此搜索结果网址的其他网站。要查找这些网站,您可以使用 link: 特殊查询字词。 |
父标记 | HAS |
内容形式 | 空 |
标签 | |
---|---|
定义 | <label> 标记指定优化标签,可用于过滤您收到的搜索结果。要使用优化标签,请将字符串 more:[[label tag value]] 添加到您向 Google 发送的 HTTP 请求中 q 参数的值,如以下示例所示。请注意,在向 Google 发送查询之前,必须对此值进行网址转义。 This example uses the refinement label golf_courses to 注意:<label> 标记与 <Label> 标记不同,后者用于标识与搜索结果中的特定网址相关联的优化标签。 |
示例 | <label>高尔夫课程</label> |
父标记 | FacetItem |
内容形式 | 文字 |
语言 | |
---|---|
定义 | <LANG> 标记包含 Google 对搜索结果语言的推测。 |
示例 | <LANG>en</LANG> |
父标记 | R |
内容形式 | 文字 |
M | |
---|---|
定义 | <M> 标记用于标识搜索结果的估计总数。 注意 :此估算值可能不准确。 |
示例 | <M>16200000</M> |
父标记 | 反抗军 |
内容形式 | 文字 |
新生儿 | |
---|---|
定义 | <NB> 标记封装结果集的导航信息,即指向搜索结果下一页或上一页搜索结果的链接。 注意:只有当更多结果可用时,才会显示此标记。 |
示例 | <NB> |
子标记 | NU?、PU? |
父标记 | 反抗军 |
内容形式 | 空 |
NU | |
---|---|
定义 | <NU> 标记包含指向下一页搜索结果的相对链接。 |
示例 | <NU>/search?q=flowers&num=10&hl=zh-CN&ie=UTF-8 &output=xml&client=test&start=10</NU> |
父标记 | NB |
内容形式 | 文本(相对网址) |
PARAM | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
定义 | <PARAM> 标记用于标识在与 XML 结果关联的 HTTP 请求中提交的输入参数。参数的相关信息包含在标记属性(name、value、original_value)中,对于 HTTP 请求中提交的每个参数,我们都会有一个 PARAM 标记。 |
||||||||||||
属性 |
|
||||||||||||
示例 | <PARAM name="cr" value="countryNZ" original_value="countryNZ" /> | ||||||||||||
父标记 | Gmail 赞助广告 | ||||||||||||
内容形式 | 复杂 |
处理单元 (PU) | |
---|---|
定义 | <PU> 标记提供指向搜索结果上一页的相对链接。 |
示例 | <PU>/search?q=flowers&num=10&hl=zh-CN&output=xml &client=test&start=10</PU> |
父标记 | NB |
内容形式 | 文本(相对网址) |
Q | |
---|---|
定义 | <Q> 标记用于标识在与 XML 结果关联的 HTTP 请求中提交的搜索查询。 |
示例 | <Q>pizza</Q> |
父标记 | Gmail 赞助广告 |
内容形式 | 文字 |
R | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
定义 | <R> 标记可封装单个搜索结果的详细信息。 注意:与 DTD 相比,WebSearch 的 <R> 标记的定义更加严格。 |
|||||||||
属性 |
|
|||||||||
子标记 | U、UE、T?、CRAWLDATE、S?、LANG?、HAS | |||||||||
父标记 | 反抗军 |
反抗军 | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
定义 | <RES> 标记封装一组单独的搜索结果以及有关这些结果的详细信息。 |
|||||||||
属性 |
|
|||||||||
示例 | <RES SN="1" EN="10"> | |||||||||
子标记 | M、FI?、XT?、NB?、R* | |||||||||
父标记 | Gmail 赞助广告 | |||||||||
内容形式 | 空 |
南 | |
---|---|
定义 | <S> 标记包含搜索结果的摘录,其中以粗体突出显示查询字词。为了正确换行,摘录中会包含换行符。 |
示例 | <S>华盛顿(CNN)-- 旨在结束参议院与布什总统官选的争夺战,让 5 名提名候选人获得最终投票,同时保留“...<b>...” |
父标记 | R |
内容形式 | 文本 (HTML) |
SL_MAIN | |
---|---|
定义 | 此标记用于封装推广结果的内容。用于解析置顶结果。标题链接的定位文字和网址分别包含在 T 和 U 子标记中。正文文本和链接行包含在 BODY_LINE 子标记中。 |
子标记 | BODY_LINE*、T、U |
父标记 | SL_RESULTS |
内容形式 | 空 |
SL_RESULTS | |
---|---|
定义 | 提升的结果的容器代码。只要搜索结果中有宣传广告,就会出现上述任一搜索结果。SL_MAIN 子标记包含主要结果数据。 |
子标记 | SL_MAIN* |
父标记 | R |
内容形式 | 空 |
拼写 | |
---|---|
定义 | <Spelling> 标记封装了针对已提交查询的备用拼写建议。此标记仅出现在搜索结果的第一页上。拼写建议支持英语、中文、日语和韩语。 注意:Google 只会针对 gl 参数值为小写字母的查询返回拼写建议。 |
示例 | <Spelling> |
子标记 | 建议 |
父标记 | Gmail 赞助广告 |
内容形式 | 空 |
建议 | |||||||
---|---|---|---|---|---|---|---|
定义 | <Suggestion> 标记包含针对已提交查询的备用拼写建议。您可以根据该标记的内容向搜索用户提出其他拼写建议。 q 属性的值是可以用作查询字词的网址转义拼写建议。 | ||||||
属性 |
|
||||||
示例 | <Suggestion> - 足球 | ||||||
父标记 | 拼写 | ||||||
内容形式 | 文本 (HTML) |
T | |
---|---|
定义 | <T> 标记包含结果的标题。 |
示例 | <T>艾米西东海岸披萨店</T> |
父标记 | R |
内容形式 | 文本 (HTML) |
标题 | |
---|---|
定义 | 作为 <Context> 的子元素,<title> 标记包含可编程搜索引擎的名称。 作为 <Facet> 的子标记,<title> 标记用于为一组分面提供标题。 |
示例 | 作为 <Context>的子级:<title>My Search Engine</title> 作为 <Facet> 的子级:<title>facet title</title> |
父标记 | Context、Facet |
内容形式 | 文字 |
TM | |
---|---|
定义 | <TM> 标记用于标识返回搜索结果所需的服务器总时间(以秒为单位)。 |
示例 | <TM>0.100445</TM> |
父标记 | Gmail 赞助广告 |
内容形式 | 文本(浮点数) |
TT | |
---|---|
定义 | <TT> 标记用于提供搜索提示。 |
示例 | <TT>提示:对于大多数浏览器,按回车键生成的结果与点击“搜索”按钮的结果相同。<T>/i</TT> |
父标记 | Gmail 赞助广告 |
U | |
---|---|
定义 | <U> 标记提供搜索结果的网址。 |
示例 | <U>http://www.dominos.com/</U> |
父标记 | R |
内容形式 | 文本(绝对网址) |
UD | |
---|---|
定义 | <UD> 标记用于为搜索结果提供采用 IDN 编码(国际域名)的网址。该值允许使用本地语言显示域名。例如,经过 IDN 编码的网址 http://www.%E8%8A%B1%E4%BA%95.com 可能会被解码,显示为 http://www.花井鮨.com。只有包含 ud 参数的请求才会包含此 <UD> 标记。 注意:这是一项 Beta 版功能。 |
示例 | <UD>http://www.%E8%8A%B1%E4%BA%95.com/</UD> |
父标记 | R |
内容形式 | 文本(IDN 编码的网址) |
UE | |
---|---|
定义 | <UE> 标记提供搜索结果的网址。该值会经过网址转义,适合作为查询参数在网址中传递。 |
示例 | <UE>http://www.dominos.com/</UE> |
父标记 | R |
内容形式 | 文本(网址转义网址) |
XT | |
---|---|
定义 | <XT> 标记表示结果总数估算值(由 M 标记指定)实际上表示结果总数。如需了解详情,请参阅本文档的自动过滤部分。 |
示例 | <XT> |
父标记 | 反抗军 |
内容形式 | 空 |
图片搜索查询的 XML 结果
此示例图片请求请求 5 条关于搜索字词“monkey”(q=monkey) 的结果 (num=5)。
http://www.google.com/cse? searchtype=image &num=2 &q=monkey &client=google-csbe &output=xml_no_dtd &cx=00255077836266642015:u-scht7a-8i
此请求会生成以下 XML 结果。
<GSP VER="3.2"> <TM>0.395037</TM> <Q>monkeys</Q> <PARAM name="cx" value="011737558837375720776:mbfrjmyam1g" original_value="011737558837375720776:mbfrjmyam1g" url_<escaped_value="011737558837375720776%3Ambfrjmyam1g" js_escaped_value="011737558837375720776:mbfrjmyam1g"/> <PARAM name="client" value="google-csbe" original_value="google-csbe" url_escaped_value="google-csbe" js_escaped_value="google-csbe"/> <PARAM name="q" value="monkeys" original_value="monkeys" url_escaped_value="monkeys" js_escaped_value="monkeys"/> <PARAM name="num" value="2" original_value="2" url_escaped_value="2" js_escaped_value="2"/> <PARAM name="output" value="xml_no_dtd" original_value="xml_no_dtd" url_escaped_value="xml_no_dtd" js_escaped_value="xml_no_dtd"/> <PARAM name="adkw" value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A" original_value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A" url_escaped_value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A" js_escaped_value="AELymgUP4VYSok20wy9SeYczEZ5UXxpBmRsJH4oC4aXhVuZgwGKuponcNXjrYkkw2bRv1BylIm89ndJ-Q4vxvyW0tcbiqipcQC9op_cBG84T12WMvX8660A"/> <PARAM name="hl" value="en" original_value="en" url_escaped_value="en" js_escaped_value="en"/> <PARAM name="oe" value="UTF-8" original_value="UTF-8" url_escaped_value="UTF-8" js_escaped_value="UTF-8"/> <PARAM name="ie" value="UTF-8" original_value="UTF-8" url_escaped_value="UTF-8" js_escaped_value="UTF-8"/> <PARAM name="boostcse" value="0" original_value="0" url_escaped_value="0" js_escaped_value="0"/> <Context> <title>domestigeek</title> </Context> <ARES/> <RES SN="1" EN="2"> <M>2500000</M> <NB> <NU>/images?q=monkeys&num=2&hl=en&client=google-csbe&cx=011737558837375720776:mbfrjmyam1g&boostcse=0&output=xml_no_dtd &ie=UTF-8&oe=UTF-8&tbm=isch&ei=786oTsLiJaaFiALKrPChBg&start=2&sa=N </NU> </NB> <RG START="1" SIZE="2"/> <R N="1" MIME="image/jpeg"> <RU>http://www.flickr.com/photos/fncll/135465558/</RU> <U> http://farm1.static.flickr.com/46/135465558_123402af8c.jpg </U> <UE> http://farm1.static.flickr.com/46/135465558_123402af8c.jpg </UE> <T>Computer <b>Monkeys</b> | Flickr - Photo Sharing!</T> <RK>0</RK> <BYLINEDATE>1146034800</BYLINEDATE> <S>Computer <b>Monkeys</b> | Flickr</S> <LANG>en</LANG> <IMG WH="500" HT="305" IID="ANd9GcQARKLwzi-t4lpWi2AERV3kJb4ansaQzTn3MNDZR9fD_JDiktPKByKUBLs"> <SZ>88386</SZ> <IN/> </IMG> <TBN TYPE="0" WH="130" HT="79" URL="http://t0.gstatic.com/images?q=tbn:ANd9GcQARKLwzi- t4lpWi2AERV3kJb4ansaQzTn3MNDZR9fD_JDiktPKByKUBLs"/> </R> <R N="2" MIME="image/jpeg"> <RU> http://www.flickr.com/photos/flickerbulb/187044366/ </RU> <U> http://farm1.static.flickr.com/73/187044366_506a1933f4.jpg </U> <UE> http://farm1.static.flickr.com/73/187044366_506a1933f4.jpg </UE> <T> one. ugly. <b>monkey</b>. | Flickr - Photo Sharing! </T> <RK>0</RK> <BYLINEDATE>1152514800</BYLINEDATE> <S>one. ugly. <b>monkey</b>.</S> <LANG>en</LANG> <IMG WH="400" HT="481" IID="ANd9GcQ3Qom0bYbee4fThCQVi96jMEwMU6IvVf2b8K5vERKVw- EF4tQQnDDKOq0"><SZ>58339</SZ> <IN/> </IMG> <TBN TYPE="0" WH="107" HT="129" URL="http://t1.gstatic.com/images?q=tbn:ANd9GcQ3Qom0bYbee4fThCQ Vi96jMEwMU6IvVf2b8K5vERKVw-EF4tQQnDDKOq0"/> </R> </RES> </GSP>
图片搜索:XML 标记
下表显示了在图片搜索查询的 XML 响应中使用的其他 XML 标记。
在下面的定义中,某些符号可能会显示在某些子标记旁边。这些符号及其含义如下:
* = 子标记的零个或多个实例
+ = 子标记的一个或多个实例
RG | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
定义 | <RG> 标记包含单个图片搜索结果的详细信息。 |
|||||||||
属性 |
| |||||||||
父标记 | 反抗军 |
俄罗斯 | |
---|---|
定义 | <RU tag> 标记包含每张图片搜索结果的详细信息。 |
父标记 | R |