百度知道OPENAPI接口规范文档1.0_final

1、百度知道OPEN API接口规范文档v1.0百度百度知道OPEN AP接口规范文档 V1.0系统名称百度知道OPEN API服务接口I项目负责人作者耿艳坤文档提交日期2010-08-26百度在线网络技术（北京）有限公司（版权所有,翻版必究）百度在线网络技术（北京）有限公司-ii -百度知道OPEN API接口规范文档v1.0百IS修改记录No修改后 版本号修改内容简介修改日期修改人11.0百度知道OPEN API服务接口2010-08-26耿艳坤百度在线网络技术（北京）有限公司-3 -143525174.docBai溢百虞目录1 背景42 规范适用对象说明 43 名词解释44 请求数据包格式规

2、范 44.1 URL44.2 参数44.2.1 系统级参数44.2.2 业务级参数的通用约定 54.2.3 参数签名算法55 响应数据包格式规范 65.1 XML输出格式65.2 json输出格式65.3 错误响应输出格式 76 错误码定义77 API接口细则87.1 baidu.zhidao.getQuesti on List 87.1.1 功能87.1.2 参数87.1.3 返回值87.2 baidu.zhidao.getQuesti on Search 97.2.1 功能97.2.2 参数97.2.3 返回值97.3 baidu.zhidao.getQuesti onlnfo 107.3

3、.1 功能 107.3.2 参数 107.3.3 返回值 107.4 baidu.zhidao.getQuesti onAn swer 117.4.1 功能117.4.2 参数117.4.3 返回值 127.5 baidu.zhidao.questi on 127.5.1 功能 127.5.2 参数 127.5.3 返回值 127.6 baidu.zhidao.a nswer 137.6.1 功能 137.6.2 参数 137.6.3 返回值 138 第三方提供 API接口细则 149 附件及参考资料 151背景本文旨在为第三方合作站点应用访问百度知道开放服务提供统一的HTTP接口调用与交互规

4、范。本文中描述的规范包括百度知道问题列表查询接口、检索查询接口、提问接口和回答接口。2规范适用对象说明本规范仅适用于由服务器端发起调用请求、API。POST提交数据以及 GET请求文本数据结果的 Open3名词解释百度知道：API KEY:注册API合作时由百度的 OPEN API平台分配的唯一标识一个应用的字符串，又 称应用公钥API SECRET注册API合作时由百度的 OPENAPI平台分配的应用密钥，用于平台与合作站 点之间通信时的参数签名4请求数据包格式规范4.1 URL按照百度 Open API规范，百度知道 OPEN API提供如下REST风格的HTTP接口： stringque

5、ry_stri ng由系统级参数部分和具体 Ope n API调用参数部分组成，以key1=value&key2=value2& 表示，对于采用 POST请求的 OpenAPI, query_string部分则是在 POST请求体里。所有查询类的Open API接口既支持POST也支持GET方式，提交类的 OPEN API接口仅支持POST方式。4.2参数4.2.1系统级参数以下参数是由百度 OpenAPI平台系统定义的，百度知道需要支持这些参数以便接入该平台提供开放接口。百度知道采用应用授权认证接口方式，合作初始百度知道代第三方站点申请应用分配api_key和参数签名密钥 a

6、pi_secret 。表格4-1 API系统级参数参数名类型是否必需描述api_keystri ng是注册应用时分配到的api keymethodstri ng是采取 baidu.zhidao.getQuestionList这样的命名空间方式制定方法名call_idui nt是时间戳，系统时间的秒值，同个应用的不 同api请求的time值应该是递增的，用 于防replay 攻击formatstri ng否响应包格式，可以是xml （默认）或jsoniestri ng否API调用请求包的编码类型，支持UTF-8和GBKbd_sigstri ng是参数签名，对bd_sig外所有参数串的签 名，包括

