Google Web APIs 参考中文版

 

内容

1.  概况

1.1  搜索请求
1.2  缓冲请求
1.3  拼写请求

2.  搜索请求格式

2.1  搜索参数
2.2  查询条件
2.3  自动过滤
2.4  约束
2.5  输入输出编码
2.6  安全搜索
2.7  局限性

3. 搜索结果格式

3.1  搜索响应
3.2  结果元素
3.3  目录种类

---

1. 概况
Back to top

这篇文档详细解释了Google Web APIs函数语法的调用,你可以方便的使用Google Web APIs服务。在文档中，你会学习到以下几个方面:

• Google的查询语句是怎么工作的。
• 怎样约束你的查询去获得Google索引中的一部分，例如特殊的语言或国家。
• 怎样解释通过Google Web APIs服务反馈的搜索结果信息。

你也可以通过Google Web APIs开发者工具包文档来帮助你:

• GoogleSearch.wsdl - 描述Google Web APIs SOAP 接口的WSDL文件.
• soap-samples/ - SOAP 消息和响应的范例.
• javadoc/index.html - Java 库范例文档.

这是一个 beta版的文档. 如果你有任何意见,或者发现了错误，或者有疑问，请联系api-support@google.com .

1.1 搜索请求
Back to top

搜索请求会提交一个查询字符串和一组参数给Google Web APIs服务，并返回一组搜索结果。搜索结果来源于超过二十亿网页的Google索引。

涉及搜索请求的详细交互过程包含在这个文档的搜索请求格式 和 搜索结果格式 章节中。

1.2 缓冲请求
Back to top

缓冲请求会提交一个URL给Google Web APIs服务，并返回Google爬虫程序最后访问的页面的URL内容（如果是可用的话）。

请注意：Google既不是缓冲页面的作者，也不对那些内容负责。

缓冲页面的返回类型是base64编码文本.

1.3 拼写请求
Back to top

拼写请求会提交一个查询给Google Web APIs服务，并为查询返回一个拼写修正的建议（如果是可用的话）。 拼写修正模仿，其行为就像在Google网站上查找一样。

拼写请求服从和其他查询请求相同的查询字符串的限制 。（输入字符串最大为2048字节和10个单词）

拼写请求返回的类型是一个文本字符串。

---

2. 搜索请求格式
Back to top

2.1 搜索参数
Back to top

这个表格列出了所有的合法的名称和对应的值。这些名称和值能够用于一个搜索请求中，并描述了这些参数将怎样修改搜索结果。

名称

描述

key

由Google提供的，这是你访问Google服务所必需的。Google使用key来验证和记录。

q

(详见 查询条件 章节中的查询语法。)

start

基于零的第一个期望的搜索结果的索引.

maxResults

每次期望查询结果数，最大查询值为10。
注意: 如果你的查询结果没有更多的匹配项，真实的查询结果数可能小于你的请求数。

filter

激活或抑制自动结果过滤，隐藏非常相似的结果和所有来自相同网站主机的结果。 过滤往往是改进终端用户在Google上的使用体验。但是对于你（程序员）的应用程序来说，你最好把这个功能关了。(详见 自动过滤 章节)

restrict

限定在Google Web索引子集的搜索, 例如限定在一个叫'乌克兰'的国家中或者限定在'Linux'主题中 (详见 约束 章节.)

safeSearch
能够在搜索结果中过滤成人内容的一个布尔值. 详见 安全搜索 章节.

lr

语言限定- 限定在一种或多种语言的范围内的搜索.

ie

输入编码 - Google已经不赞成大家使用这个这个参数了，而且这个参数已经被忽视了。所有对API请求都必须是UTF-8编码。 (详见 输入和输出编码 章节)

oe

输出编码 - Google已经不赞成大家使用这个这个参数了，而且这个参数已经被忽视了。所有对API请求都必须是UTF-8编码。 (详见 输入和输出编码 章节)

2.2 查询条件 - <q>
Back to top

默认搜索

默认情况下, Google只返回所有符合那些字符串查询条件的页面。不必在查询条件中写逻辑关系'AND'。记住，查询条件的顺序会影响到搜索结果。

忽略的单词(stop words)

Google 忽略最普通的单词和字符，例如：'where' 和 'how' 以及单个的数字和字母。把最普通的单词忽略掉被称为“忽略的单词”(stop words)。

如果你想阻止Google把某些单词忽略掉，可以通过加双引号来解决，例如'to be or not to be'这个短语。

特殊字符

通常，所有非字母字符在搜索中会被当作分隔符来处理。

但以下情况除外: 双引号('), 加号(+), 减号或连字符(-), 以及＆符号(&). 

＆符号(&) 会被当作另一个包含在查询词条中字符来处理。 这个特例字符符合以下章节列出的搜索特性。

特殊查询词条

Google支持一些特殊的查询词条的使用，允许用户或搜索管理者去访问Google搜索引擎的附加功能。

特殊查询功能

查询范例

描述

包含查询词条
Star Wars Episode +I

如果一个普通的单词是你搜索所必需的，你就在这个单词前放上'+'号。 

排除查询词条
bass -music
你可以在那个要排除的单词前放上'-'号，这样就可以在搜索结果中去除这个单词。

短语搜索
'yellow pages'

如果要搜索一个完整的短语，可以通过加上双引号或用连字符连接这些单词来完成。词组用这种方法标注，在搜索结果中就会显示在一起，就像你输入的那样。

注意: 在一个短语中，你可能需要用'+'号来强制将普通的单词连接起来。

布尔 或（OR） 搜索
vacation london OR paris
Google搜索支持'OR'布尔操作，用大写OR来连接词条A和B，反馈的页面将既包含A又包含B。

网站限定搜索
admission site:www.stanford.edu

如果想要搜索的网站是你知道的那个网站，但是不确定是否有需要的信息在那个网站中，你能用google来指定只在这个网站中搜索。

搜索时，在查询词条后跟'site:' 然后写上主机名。

注意:排除操作符('-')号可运用到查询条件中,它所起到的作用是把某些网站从搜索描述中排除出去。
注意: 每次查询只支持一个site:

日期限定搜索
Star Wars daterange:2452122-2452234
如果你想限定搜索到的结果是在一个特殊的日期范围内发布的，那么你可以用 'daterange: '查询条件来完成它。 'daterange:' 查询条件必须用以下格式:

daterange:<start_date>-<end date>

其中

<start_date> =开始的时间（公历）
<end_date> = 结束的时间（公历）

公历日期是从公元前4713年1月1日开始计算的天数。 例如, 公历2001年8月1日天数为 2452122。

标题搜索(term)
intitle:Google search
如果你用'intitle:'来作为查询条件, Google搜索结果会限定在标题中。 注意在 'intitle:'和查询的单词之间没有空格。

注意: 将 'intitle:'放在每个你查询的单词前就等于将'allintitle:'放在你的查询条件前。

标题搜索(all)
allintitle: Google search
在查询条件前用 'allintitle:'，将限定其结果来自于在标题中包含所有查询条件的网站。

URL 搜索 (term)
inurl:Google search
如果你用 'inurl:'来作为查询条件 , Google 搜索结果会限定在URL中。 注意在 'inurl:' 和查询的单词之间没有空格。

注意: 'inurl:' 只作用在查询单词上 , 不作用在URL结构上。 特别是, 它会忽略标点符号，并忽略只用一个单词写在 'inurl:'后面的情况. 查询多个单词在URL中, 应为每一个单词都使用'inurl:'符号 。

注意: 将'inurl:'放在需要查询的每一个单词前就等于将'allinurl:' 放在需要查询的条件前

URL 搜索 (all)
allinurl: Google search
在查询条件前用'allinurl:' 将限定其结果来自于在URL中包含所有查询条件的网站。

注意: 'allinurl:'只作用在 查询单词上 , 不作用在URL结构上。特别是,它会忽略标点符号.  因此, 'allinurl: foo/bar' 将限定在包含具有'foo'和'bar'的URL的结果集中，但不会将包含字符串'foo/bar'（包括斜杠）的URL作为结果集，或者将其作为特殊的词序。目前没有方法强制这些约束。

纯文本搜索 (all)
allintext: Google search
在查询条件前用 'allintext:' 来限定那些满足所有查询单词的纯文本的结果， 忽略链接,URL,和标题匹配。

纯链接搜索 (all)
allinlinks: Google search
在查询条件前用 'allinlinks:'来限定那些满足所有查询单词，包含URL链接的页面。

文件类型过滤
Google filetype:doc OR filetype:pdf
前缀'filetype:' 前缀'filetype:'会立即反馈只包含指定扩展名的文档的查询结果。  注意：在'filetype:'和指定的扩展名之间没有空格。

注意: 通过增加更多的'filetype:' 来搜索出多种类型的文件。

文件类型排除
Google -filetype:doc -filetype:pdf
前缀'-filetype:'将排除掉指定扩展名的文档。  注意：在'-filetype:' 和指定的扩展名之间没有空格。

注意:通过增加更多的'-filetype:'来排除掉多种类型的文件。

网页文件信息
info:www.google.com
前缀'info:' 会根据指定的URL来返回单个结果（如果这个URL在索引中存在）。

注意:当使用这个特殊的查询条件时，不能使用其他指定的查询条件。

主页链接
link:www.google.com
前缀'link:' 列出连接到指定网页的所有网页。注意：在'link:' 和网页URL之间不能有空格.

注意:在使用这个查询方法的同时不能使用其他查询条件。

相关链接
related:www.google.com
前缀'related:'列出了与指定网页相似的网站页面。 注意：在 'link:' 和网页URL之间不能有空格。

注意:在使用这个查询方法的同时不能使用其他查询条件。

缓冲结果页面
cache:www.google.com web
前缀'cache:'会返回缓冲在google服务器中的HTML版本指定网页文档。（'Google搜索爬虫器'会将抓取的网页临时存储在google系统中。） 注意 在'cache:' 和网页URL之间不能有空格。

注意:如果你在查询中包含其他的关键字，Google将会在缓冲的文档中高亮显示。

2.3 自动过滤 - <filter>
Back to top

这个<filter> 参数会引起Google把搜索的结果再次过滤掉一些。这个是为有经验的用户准备的。但对于你的应用程序来说， 为了得到完整的搜索结果，你最好把这个过滤参数关闭。

当过滤参数打开的时候，过滤器会做以下工作：

• Near-Duplicate Content Filter = 如果重复的搜索结果包含同样的标题和内容片断，只会有一个结果会反馈回来。
• Host Crowding = 如果重复的搜索结果来自于同一个网站主机，那么只有前2个会反馈回来。

2.4 限定 - <lr> <restrict>
Back to top

Google 提供了一些功能，能搜索一些Google的网页索引预先确定的子集。 使用的参数就是lr 和 restrict 。

<lr> - 语言限定

在特殊的语言范围内搜索文档，可以使用<lr>参数,以下就是语言参数列表：

语言           <lr>值

阿拉伯语  lang_ar
冰岛语      lang_is

中文简体  lang_zh-CN
意大利语  lang_it

中文繁体  lang_zh-TW
日语        lang_ja

捷克语     lang_cs
韩语        lang_ko

丹麦语      lang_da
拉脱维亚语 lang_lv

荷兰语       lang_nl
立陶宛语    lang_lt

英语          lang_en
挪威语       lang_no

爱沙尼亚语 lang_et
葡萄牙语   lang_pt

芬兰语        lang_fi
波兰语       lang_pl

法语         lang_fr
罗马尼亚语 lang_ro

德语         lang_de
俄语         lang_ru

希腊语      lang_el
西班牙语   lang_es

希伯来语   lang_iw
瑞典语       lang_sv

匈牙利语     lang_hu
土耳其语    lang_tr

<restrict> - 国家和主题限定

Google允许你搜索一个或多个国家的网站信息 , 这是通过顶级域名服务和服务器IP地址所在的地理位置确定的。

自动的国家子集当前支持以下这些国家: (不列举了，详细信息请见：有关日志)

Google同时也有4个主题限定:

主题

<restrict>   值

美国政府      unclesam

Linux           linux

Macintosh     mac

FreeBSD        bsd

结合 <lr>和<restrict> 参数

使用lr和restrict参数的搜索请求支持布尔操作，见下表：(按优先级排序).

注意: 如果在搜索请求中同时使用lr和restrict参数，子集字符串将用'AND'逻辑结合起来。

布尔操作 范例  描述 :

布尔值 NOT [ - ]

-lang_fr

移除所有紧跟在'-'操作符后面的子集的结果。

范例中限定了所有的法语结果将会去除。

布尔值 AND [ . ]

linux.countryFR

反馈'.'操作符左右两端的子集的交集（intersection）的结果。

范例中限定了所有既是'linux'主题又是法国地区信息的结果集。

布尔值 OR [ | ]

lang_en|lang_fr

反馈'|'操作符两端子集的并集。

范例中限定了既是英语又是法语的，所有匹配的查询结果。

括号 [ ( ) ]

(linux).(-(conutryUK|countryUS))

在括号里面的一个子集字符串中的所有查询条件将会比括号外的先估算，使用括号来调整查询条件估算的顺序。

范例中 限定 了查询结果为：在Linux子集中但既不是美国地区信息子集又不是英国地区信息子集的所有结果。

注意:在限定参数中，空格是不允许的。

2.5 输入和输出编码 - <ie>, <oe>
为了支持在多语言和字符编码中搜索文档，Google Web APIs用UTF-8码来执行所有的请求和响应。 在客户端请求查询时，参数<ie>和<oe>是必须的，但值会被忽略。客户端应该把所有的请求数据编码成UTF-8码，同时期待结果集也是UTF-8码的形式。

2.6  安全搜索 - <safeSearch>
许多Google用户希望没有成人网站包含在搜索结果中， Google安全搜索特性 掩蔽了包含这种信息的网站，将其排除在搜索结果中。没有任何过滤方法是100%正确的，google过滤方法使用了先进的具有专利的技术，它能检查关键字，短语，URL和公开的目录分类。

如果你发现在你的搜索结果中的某些网站包含讨厌的内容，甚至涉及安全内容的，请将网站URL发送到safesearch@google.com，Google会进行调查。

2.7  限制
有一些重要的限制你是应该知道的，由于Google当前基础设施是为终端用户优化的，所以，将来我们希望为Google Web API开发者的提高限制等级。

结构                                限制

搜索请求长度                     2048 bytes

查询最大单词数                  10

最大site:条件数目                每次搜索请求1个

每次查询最大结果数            10

<start> + <maxResults>的最大值   1000

3. 搜索结果格式

3.1  搜索响应
每次你提出一个搜索请求给Google服务,会有一个响应反馈给你. 这章描述具体描述反馈值的含义.

<documentFiltering> - 一个布尔值,表示是否在搜索结果中执行过滤. 如果你请求过滤并过滤实际情况也发生了,这个值将是'true'.

<searchComments> - 显示给最终用户的一个文本字符串。 当你在搜索结果中发现有最普通的信息时,其实是让你注意:“被忽略的单词(stop words)”会自动从搜索中被删减掉。 (常见的有:'and'和'as'.')

<estimatedTotalResultsCount> - 注意:估计的数值可能高于或低于实际的结果数.
注意:估计的数值可能高于或低于实际的结果数.

<estimateIsExact> - 估计的数值实际存在.是布尔值.

<resultElements> - <resultElement>数组项,这个数组项符合真实的搜索结果列表.

<searchQuery> - 这是为搜索结果存在的 <q>值.

<startIndex> - 在<resultElements>中第一个搜索结果的索引，（索引是从1开始的）。

<endIndex> - 在<resultElements>中最后一个搜索结果的索引，（索引是从1开始的）。

<searchTips> - 为终端用户显示一串字符串，告诉终端用户一些使用Google的建议和技巧。

<directoryCategories> - 一个<directoryCategory>数组项. 这是为了让搜索符合 ODP（开放式目录管理）的目录规则。

<searchTime> - 文本，浮点数，是指总的反馈搜索结果的时间，精确到秒。

3.2  结果元素
<summary> - 如果搜索结果在ODP目录下有列表，ODP摘要会以文本字符串形式显示在这里。

<URL> - 搜索结果的URL, 返回URL绝对路径的文本类型。

<snippet> - A 显示查询到的上下文的片断 ，这个是HTML格式的，通常在其中包括<B>标记,注意: 查询条件不总是显示在片断中. 注意: 查询条件将会在结果中加粗高亮，行断点也将包含在适当的文本中。

<title> - 搜索结果的标题，返回HTML格式。

<cachedSize> - 文本(Integer + 'k')， 是指URL的缓冲版本是可用的，size是KB（千字节）。

<relatedInformationPresent> - 布尔值，是指'related:'查询条件支持这个URL。

<hostName> - 当过滤发生的时候，在相同主机结果中，顶多只有2个结果会返回，当这种情况发生的时候 来自那个主机的第二个结果元素（resultElement）在参数中包含有主机名.

<directoryCategory> - 见下条.

<directoryTitle> - 如果这个结果元素（resultElement）的URL包含ODP目录,显示在目录中的标题会在此显示一串文本字符串,注意:directoryTitle可能和<title>的URL不同。

3.3  目录类别
<fullViewableName> - 文本, 为当前的ODP类别包含ODP目录名。

<specialEncoding> - 指定目录信息编码方案。

---

?nbsp;2002 Google, Inc. All Rights Reserved.

---

Google Web APIs 参考中文版