搜索引擎接口文档

概述

达观开放搜索服务(Datagrand Open Search,简称DOS)为应用方提供了功能强大、使用灵活的搜索系统。通过使用达观搜索服务,应用方可以快速构建自己的高性能实时搜索服务,而且包括全面的搜索功能,包括三类服务。
1,关键词搜索服务:输入搜索词,返回搜索的结果;2,关键词自动补全服务:输入搜索词的前几个字符,能自动提示对应的搜索词,例如输入“变形”,提示“变形金刚”、“变形记”等;3,相关搜索词推荐服务:提供“相关的搜索词”的列表,例如当前搜索词为“变形金刚1”,相关搜索词包括“变形金刚女主角”、“变形金刚2”等。 同时这三项功能,在达观后台也提供详细的搜索配置,以及数据统计功能,让使用者充分掌握搜索功能的运行状态

注意事项

您需要完成以下步骤后,才可调用达观数据相关服务。
1. 如您还没有开通达观账号,请先开通,账号开通请参考文档:Step 1:开通账号
2. 获取您的appidappname,请参考文档:获取AppId及AppName
3. 设置IP白名单,请参考文档:设置IP白名单

数据上报

常见问题

1.常见问题及解答请参考数据上报常见问题
2.强烈建议使用数据上报文档末尾提供的代码进行数据上报,可以避免大部分问题。

数据上报接口列表

接口描述

达观数据上报统一接口,产品信息数据、用户信息数据、用户行为数据等等都是通过该接口进行上报。接入达观搜索服务首先需要进行数据上报。

URL

http://datareportapi.datagrand.com/data/YOUR_APP_NAME
* 注:YOUR_APP_NAME 请填您的达观账号名。

Http Method

POST

Http 返回格式

JSON

Http 请求参数说明

参数 类型 是否必需 描述
appid int 您的达观账号对应的id
table_name string 要上传数据的表名
table_content string 上报的数据内容,JSON格式

请求参数详细说明:

1. table_name
table_name字段表明数据所要上传到的表格。达观预定义了4个数据表,使用搜索服务只需要上传其中2个表格的数据,table_name字段 需要是以下表格给出的值。请对照各个表格的含义,上传数据到正确的表格。
各个达观数据表格和字段的详细说明,请参见后文“上报数据表详细说明”。

table_name 含义
item 物品信息表
user_action 用户行为信息表

2. table_content
table_content字段的值对应的是上报的数据内容,必须是UTF8编码。
支持批量上报,即一次请求上报多条数据,因此table_content是一个列表(list)的JSON字符串
table_content列表的每一个元素是一个字典(dict),每个dict必须包含“cmd”和“fields”两个字段,“fields”包含数据记录的具体内容,“cmd”是对记录的操作。
(1)cmd可能的取值和定义如下:

cmd 含义
add 新增或更新一条记录,如果主键对应的记录已经存在,则对该记录做更新操作
update 更新一条记录,如果主键对应的记录不存在,则不处理,user_action表不支持update操作
delete 删除一条记录,如果主键对应的记录不存在,则认为删除成功,user_action表不支持delete操作
refresh_all 批量下线item数据,仅对item表有效

(2)fields 字段的值为一个词典(dict),是具体上报的数据内容,请将您所要上报的字段及相应的值构建成词典,比如 { “itemid”: “28394556”, “cateid”: “9_2_1”, “score”: 459, “title”: “天穿修炼记最新版”, “item_tags”: “修仙”}。
*注:根据上报的table_name的不同,fields 应包含不同的字段,详见后文“上报数据表详细说明”。

Http 返回结果说明

参数 类型 描述
status string 执行结果,OK为成功。FAIL为失败,数据不会入库。WARN为有部分非重要字段异常,数据会正常入库,但请根据返回错误信息进行排查。
errors string 错误信息
request_id string 该条上报记录的序号,仅用于排查问题使用

上报数据表详细说明

概述

达观预定义了2个数据表格供搜索服务使用,以下给出每个表格的字段定义,以及取值的格式,请严格按照以下规定进行数据上报。
如果上报的数据字段和以下数据表的字段含义一致,请务必按照本文档规定的字段名进行上报,否则可能会影响搜索的效果。