7、业务级的参数。4.2.2业务级参数的通用约定百度知道遵守百度 Open API规范中业务级通用参数的约定。表格4-2业务级参数的通用约定参数名类型描述page_noInt用于支持分页的api，默认为1，表示第几页page_sizeInt用于支持分页的 上限为25api，表示每页返回多少条数据，默认以及4.2.3参数签名算法参数签名生成算法采取如下方式（PHP版），其它语言根据注释描述完成等同功能：param_array 是key-value形式的参数数组，不包括 api_secret密钥本身/secret是合作申请成功后分配的api_secret 密钥function gen erate si

8、g（$param array, $secret） $str = ”;II对param array中的参数名称进行升序排序ksort($param array);II按照如下格式转换数组为string格式foreach ($param array as $k=>$v) |$str .= "$k=$v"I/string末端补充 api_secret 密钥$str .= $secret;百度在线网络技术（北京）有限公司-8 -143525174.doc百虞/生成MD5为最终的数据签名return md5（$str）;注：密钥是百度知道分配给第三方应用的secret_key，

9、该算法返回的结果便是系统级参数中的 bd_sig。5响应数据包格式规范响应数据包的格式由调用时传递的format参数指定（默认为xml格式），无论是xml格式还是json格式，输出内容都是UTF-8格式。目前，百度知道目前支持xml、json格式。5.1 XML输出格式文档编码格式UTF-8接口的返回数据中，数组对应的xml节点包含list= ”true ”属性，其子节点的标签名跟对应 的数据有联系，并且同个数组内的同级节点的标签名一致。例如表示问题标题列表对应的 xml输出可能为：vquestio nList list="true"><title><

10、;!CDATA北京一共有几个区？></title><title><!CDATA 百度大厦的地址是什么？></title></questi on List>接口的返回数据中，对象类型和普通数据类型数据（string , int ，double ，bool ）对应的xml节点不包含list属性或者list属性值为false ，节点标签名具有实际意义，与数据所 描述的信息相符。例如，表示问题的数据对应的xml输出为：<question list="false ”<title><!CDATA 百度大厦的

11、地址是什么？></title><url><!CDATA n/133295964.html</url><content><!CDATA如题，百度大厦地址在</ content ></questi on>5.2 json输出格式API调用时如果传递format参数为json （大小写不敏感），则正常响应包符合如下规范的json字符串：http 响应头中的 Content-Type 指定为 application/json,charset=utf-8字符串编码格式是 UTF-8字符串内容是XML输出数据所对应的

12、PHP数组的标准JSON字符串5.3错误响应输出格式错误响应输出内容符合以下规范：返回内容由error_code, error_msg, request_args这3个属性组成，分别用于描述错误码，错误信息，以及调用Open API时所传递的所有参数的信息。request_args 属性是一个数组，由n个包含key和value属性的对象组成例如，假设第三方应用调用baidu.zhidao.getQuestionList接口时传递的参数api_key无效,则其对应的xml格式的错误响应包为如下格式：<?xml versio n="1.0" en codi ng=&quo

13、t;UTF-8"?><baidu zhidao getQuesti on List resp on se><error code>101</error code><error msg> In valid API key</error msg><request args list="true"><arg><key><!CDATAcid></key><value><!CDATA249></value><

14、/arg><arg><key><!CDATAmethod></key><value><!CDATAbaidu.zhidao.getQuestio nLisx/value></arg></request args></ baidu zhidao getQuesti on List resp onse >Json格式的字符串内容是 XML输出数据所对应的 PHP数组的标准JSON字符串6错误码定义百度开放知道 OPEN API调用过程中可能会返回的错误码定义如下表所示:error_co

15、deerror_msgDescriptio n0Success成功1Unknown error未知错误2Service temporarily un available后端服务暂时不可用3Un supported ope napi methodOpen api接口不被支持百度在线网络技术（北京）有限公司-10 -143525174.doc百虞4Open api request limit reached应用对open api接口的调用请求数 达到上限5Un authorizedclie ntIP address:%sopen api调用端的IP未被授权100In valid parameter

