直播间详细数据
目前直播间详细数据部分仅支持查看自挂载,达人挂载直播间的详细数据,数据内容与(小程序控制台-数据-数据中心-直播)页面保持一致。根据直播间 id、抖音号获取开播直播间的详细信息:包括每个直播间自开播以来产生的所有(互动/经营)指标。
使用限制
- •每日 14:00:00 前更新前一日数据。
- •只能查询昨天以前,且是近90天内的数据。
- •串行调用,控制该open_api的调用频率,并发太高可能触发限流
接口
根据直播间 id 和抖音号获取对应的直播间详细指标,包含互动信息,经营信息。
若传入直播间 id,则会返回对应直播间的详细信息。
若传入抖音号,则获取抖音号作为主播所开播的直播间的详细信息。
接口说明
- •业务场景:此open_api仅支持查看自挂载,达人挂载直播间的相关数据。
- •查询限制:暂不开放UGC挂载相关数据,原因如下:UGC挂载能力下用户的挂载属于自发行为,未经用户授权对经营者开放数据信息涉及数据安全和隐私安全问题,因此暂不对外开放,感谢您的理解。
- •注意事项:此open_api获取的是离线数据,支持查看近90天所开播的直播间详细数据,当天开播的直播间数据无法在当天查看,请在下一天查看。同时请严格控制该open_api的调用频率。
基本信息
名称 | 描述 |
HTTP URL | |
HTTP Method | POST |
Scope | 无 |
权限要求 | 服务商代调用场景下,需商家授予数据分析权限集 |
请求头
请求参数
名称 | 类型 | 是否必填 | 描述 | 默认值 |
start_time | int64 | 是 | 开始时间,必须是昨天以前的某个时间戳,传入当天的整点时间戳,例如要查询2023年3月20号以来的数据,start_time就传2023-03-20 00:00:00对应的时间戳 | 无 |
end_time | int64 | 是 | 结束时间,必须是昨天以前的某个时间戳,传入当天的整点时间戳,例如要查询截止到2023年3月20号的数据 query_bind_type=0,end_time就传2023-03-20 00:00:00对应的时间戳 query_bind_type=1,end_time就传2023-03-20 23:59:59对应的时间戳 | 无 |
host_name | string | 否 | 宿主APP,douyin-抖音;douyin_lite-抖音lite;toutiao-今日头条;tt_lite-今日头条lite;huoshan-抖音火山版;不传表示查全部端数据 | 无 |
query_bind_type | int64 | 是 | 查询数据的挂载类型,1-自挂载数据,0-自挂载数据+达人挂载数据,目前调用此open_api必须传0或1,传其他值可能产生非预期的结果 | 1 |
aweme_short_id_list | array | 是 | 没有抖音号列表,需要传递 空的字符串数组,如果查询抖音号列表限制长度在200以内,即一次性最多查询 200个抖音号 所对应的自挂载,达人挂载视频/自挂载,达人挂载直播间所产生的数据 | 无 |
query_data_type | int64 | 是 | 查询的列表类型,传4表示查询短视频发布数据,传5表示查询直播开播数据 | 无 |
item_id_list | array | 否 | 查询的短视频列表,限制长度在1000以内,即一次性最多查询 1000个 自挂载,达人挂载短视频的详细数据 | 无 |
room_id_list | array | 否 | 查询的直播间列表,限制长度在1000以内,即一次性最多查询 1000个 自挂载,达人挂载直播间的详细数据 | 无 |
page_no | int64 | 是 | 查询页号,从1开始 | 无 |
page_size | int64 | 是 | 每页的大小(20以内),分页结果按短视频发布时间or直播间开播时间倒序排列 | 无 |
请求示例
//查询"xxx","xxx"这两个抖音号在 2023年3月20日 到 2023年3月21日 之间,在抖音端开播的自挂载,达人挂载直播间详细数据 { "start_time": 1679241600, "end_time": 1679328000, "host_name": "douyin", "query_bind_type": 0, "aweme_short_id_list": ["xxx","xxx"], "query_data_type":5, "page_no":1, "page_size":100 } /**查询"7169582199207939932","7169582199207457932"这两个直播间ID中开播时间在 2023年3月20日 到 2023年3月21日 之间且类型为自挂载的直播间的详细数据**/ { "start_time": 1679241600, "end_time": 1679328000, "query_bind_type": 1, "room_id_list": ["7169582199207939932","7169582199207457932"], "query_data_type":5, "page_no":1, "page_size":100 }
响应参数
名称 | 类型 | 是否必填 | 描述 | 默认值 |
err_no | int64 | 是 | 错误码 | |
err_msg | string | 是 | 错误信息 | |
log_id | string | 是 | log_id,用于向内部开发人员进行反馈 | |
data | object | 是 | 响应结果(具体结构见下方正常实例) | |
响应示例
正常示例
{ "err_no":0, "err_msg":"success", "data":{ // 短视频/直播间详细数据列表,每一个元素表示一个短视频/直播间数据,列表按短视频发布时间/直播间开播时间倒序排列 "data_list":[ { //如果是直播间,则会返回如下指标 "room_id": "7169582199207939932", //直播间ID "app_type": "1128", //开播平台,-1-不区分端,1128-抖音, 8663-火山,1112-火山(旧),2329-抖音lite, 1350-火山lite, 13-头条,35-头条lite "room_aweme_shortid":"今天又明天", //直播间作者对应的抖音号 "room_aweme_type":"1", //直播间作者对应的类型,1:企业号 0或者没有该字段表示个人号 "room_aweme_nickname":"xxx", //直播间作者的昵称 "room_aweme_avt":"xxx", //直播间作者头像地址 "room_duration":"449", //开播时长,单位秒 "room_create_time":"1679241689", //直播间开播时间,时间戳形式 "room_finish_time":"1679241989", //直播间关播时间,时间戳形式 "room_highest_online_count":"1", //直播间最高在线人数 "room_once_watch_duration":"10", //直播间人均观看时长(单位:秒),计算方式=直播间观看总时长/直播间观看人数 "room_comment_count":"1", //直播间评论次数 "room_like_count":"1", //直播间点赞次数 "room_share_count":"1", //直播间分享次数 "room_comment_user_count":"1", //直播间评论人数 "room_like_user_count":"1", //直播间点赞人数 "room_share_user_count":"1", //直播间分享人数 "mp_show_pv":"2", //小程序曝光次数 "mp_click_pv":"2", //小程序点击次数(该指标后续不再提供,可以参考 mp_drainage_pv 指标) "mp_drainage_pv":"2", //进入小程序次数 "mp_show_uv":"2", //小程序曝光人数 "mp_click_uv":"2", //小程序点击人数(该指标后续不再提供,可以参考 mp_drainage_uv 指标) "mp_drainage_uv":"2", //进入小程序人数 "room_show_pv":"3", //直播间曝光次数 "room_show_uv":"3", //直播间曝光人数 "room_watch_pv":"3", //直播间看播次数 "room_watch_uv":"3", //直播间看播人数 "room_watch_rate":"100%", //看播率(直播间看播人数/直播间曝光人数) "room_interactive_rate":"0%", //互动率,此指标计算方式不完善,暂不使用该指标 "room_uv_price":"0", //直播间uv价值(单位:分) 计算方式-(支付订单金额/小程序曝光人数) "mp_click_rate":"100%", //小程序点击率 计算方式-(小程序点击人数/小程序曝光人数) "pay_order_cnt":"1", //支付订单数 "pay_customer_cnt":"1", //支付订单人数 "pay_order_amount":"1", //支付订单金额(单位:分) "customer_once_price":"1", //客单价(支付订单金额/支付订单人数 单位:分) "order_once_price":"1", //单均价(支付订单金额/支付订单数 单位:分) "refund_customer_cnt":"0", //发起退款用户数 "refund_order_cnt":"0", //发起退款订单数 "refund_amount":"0" //发起退款金额(单位:分) "bc_relation_bind_type":"0" //BC账号绑定关系,0-普通号,100-品牌号,200-员工号,300-合作号 }, { ... }, { ... } , ... ], "sum":20, //在查询条件范围内发布视频/直播间的总数 // 此字段只有在查询单个直播间时才有数据返回,用于展示跨天直播的直播间在每一天所产生的详细数据,key:时间戳,value:直播间数据 "detail_data":{ 1679241600:{ //与data_list列表中的元素的字段相同 ... }, 1679328000:{ ... } } }, "log_id":xxx }
异常示例
{ "err_no":11009, "err_msg":参数不合法或缺少参数, "log_id":xxx, "data":{ } }
错误码
HTTP 状态码 | 错误码 | 描述 | 排查建议 |
200 | -1 | 系统错误 | 建议重试,若多次重试失败,可向平台反馈该问题 |
200 | 11009 | 参数不合法或缺少参数 | 检查参数合法性,注意参数类型以及是否缺少必要参数 |
200 | 28001003 | access_token无效 | 请检查access_token |
200 | 28001007 | 必填字段缺失 | 请检查必填字段 |
200 | 28001008 | access_token过期 | 请刷新或重新授权access_token |