知道OPEN API接口规范文档1.0_final

百度知道OPEN API接口规范文档v1.0

百度知道OPEN API接口规范文档V1.0

系统名称

项目负责人

作者

文档提交日期

百度知道OPEN API服务接口

耿艳坤

2010-08-26

百度在线网络技术（北京）有限公司

(版权所有,翻版必究)

百度在线网络技术（北京）有限公司 - 1 -

百度知道OPEN API接口规范文档v1.0

百度在线网络技术（北京）有限公司 - 2 -

百度知道OPEN API接口规范文档v1.0

修改记录

No

1

修改后

版本号

1.0

修改内容简介

百度知道OPEN API服务接口

修改日期

2010-08-26

修改人

耿艳坤

百度在线网络技术（北京）有限公司 - 3 -

百度知道OPEN API接口规范文档v1.0

目 录

1

2

3

4

背景 ......................................................................................................................................................... 5

规范适用对象说明 ................................................................................................................................. 5

名词解释 ................................................................................................................................................. 5

请求数据包格式规范 ............................................................................................................................. 5

4.1 URL .......................................................................................................................................... 5

4.2 参数 .......................................................................................................................................... 5

4.2.1 系统级参数 ..................................................................................................................... 5

4.2.2 业务级参数的通用约定 ................................................................................................. 6

4.2.3 参数签名算法 ................................................................................................................. 6

响应数据包格式规范 ............................................................................................................................. 7

5.1 XML输出格式 ......................................................................................................................... 7

5.2 json输出格式 ........................................................................................................................... 7

5.3 错误响应输出格式 ................................................................................................................... 8

错误码定义 ............................................................................................................................................. 8

API接口细则 .......................................................................................................................................... 9

7.1 stionList .................................................................................................... 9

7.1.1 功能 ................................................................................................................................. 9

7.1.2 参数 ................................................................................................................................. 9

7.1.3 返回值 ............................................................................................................................. 9

7.2 stionSearch ............................................................................................. 10

7.2.1 功能 ............................................................................................................................... 10

7.2.2 参数 ............................................................................................................................... 10

7.2.3 返回值 ........................................................................................................................... 10

7.3 stionInfo ................................................................................................. 11

7.3.1 功能 ............................................................................................................................... 11

7.3.2 参数 ............................................................................................................................... 11

7.3.3 返回值 ........................................................................................................................... 11

7.4 stionAnswer ........................................................................................... 12

7.4.1 功能 ............................................................................................................................... 12

7.4.2 参数 ............................................................................................................................... 12

7.4.3 返回值 ........................................................................................................................... 13

7.5 on ............................................................................................................. 13

7.5.1 功能 ............................................................................................................................... 13

7.5.2 参数 ............................................................................................................................... 13

7.5.3 返回值 ........................................................................................................................... 13

7.6 ................................................................................................................ 14

7.6.1 功能 ............................................................................................................................... 14

7.6.2 参数 ............................................................................................................................... 14

7.6.3 返回值 ........................................................................................................................... 14

第三方提供API接口细则 ................................................................................................................... 15

附件及参考资料 ................................................................................................................................... 16

5

6

7

8

9

百度在线网络技术（北京）有限公司 - 4 -

1 背景

本文旨在为第三方合作站点应用访问百度知道开放服务提供统一的HTTP接口调用与交互规范。

本文中描述的规范包括百度知道问题列表查询接口、检索查询接口、提问接口和回答接口。

2 规范适用对象说明

本规范仅适用于由服务器端发起调用请求、POST提交数据以及GET请求文本数据结果的Open

API。

3 名词解释

 百度知道：

 API KEY：注册API合作时由百度的OPEN API平台分配的唯一标识一个应用的字符串，又称应用公钥

 API SECRET：注册API合作时由百度的OPEN API平台分配的应用密钥，用于平台与合作站点之间通信时的参数签名

4 请求数据包格式规范

4.1 URL