16、参数无效或缺失101In valid API keyApi key 无效103In valid call_id parameterCall_id参数无效或已被使用过104In correct sig nature签名无效105Too many parameters参数过多106Un supported sig nature method参数签名算法未被平台所支持200No permissi on to access data没有权限访问数据900No such applicati on exists应用不存在12001Parameters format error必选参数格式错误12002An

17、 swer for in valid questi on提交回答的冋题生命已结束7 API接口细则以下接口返回数据均是以 XML格式为demo,JSON格式的字符串内容是 XML输出数据所对应 的PHP数组的标准JSON字符串。7.1 baidu.zhidao.getQuestionList7.1.1 功能基于百度知道分类ID获取对应分类下的问题列表URL Demo: http:/ope n. on List& call_id=1276418994& format=xml&bd_sig=sig-result&cid=249&qstatus=O&p

18、age_no=2&page_size=257.1.2参数参数名类型描述4.2.1系统级参数全体4.2.2业务级参数全体cidint百度知道的分类IDqstatusint问题状态0为待解决1为已解决7.1.3返回值Response XML 示例<?ral ver3i0n=rrL.Orr encoding=rr0TF-8rr?><b«idu_ztildao_g«tQue3tlaoLi3t_ttsponse xmlnj"Hhttp: /openapl»baidu+ com" xhinsixai""http

19、:/wu*w3»org/2001 /XKLSchema-instanceM> <questionLi3t 113t-"truerr><question list=J,fal3ex><id><： CDATA 133295364<url>< ! CDATAhttp: /zhidao.haid.Ux coia/que3t±Dn/133295964.htnilJ ></ur L>CD1TA百度大腹地址X/title><CDiiLent>< CDATA百度大鹿地址Jx

20、/contea1<CltiX?CDATA1075JJ></cltl>< cna*e>< ! CD1TA 百 J® ></cnaiae></questioH></ttue3tioiiLlst></bai du_zhi dao_tjetQue 3 ti anL i3t_cesp onse>Response XML标签说明标签名描述id问题IDurl该问题在百度知道的 URLtitle问题标题content提问内容cid该冋题在百度知道所属的分类IDcn ame该问题在百度知道所属的分类名称7.

21、2 baidu.zhidao.getQuestionSearch7.2.1功能基于检索关键字在百度知道中搜索匹配的问题列表URL Demo:http:/ope n. on Sear ch&call_id=12764994&format=xml&bd_sig=sig-result&keywords=北京 + 百度大厦 &qstatus=O&page_ no=2&page_size=257.2.2参数参数名类型描述4.2.1系统级参数全体4.2.2业务级参数全体keywordsstri ng检索关键字多个检索关键字之间使用 +号连接qstat

22、usint问题状态0为待解决1为已解决7.2.3返回值Response XML 示例vei：3ion®rrl. Orr encodingsUTF-0rr?><baidu_zhidao_getQuestionSearch_response xmlns=rrhtt.p: /openapi.ibaidu c*" xnJins :xsi=rrhttp: /uww m3 oeg/2001 /XML5chema-instancer,> <qviest-ionLi3t 113t-rrtruerr><question list=false*><

23、;id><! CDATA|133Z95964X/id><urJL>< ! CDATAhttp: /ziiidao»baidu c>/question/133295964ht»J. X/u.rL>! CD ATA 百蘆大庫地址r Le><contenLX ! CDATAf 百度大厦地址X /content><Cld><!CDATA10?$></Cld>< cnamex ? CDATA 百度X / cnauie></t|U4stion></ques

24、tionList></haldu_zhidao_getoutstlonSebtch_tesponje>Response XML标签说明标签名描述id问题IDurl该问题在百度知道的 URLtitle问题标题content提问内容cid该冋题在百度知道所属的分类IDcn ame该问题在百度知道所属的分类名称7.3 baidu.zhidao.getQuestionlnfo7.3.1功能基于百度知道问题ID获取对应问题的数据以及回答URL Demo:http:/ope nlnfo& call_id=127323494&format=xml&bd_sig=si