item(物品信息表)

说明: 用于上报主要的产品数据,比如商品信息、视频信息、主播信息等等。

参数 类型 必需 描述
itemid string item的唯一id
cateid string cateid,item所属分类,多级分类用“_”进行分隔。例如“1_2”,表示一级分类为1,二级分类为2。如果同时属于多个分类,用英文分号“;”分隔。比如“1_2;3_1”。
score int item的热门程度,0~1000的整数
title string item的标题
content string 正文,比如帖子或新闻的正文
price int item的价格,单位为分
item_tags string item的标签等信息,多个标签以英文分号“;”分割。如果需要根据标签进行搜索,此项需要上报
item_modify_time int item的最新修改时间,unix时间戳,精确到秒如果需要根据该字段进行搜索筛选,此项需要填上
其他 string 其他字段也可以进行上报,如果有时间字段,需要采用unix时间戳(精确到秒)

常见错误
1. item_modify_time必须是秒级的时间戳,不是毫秒
2. cateid不要错写成cate
3. cateid和item_tags必须使用英文分号分隔,不能用逗号(中英文)或者其它

示例

CURL调用示例:
Content-Type: multipart/form-data方式:

Content-Type: application/json方式:

refresh_all调用示例:
注意:
1. refresh_all命令需要在fields中填all_itemid,all_itemid是所有要保持在线的itemid构成的list,refresh_all会把不在all_itemid中的所有item都下线,请谨慎使用!
2. all_itemid必须传多于100个itemid

成功返回示例:

错误返回示例:

警告返回示例:

user_action(用户行为信息表)

说明: 用户的行为数据,尤其是对物品的比较重要的行为数据,比如购买。
* 用户对搜索结果的点击行为也通过该表进行上报。

参数 类型 必需 描述
userid string 用户唯一id,对应user表的userid
imei string 用户的手机IMEI号
cid string 用户的cookieid,(userid、imei、cid至少存在一个)
itemid string 对应item表的itemid
action_type string 用户对item执行的操作,必须是有意义的字符串,上报用户对搜索结果的点击请填“search_click”,用于统计搜索点击率
action_num int 动作数量。对于购买,可以是购买价格(单位为分)
action_detail string 该行为的一些描述信息,该字段可以自行定义,比如登录的话,可以是qq登录或者微信登录,发送短信可以是短信发送成功或者失败等等。在大数据平台会对这些数据进行汇总,以;进行分隔
timestamp timestamp 动作发生的时间,unix时间戳,精确到秒,没有传则置为收到请求的时间
其他 string 其他字段也可以进行上报,如果有时间字段,需要采用unix时间戳(精确到秒)

常用的的action_type如下表所示:

action_type 含义
view 浏览
search_click 点击搜索结果
collect 收藏
subscribe 订阅
comment 评论
gift 送礼物
share 分享
like 点赞
dislike 点衰
cart 加入购物车(或加入书架)
buy 购买

常见错误
1. 上报用户浏览、点击行为时,上报的itemid不能为空
2. userid imei cid三个用户id不能都为空
3. timestamp必须是秒级的时间戳,不是毫秒
4. action_type必须是有意义的字符串,如果用户的操作是上面表格所列的动作,请按照表格规定进行上报

示例

CURL调用示例:
Content-Type: multipart/form-data方式:

Content-Type: application/json方式:

HTTP请求示例代码

JAVA

1. 普通方式上传

2. gzip压缩上传

PHP

搜索服务接口列表

关键词搜索服务

接口描述

对用户输入的关键词进行相关结果的搜索匹配,搜索结果默认按照关键词与文档的相关性分以及文档的质量分加权后的得分进行排序,也可以按照指定字段进行排序。接口支持指定字段值筛选以及区间筛选。

URL

http://searchapi.datagrand.com/search/YOUR_APP_NAME

Http Method

GET

Http 返回格式

JSON

Http 请求参数说明