按照百度Open API规范，百度知道OPEN API提供如下REST风格的HTTP接口：

/restserver/zhidao?{query_string}

query_string由系统级参数部分和具体Open API调用参数部分组成，以key1=value&key2=value2&…表示，对于采用POST请求的Open API，query_string部分则是在POST请求体里。所有查询类的Open API接口既支持POST，也支持GET方式，提交类的OPEN API接口仅支持POST方式。

4.2 参数

4.2.1 系统级参数

百度在线网络技术（北京）有限公司 - 5 -

以下参数是由百度Open API平台系统定义的，百度知道需要支持这些参数以便接入该平台提供开放接口。百度知道采用应用授权认证接口方式，合作初始百度知道代第三方站点申请应用分配api_key和参数签名密钥api_secret。

表格 4-1 API系统级参数

参数名

api_key

method

类型

string

string

是否必需

是

是

描述

注册应用时分配到的api key

采取stionList这样的命名空间方式制定方法名

时间戳，系统时间的秒值,同个应用的不同api请求的time值应该是递增的, 用于防replay攻击

响应包格式，可以是xml（默认）或json

API调用请求包的编码类型，支持UTF-8和GBK

参数签名，对bd_sig外所有参数串的签名，包括业务级的参数。

call_id

format

ie

bd_sig

uint

string

string

string

是

否

否

是

4.2.2 业务级参数的通用约定

百度知道遵守百度Open API规范中业务级通用参数的约定。

表格 4-2 业务级参数的通用约定

参数名

page_no

page_size

类型

Int

Int

描述

用于支持分页的api，默认为1，表示第几页

用于支持分页的api，表示每页返回多少条数据，默认以及上限为25

4.2.3 参数签名算法

参数签名生成算法采取如下方式（PHP版），其它语言根据注释描述完成等同功能：

//param_array是key-value形式的参数数组，不包括api_secret密钥本身

//secret是合作申请成功后分配的api_secret密钥

function generate_sig($param_array, $secret) {

$str = '';

//对param_array中的参数名称进行升序排序

ksort($param_array);

//按照如下格式转换数组为string格式

foreach ($param_array as $k=>$v) {

$str .= "$k=$v";

}

//string末端补充api_secret密钥

百度在线网络技术（北京）有限公司 - 6 -

$str .= $secret;

//生成MD5为最终的数据签名

return md5($str);

}

注：密钥是百度知道分配给第三方应用的secret_key，该算法返回的结果便是系统级参数中的bd_sig。

5 响应数据包格式规范

响应数据包的格式由调用时传递的format参数指定（默认为xml格式），无论是xml格式还是json格式，输出内容都是UTF-8格式。目前，百度知道目前支持xml、json格式。

5.1 XML输出格式

 文档编码格式UTF-8

 接口的返回数据中，数组对应的xml节点包含list=”true”属性，其子节点的标签名跟对应的数据有联系，并且同个数组内的同级节点的标签名一致。例如表示问题标题列表对应的xml输出可能为：

 接口的返回数据中，对象类型和普通数据类型数据（string，int，double，bool）对应的xml节点不包含list属性或者list属性值为false，节点标签名具有实际意义，与数据所描述的信息相符。例如，表示问题的数据对应的xml输出为：

5.2 json输出格式

API调用时如果传递format参数为json（大小写不敏感），则正常响应包符合如下规范的json字符串：

 http响应头中的Content-Type指定为application/json, charset=utf-8

百度在线网络技术（北京）有限公司 - 7 -

 字符串编码格式是UTF-8

字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串

5.3 错误响应输出格式

错误响应输出内容符合以下规范：

 返回内容由error_code, error_msg, request_args这3个属性组成，分别用于描述错误码，错误信息，以及调用Open API时所传递的所有参数的信息。

 request_args属性是一个数组，由n个包含key和value属性的对象组成

例如，假设第三方应用调用stionList接口时传递的参数api_key无效，则其对应的xml格式的错误响应包为如下格式：