25、g-result&qid= 1227274827.3.2参数参数名类型描述4.2.1系统级参数全体qidint百度知道的冋题ID7.3.3返回值Response XML 示例<?ral versionsl.O encoding=TITF-8rr?><bai.du_zhidao_gecQuestxonlnf o_r&sportse xm.lns="http: /openapibaidu com- xmlns:xsi=rrh.tt.p: /www m3 dieg/200JL/XML临cbeutL且一instance!" <que3tion

26、ln£o list=PTfalsew>CDATA 133295964></idO<url>< ! |CDATAh.ttp: /zhidao .beldii ccna/qu已3七:1011/丄3329596411匸111丄></111：1><citle><! CD AT町百度大 IE felh 址Ccontentx ! CDATA百度大匣地Jal ></contentsCDATA 1075 ></clcl><cji：±di 已毛 CDATA 百度X/cnaBe>&

27、lt;/que5tigxiIn£o><bestAnswer3 list=Jirt.ruerr><bes tAnswe e 1 istrr f al serr>< c oncentx! CDATA北京市电捉区上地十銜丄。号 坐地訣丄3号线到西二瞼站下车一艮往西走五分钟就到了 X /匚ontent> <cite>< ! CDATAhttp: /map baiduT cQm/subways/indexhaul ?c=bei j ing X/cite><pic_url><! CDATAhttp: /list

28、mage ben du c Dfc/t/ image_c a tego ry / iatage /hk /zheng j laying j)?g ></pic_url> C/lbestAnsweO</besdLn.3wei；3>|Kanswer s liatrue<answer<content><!CDATAdt京市羁提区上地十浙切母 坐地底口号线到西二旗站下年一宜柱西走五分钟就到了X/c皿t曰让 0g< ! CDATA百矗丸匹地Wt ></Clte><pic_url><! CDATAhttp: /

29、list i>age baidu c o*/1/ image_c a tego ry / iaage/tik/zheng j laying .jpg ></pic_ui:l></answeE><answer list=rrfals已"A<cantent><'CDATA百度大庾由翼林匹克饭功命主佯育场一*鸟翼”的设计者设计的百度大J® ></cgntent><cibe><! CDATAE'B度大廈tfcMh ></cite><pic_url&

30、gt;< CDATAfhttp:/list iaage.baidu c/t/image_category/iaage/hk/Ehengjiayingjjig></pic_url> </answet></aii5wers>< /bai du_：z.hi daogetQue 3 tionInfo_E e sipon3e>Response XML标签说明标签名描述questio nlnfo问题内容数据，具体明细参考7.1和7.2bestA nswers最佳答案列表an swers普通答案列表content回答内容cite回答参考资料pic_

31、url回答贴图URL7.4 baidu.zhidao.getQuestionAnswer7.4.1功能基于百度知道问题ID、回答ID获取对应问题的数据的回答URL Demo:http:/ope nlnfo& call_id=127323494& format=xml&bd_sig=sig-result&qid= 122727482&aid=12321423527.4.2参数参数名类型描述4.2.1系统级参数全体qidint百度知道的冋题IDaidint百度知道的回答ID7.4.3返回值Response XML 示例<baldu_Ehidao_g&#

32、171;tQuestionAnswei_response xulms"http: /openapi. baidu. co«rr xmLns: xsi= Phttp: f /www. w3,org/2001 /XMLSchema-instance"? <quescionlnfo 1 is totals td><id><!CDATA133295964J<ur 1><'! (DATAhttp: /zliidao, baidu. con/que3tion/ 133Z959E吗”html ></ur 1&g

33、t;<- L clftX? CDATAISJ® 大1Oicontentx ! CDAJA 百度大厦地址></content><cid><'! CTATA 1075></cid>< -nantx! CD ATA i J>< / cn&o_ ></questionInfo>Onsweilnf List=rrEalserr><c(Hiten»< ! CMEL北JR1IJ羁促区上地4潮ID号 坐地嵌13号城利西二旳站下带-往西建五井悼就到T >&l