参数 类型 是否必需 描述
query string 搜索查询词,utf-8 编码,允许在某些情况下留空(例如按全体价格排序等情况下,不需要query)
userid string 用户id
imei string 用户手机IMEI号
cid string 用户网站cookieid (注意:userid、imei、cid至少包含一项,可都填写
sort string 排序字段。根据不同的应用,排序字段可以为商品的价格、更新时间或书籍的阅读数、点赞数等。如未指定该参数,则默认使用综合排序。默认排序综合考虑关键词与文档的相关性、文档的质量分以及关键词对文档的点击加权计算模型(注意:字段名须和 达观-数据采集接口文档 中item信息表相对应)。
revert int 指定按sort字段降序还是升序排列结果。revert=1表示倒排序,revert=0表示升序排序,如未指定该参数或参数为非0或1的非法值,则默认按降序排序。
pos int 分页返回结果的开始项,默认为0。注意pos不是起始页数,而是当前页的起始条数。比如每页返回条数cnt=10, 则第1页的pos=0, 第2页的pos=10,以此类推。
cnt int 每页返回的结果条数,默认为20,最大为50,例如当pos为10,cnt为20时,返回搜索结果的第10-30条结果
filter string 对搜索结果用指定的字段进行筛选。字段名与字段值用:分割,多个字段用+分割,如filter=status:1+cateid:60;支持字段多值OR关系筛选,多值之间用逗号分隔,比如filter=cateid:100,101
not_filter string 对搜索结果用指定的字段进行排除筛选。字段名与字段值用:分割,多个字段用+分割,如not_filter=status:1+cateid:60;支持字段多值排除筛选,多值之间用逗号分隔,比如not_filter=cateid:100,101,表示cateid不等于100和101
range string 区间筛选,仅支持>=和<=两种符号,多个条件间用加号+连接,例如要求结果字数大于等于10000且小于等于20000,则搜索条件写为range=wordcount>=10000+wordcount<=20000(注意:字段名须和达观-数据采集接口文档 中item信息表相对应)
boost string 在综合排序中,设置对指定的字段根据特定值进行排序提升。字段名与字段值用:分割,如boost=nationId:2,支持int类型的排序提升,不支持多值类型的排序提升
scene_type string 场景类型,用于标时不同的场景,常用的包括pc(PC搜索),android(安卓搜索)等。不在上述中的可以自行添加。
fields string 指定搜索结果需要返回的字段,多个字段用英文逗号,隔开,不指定则默认只返回搜索结果的itemid
no_ec string 关键词默认会进行纠错处理;no_ec设置为true时,表示不进行纠错

Http 返回结果说明

字段 类型 描述
status string 执行结果,OK为成功,FAIL为失败,如果有参数异常但可以有返回结果,则返回WARN,请根据返回错误码进行排查
resultcount int 搜索结果总数,如搜索失败,则resultcount值为-1
resultdata string 搜索结果,为一个LIST,每一项为一个jsondict,主要包括itemid。
request_id string 该条查询的记录id,发生错误时产生此字段,主要用于排查问题使用
errors string 出现问题时提供错误信息,正常时不显示

示例 CURL调用示例:

成功返回示例:

错误返回示例:

警告返回示例:

注意事项:
1)为了便于更好的分析用户的搜索效果,搜索请求时尽可能传递用户标识符,例如cid、imei、userid等字段的值
2)search_data的返回的搜索结果集默认值包含itemid,需要返回其它字段,可通过fields参数指定
3) no_ec未设置时,默认会进行纠错处理,如果纠错成功,会返回纠错结果如”ec_info”: {“transfered_keyword”: “\u80b2\u8b66”, “keyword”: “\u4e8e\u656c”}。
4)如果在搜索后台配置了高亮字段,会在该字段的返回结果里高亮命中的关键词,如”纪录片:争夺<font color=red>原始森林</font>,人象相杀30年”。

自动补全服务

接口描述

用户在搜索框输入部分关键词,接口自动输出与用户输入词相关的完整关键词列表供用户选择。比如用户输入”北京”,自动补全接口可以返回“北京天安门,北京故宫,北京大学等”。接口支持拼音匹配,比如用户输入“beijing”, 自动补全接口可以返回“北京天安门,北京故宫,北京大学等”。