101

Invalid API key

Json格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串

6 错误码定义

百度开放知道OPEN API调用过程中可能会返回的错误码定义如下表所示：

error_code

0

1

2

3

error_msg

Success

Unknown error

Unsupported openapi method

Description

成功

未知错误

Open api接口不被支持

Service temporarily unavailable

后端服务暂时不可用

百度在线网络技术（北京）有限公司 - 8 -

4

5

100

101

103

104

105

106

200

900

12001

12002

Open api request limit reached

应用对open api接口的调用请求数达到上限

参数无效或缺失

Api key无效

Call_id参数无效或已被使用过

签名无效

参数过多

参数签名算法未被平台所支持

没有权限访问数据

应用不存在

必选参数格式错误

提交回答的问题生命已结束

Unauthorized client IP address:%s

open api调用端的IP未被授权

Invalid parameter

Invalid API key

Invalid call_id parameter

Incorrect signature

Too many parameters

Unsupported signature method

No permission to access data

No such application exists

Parameters format error

Answer for invalid question

7 API接口细则

以下接口返回数据均是以XML格式为demo，JSON格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串。

7.1 stionList

7.1.1 功能

基于百度知道分类ID获取对应分类下的问题列表

URL Demo：

/restserver/zhidao?api_key=20000&method=stionList

&call_id=1276418994&format=xml&bd_sig=sig-result&cid=249&qstatus=0&page_no=2&page_size=25

7.1.2 参数

参数名 类型 描述

4.2.1 系统级参数全体

4.2.2 业务级参数全体

cid

qstatus

int

int

百度知道的分类ID

问题状态 0为待解决 1为已解决

7.1.3 返回值

 Response XML 示例

百度在线网络技术（北京）有限公司 - 9 -

 Response XML 标签说明

标签名

id

url

title

content

cid

cname

描述

问题ID

该问题在百度知道的URL

问题标题

提问内容

该问题在百度知道所属的分类ID

该问题在百度知道所属的分类名称

7.2 stionSearch

7.2.1 功能

基于检索关键字在百度知道中搜索匹配的问题列表

URL Demo：

/restserver/zhidao?api_key=20000&method=stionSearch&call_id=12764994&format=xml&bd_sig=sig-result&keywords=北京+百度大厦&qstatus=0

&page_no=2&page_size=25

7.2.2 参数

参数名 类型 描述

4.2.1 系统级参数全体

4.2.2 业务级参数全体

keywords

qstatus

string

int

检索关键字 多个检索关键字之间使用+号连接

问题状态 0为待解决 1为已解决

7.2.3 返回值

 Response XML 示例

百度在线网络技术（北京）有限公司 - 10 -

 Response XML 标签说明

标签名

id

url

title

content

cid

cname

描述

问题ID

该问题在百度知道的URL

问题标题

提问内容

该问题在百度知道所属的分类ID

该问题在百度知道所属的分类名称

7.3 stionInfo

7.3.1 功能

基于百度知道问题ID获取对应问题的数据以及回答

URL Demo：

/restserver/zhidao?api_key=20000&method=stionInfo

&call_id=127323494&format=xml&bd_sig=sig-result&qid= 122727482

7.3.2 参数

参数名

qid

类型

int

描述

百度知道的问题ID

4.2.1 系统级参数全体

7.3.3 返回值

 Response XML 示例

百度在线网络技术（北京）有限公司 - 11 -

 Response XML 标签说明

标签名

questionInfo

bestAnswers

answers

content

cite

pic_url

描述

问题内容数据，具体明细参考7.1和7.2

最佳答案列表

普通答案列表

回答内容

回答参考资料

回答贴图URL

7.4 stionAnswer

7.4.1 功能

基于百度知道问题ID、回答ID获取对应问题的数据的回答

URL Demo：

/restserver/zhidao?api_key=20000&method=stionInfo

&call_id=127323494&format=xml&bd_sig=sig-result&qid= 122727482&aid=1232142352

7.4.2 参数

参数名

qid

类型

int

描述

百度知道的问题ID

4.2.1 系统级参数全体

百度在线网络技术（北京）有限公司 - 12 -

aid int 百度知道的回答ID

7.4.3 返回值

 Response XML 示例

 Response XML 标签说明

标签名

questionInfo

answerInfo

描述

问题内容数据，具体明细参考7.1和7.2

回答内容数据

7.5 on

7.5.1 功能

向百度知道进行提问

URL Demo：

/restserver/zhidao 参数全部为POST方式

7.5.2 参数

参数名

title

content

utype

uid

uname

类型

string

string

string

int

string

描述

POST字段问题标题

POST字段问题内容

POST字段用户类型，例如baidu、renren、wanmei

POST字段第三方账号系统uid

POST字段第三方账号系统uname

4.2.1 系统级参数全体api_key method call_id format bd_sig（POST）

7.5.3 返回值

 Response XML 示例

百度在线网络技术（北京）有限公司 - 13 -

 Response XML 标签说明

标签名

error_code

error_msg

qid

描述

错误号，0为成功

错误描述

提问成功后返回的qid

7.6

7.6.1 功能

向百度知道的待解决问题进行回答

URL Demo：

/restserver/zhidao 参数全部为POST方式

7.6.2 参数

参数名

qid

content

cite

pic_url

utype

uid

uname

类型

string

string

string

string

string

int

string

描述

POST字段提供回答的问题ID

POST字段回答内容

POST字段回答参考资料

POST字段回答的贴图

POST字段用户类型，例如baidu、renren、wanmei

POST字段第三方账号系统uid

POST字段第三方账号系统uname

4.2.1 系统级参数全体api_key method call_id format bd_sig （POST）

7.6.3 返回值

 Response XML 示例

 Response XML 标签说明

标签名

error_code

描述

错误号，0为成功

百度在线网络技术（北京）有限公司 - 14 -

error_msg

qid

错误描述

回答成功后返回的问题id

8 第三方提供API接口细则

使用提问API（on）的第三方，其用户使用该API提交提问之后，如果知道平台上有用户对该提问进行了回答，那么是需要一种机制反馈给第三方API调用者，以便及时将回答反馈给提问的用户，解决用户的疑问。本章节描述提问下产生回答后，第三方需要提供的API接口规范格式和要求。所有回答相关的反馈输出字符编码均是UTF-8

需要第三方提供HTTP的接口，采用POST方法，参数签名加密算法和4.2.3章节描述的算法一致，会使用第三方的密钥进行加密，第三方对之进行有效性校验，需要支持的POST参数如下：

参数名

method

qid

aid

utype

uid

类型

string

int

int

string

int

描述

值为ck

问题ID，知道为int型

回答ID，知道为int型

提问用户的用户类型，例如baidu、renren、飞信

第三方账号系统uid

第三方基于接收到的qid和aid向平台发起请求，调用stionAnswer API接口获取对应提问下的回答信息。

第三方合作站点如果不采用消息提醒=》抓取回答内容的方式，可以选择下面这个直接接收回答数据的方法，仍然是HTTP接口，POST方法，参数签名加密算法和4.2.3章节描述的算法一致，会使用第三方的密钥进行加密，第三方对之进行有效性校验，需要支持的POST参数如下：

参数名

method

qid

aid

utype

uid

content

cite

pic_url

类型

string

int

int

string

int

string

string

string

描述

值为swer

问题ID，知道为int型

回答ID，知道为int型

提问用户的用户类型，例如baidu、renren、wanmei

第三方账号系统uid

回答内容

回答参考资料

回答的贴图URL

第三方合作接收到平台的回答反馈后，需要按指定数据格式输出数据信息，输出数据格式为UTF-8编码的XML接口。具体数据格式为：

 Response XML 示例

百度在线网络技术（北京）有限公司 - 15 -