34、t;/coaitenO <cite><! CDATA百度大匣地kfic urlx!CDATAhttp:/li3t,image.taidu,com/1/image category/image/bfc/zhengjiaying.jpg></pir_Qr1> </an?weEinfo></bai du_zhi dao_Qet.Que s ticuiAri3(reE_r e spon3 e>Response XML标签说明标签名描述questio nlnfo问题内容数据，具体明细参考7.1和7.2an swerI nfo回答内容数据7.5

35、baidu.zhidao.question7.5.1功能向百度知道进行提问URL Demo:参数全部为 POST 方式7.5.2参数参数名类型描述4.2.1 系统级参数全体即i key method call idformat bd sig ( POSTtitlestri ngPOST字段冋题标题contentstri ngPOST字段问题内容utypestri ngPOST字段用户类型，例如baidu、renren、wanmeiuidintPOST字段第三方账号系统 uidun amestri ngPOST字段第三方账号系统 un ame7.5.3返回值Response XML 示例<

36、?xnl versicn=rrl. 0,r encoding= rrUTF-Brr?><haidu_zhidaD_question_response XMlns«r,http: /apenapi.baidu. comH， Kinins:xsi=rrhtcp: /wwworg/2DOI/XMLSchema-instanc>e"> <eEEQi:_co(ie>0</erEOE_«(le><tt£or_uisg>succts3</«riior<qid>$3S34543<

37、;/qid>< /bai du_zhi dao_ques ti oi l_i esp ons e>Response XML标签说明标签名描述error_code错误号，0为成功error_msg错误描述qid提问成功后返回的qid7.6 baidu.zhidao.answer7.6.1功能向百度知道的待解决问题进行回答URL Demo:参数全部为 POST 方式7.6.2参数参数名类型描述4.2.1 系统级参数全体即i_key method call_id format bd_sig ( POSTqidstri ngPOST字段提供回答的问题 IDcontentstri ng

38、POST字段回答内容citestri ngPOST字段回答参考资料pic_urlstri ngPOST字段回答的贴图utypestri ngPOST字段用户类型，例如baidu、renren、wanmeiuidintPOST字段第三方账号系统 uidun amestri ngPOST字段第三方账号系统 un ame7.6.3返回值Response XML 示例<?xnl versicn=rr1.0rr encoding= rrUTF-6rr?><haidu_zhidaD_que3tion_response XMlns»r,http: /apenapi.baidu.

39、com*' xmlns:xsi=rrhtcp: /www.W3. org/2DOI/XMLSchema-instanc"><eriot_code>0</erEQt_co(ie><tt£or_uisg>succts3</eriiDr<qid>$8S34543</qid>< /bai du_zhi dao_ques ti oi l_l e3p ons e>Response XML标签说明标签名描述error code错误号，0为成功百度在线网络技术（北京）有限公司-16 -1435251

40、74.doc百虞error_msg错误描述qid回答成功后返回的问题id8第三方提供API接口细则使用提问API (baidu.zhidao.question)的第三方，其用户使用该 API提交提问之后，如果知道平台上有用户对该提问进行了回答，那么是需要一种机制反馈给第三方API调用者，以便及时将回答反馈给提问的用户，解决用户的疑问。本章节描述提问下产生回答后，第三方需要提供的API接口规范格式和要求。所有回答相关的反馈输出字符编码均是UTF-8需要第三方提供 HTTP的接口，采用POST方法，参数签名加密算法和4.2.3章节描述的算法一致，会使用第三方的密钥进行加密，第三方对之进行有效性校验，需要支持的POST参数如下:参数名类型描述methodstri ng值为 baidu.zhidao.feedbackqidint问题ID，知道为int型aidint回答ID，知道为int型utypestri ng提冋用户的用户类型，例如baidu、renren、飞信uidint第三方账号系统uid第三方基于接收到的qid和aid向平台发起请求，调用 baidu.zhidao.getQuestionAns