URL

http://searchapi.datagrand.com/suggest/YOUR_APP_NAME

Http Method

GET

Http 返回格式

JSON

Http 请求参数说明

参数 类型 是否必需 描述
query string 用户输入的待自动补全的搜索关键词,例如“变”字,utf-8 编码,不可为空
cnt int 需要返回的结果条数,最大支持20,默认返回10条suggest结果
userid string 用户id
imei string 用户手机IMEI号
cid string 用户网站cookieid
scene_type string 场景类型,用于标时不同的场景,常用的包括pc(PC自动补全),android(安卓自动补全)等。不在上述中的可以自行添加

Http 返回结果说明

字段 类型 描述
status string 执行结果,OK为成功,FAIL为失败,如果有参数异常但可以有返回结果,则返回WARN,请根据返回错误码进行排查
resultcount int 自动补全结果条数,如搜索失败,则resultcount值为-1
resultdata string 补全结果,为一个LIST,每一项为一个suggest的字符串
request_id string 该条查询的记录id,发生错误时产生此字段,主要用于排查问题使用
errors string 出现问题时提供错误信息,正常时不显示

示例 CURL调用示例:

成功返回示例:

错误返回示例:

注意事项:
1) 自动补全的结果默认计算自item的title字段,比如商品的标题或书籍的名称
2) 系统会根据用户常见的查询词来选择最优的suggest补全结果

相关搜索服务请求

接口描述

根据用户当前的搜索词,接口自动推荐与当前搜索词相关的搜索词列表。比如用搜索“变形金刚”,接口可以返回“变形金刚最新电影,变形金刚游戏,变形金刚5黑暗擎天柱”等。

URL

http://searchapi.datagrand.com/relate/YOUR_APP_NAME

Http Method

GET

Http 返回格式

JSON

Http 请求参数说明

参数 类型 是否必需 描述
query string 当前的搜索词,utf-8 编码,不可为空
cnt int 需要返回的结果条数,最大支持20,默认返回10条相关搜索词
userid string 用户id
imei string 用户手机IMEI号
cid string 用户网站cookieid
scene_type string 场景类型,用于标时不同的场景,常用的包括pc(PC搜索),android(安卓搜索)等。不在上述中的可以自行添加

Http 返回结果说明

字段 类型 描述
status string 执行结果,OK为成功,FAIL为失败,如果有参数异常但可以有返回结果,则返回WARN,请根据返回错误码进行排查
resultcount int 相关搜索结果总数,如系统处理失败,则resultcount值为-1
resultdata string 相关搜索结果,为一个LIST,每一项为一个相关搜索关键词
request_id string 该条查询的记录id,发生错误时产生此字段,主要用于排查问题使用
errors string 出现问题时提供错误信息,正常时不显示

示例 CURL调用示例:

成功返回示例:

错误返回示例:

热门搜索词接口

接口描述

接口返回以天为单位统计的热门搜索词,支持分页获取。

URL

http://searchapi.datagrand.com/hotqueries/YOUR_APP_NAME

Http Method

GET

Http 返回格式

JSON

Http 请求参数说明

参数 类型 是否必需 描述
userid string 用户id
imei string 用户手机IMEI号
cid string 用户网站cookieid
pos int 分页返回结果的开始项,用于翻页,默认为0。
cnt int 每页返回的结果条数,默认为10,最大为20,例如当start为10,cnt为20时,返回搜索结果的第10-30条结果
scene_type string 场景类型,用于标时不同的场景,常用的包括pc(PC搜索),android(安卓搜索)等。不在上述中的可以自行添加。

Http 返回结果说明

字段 类型 描述
status string 执行结果,OK为成功,FAIL为失败,如果有参数异常但可以有返回结果,则返回WARN,请根据返回错误码进行排查
resultcount int 结果总数,如接口失败,则resultcount值为-1
resultdata string 搜索结果,为一个LIST,每一项为一个jsondict,主要包括query_text
request_id string 该条查询的记录id,发生错误时产生此字段,主要用于排查问题使用
errors string 出现问题时提供错误信息,正常时不显示

示例

CURL调用示例:

成功返回示例: