获取直播大屏数据 | 微信开放文档

# 获取直播大屏数据

# 接口调用请求说明

POST https://api.weixin.qq.com/channels/livedashboard/getlivedata?access_token=ACCESS_TOKEN

# 请求参数实例

{
    "export_id": "export/UzFf*****************************************************************************************64V"
}

# 请求参数说明

参数	类型	说明
export_id	string	直播唯一ID

# 回包参数说明

参数	类型	说明
errcode	number	错误码
errmsg	string	错误信息
trace_id	string	追踪ID，报bug带
live_dashboard_data	string	直播大屏基础数据json，对应实体 `LiveDashboardData`
live_comparison_index	string	内容力数据json，对应实体 `LiveComparisonIndex`
live_ec_data_summary	string	电商数据概要数据json，对应实体 `LiveEcDataSummary`
live_ec_conversion_metric	string	电商转化力数据json，对应实体 `LiveEcConversionMetric`
live_ec_profile	string	电商画像数据json，对应实体 `LiveEcProfile`
live_distribution_channel	string	电商渠道分布json，对应实体 `LiveDistributionChannel`
single_live_ec_spu_data_page_v2	string	电商商品数据json，对应实体 `SingleLiveEcSpuDataPageV2`

# 枚举

# DimensionType

枚举值	含义
1	一级渠道
2	年龄段
3	性别
5	关注关系
7	二级渠道
9	策略人群
10	省级行政区
11	地级行政区
12	消费者商品类目偏好
13	客单价区间
15	关注关系
16	流量类型（自然流量、直播加热、广告投流）

# LiveDistributionChannel_LiveDistributionSceneType

枚举值	含义
6	商品曝光
7	直播间曝光次数
8	商品点击次数
9	创建订单数按渠道统计
10	成交订单数按渠道统计

# 实体

# LiveDashboardData

参数	类型	说明
LiveDashboardData2	LiveDashboardData

# LiveDashboardData2

参数	类型	说明
summary	LiveDashboardData2Summary	直播基础数据
source	LiveDashboardData2Source	直播流量渠道
portrait	LiveDashboardData2Portrait	直播观众画像

# LiveDashboardData2Summary

参数	类型	说明
new_watch_uv	number	观看人数
max_online_wtch_uv	number	最大在线人数
impression_uv	number	曝光人数
average_watch_seconds_per_audience	number	平均观看时长（秒）
new_follow_uv	number	新增关注人数
new_fans_club_uv	number	新增粉丝团人数
comment_uv	number	评论人数
reward_uv	number	打赏人数
sharing_uv	number	分享直播间人数
hot_quota	number	热度

例子：

{
  "new_watch_uv": 85609,
  "max_online_watch_uv": 602,
  "impression_uv": 287771,
  "average_watch_seconds_per_audience": 60,
  "new_follow_uv": 179,
  "new_fans_club_uv": 0,
  "comment_uv": 525,
  "reward_uv": 1,
  "sharing_uv": 85,
  "hot_quota": 1
}

# LiveDashboardData2Source

参数	类型	说明
new_watch_uv	array[Series]	观看人数的渠道分布

new_watch_uv 的维度组合有两种：

16
16, 1, 7

参见 DimensionType。

# LiveDashboardData2Portrait

参数	类型	说明
online_watch_uv	array[Series]	在线人数的画像
new_watch_uv	array[Series]	观看人数的画像

对于 online_watch_uv 里的所有时间戳字段无意义，毋须理解。online_watch_uv 里的数据仅在直播中时有效，直播结束后该字段的值无意义。

online_watch_uv 和 new_watch_uv 的维度组合有八种：

这八种维度组合都是由单个维度构成。参见 DimensionType。

# Series

Series 是带有维度标签的时间序列，Series 与指标的类型无关。

参数	类型	说明
points	array[Point]	数据点
dimensions	array[Dimension]	描述时间序列的维度标签
step	number	每个数据点描述的时间长度（秒）
begin_ts	number	该时间序列的起始时间戳
end_ts	number	该时间序列的结束时间戳

当 step、begin_ts、end_ts 全为 0 或空时，代表该 Series 描述的是整场直播的数据，此时数据 points 内的点数恒为 1 个。除此情形外，可以保证:

begin_ts 小于等于 end_ts；
step、begin_ts、end_ts 均不小于零；
(begin_ts-end_ts) 能被 step 整除；
(begin_ts-end_ts)/step 和数组 points 的长度相等。

注意：参数 points 内的数据点不保证按照时间排序。参数 dimensions 内的维度不保证任何顺序。

例子1:

{
  "points": [
    {
      "ts": 1718038800,
      "value": 52084
    },
    {
      "ts": 1718042400,
      "value": 840436
    }
  ],
  "dimensions": [
    {
      "type": 16,
      "ux_label": "私域流量",
      "dimension_value": 4
    },
    {
      "type": 1,
      "ux_label": "分享",
      "dimension_value": 3
    },
    {
      "type": 7,
      "ux_label": "聊天页",
      "dimension_value": 4
    }
  ],
  "step": 3600,
  "begin_ts": 1718038800,
  "end_ts": 1718046000
}

这个例子是一个描述从 2024 年 6 月 11 日 1:00 (begin_ts=1718038800) 到 2024 年 6 月 11 日 3:00 (end_ts=1718046000) 的时间序列，每个数据点描述一个小时（step=3600）的时间范围，刻画了流量类型为 私域流量、一级渠道为分享、二级渠道为 聊天页 的指标。

从字段 points[0] 可知，从 1:00-2:00 的时间段，该指标值为 52084；
从字段 points[1] 可知，从 2:00-3:00 的时间段，该指标值为 840436。

例子2：

{
  "points": [
    {
      "ts": 0,
      "value": 62163
    }
  ],
  "dimensions": [
    {
      "type": 16,
      "ux_label": "广告投流",
      "dimension_value": 3
    }
  ],
  "step": 0,
  "begin_ts": 0,
  "end_ts": 0
}

这个例子是一个描述 整场直播 的特殊时间序列，刻画了流量类型为 广告投流 的指标。

# Point

参数	类型	说明
ts	number	时间戳
value	number	指标值

例子：

{
  "ts": 1718042400,
  "value": 840436
}

# Dimension

参数	类型	说明
type	DimensionType	维度的类型
ux_label	string	维度值

该实体内的其他字段在本接口内无实际意义。

例子：

{
  "type": 1,
  "ux_label": "分享",
  "dimension_value": 3
},

# LiveComparisonIndex

参数	类型	说明
is_living	boolean	是否正在直播
on_air.recommend_effective_new_watch_2_uv_over_impression_uv	LiveComparisonIndex_OnAirIndexItem	曝光有效CTR（万分比）
on_air.average_watch_seconds	LiveComparisonIndex_OnAirIndexItem	人均看播时长
on_air.comment_uv_over_new_watch_uv	LiveComparisonIndex_OnAirIndexItem	评论率（万分比）
on_air.like_uv_over_new_watch_uv	LiveComparisonIndex_OnAirIndexItem	点赞率（万分比）
ended.recommend_effective_new_watch_2_uv_over_impression_uv	LiveComparisonIndex_EndedIndexItem	曝光有效CTR（万分比）
ended.average_watch_seconds	LiveComparisonIndex_EndedIndexItem	人均看播时长
ended.comment_uv_over_new_watch_uv	LiveComparisonIndex_EndedIndexItem	评论率（万分比）
ended.like_uv_over_new_watch_uv	LiveComparisonIndex_EndedIndexItem	点赞率（万分比）

在播时，字段 ended 为空；关播后，字段 on_air 为空。

例子:

{
  "is_living": true,
  "on_air": {
    "recommend_effective_new_watch_2_uv_over_impression_uv": {
      "n": 10,
      "last_n_mins_value": 187,
      "last_2n_to_n_mins_value": 161,
      "last_n_mins_percentile": 40,
      "value": 134,
      "percentile": 20
    },
    "average_watch_seconds": {
      "n": 10,
      "last_n_mins_value": 51,
      "last_2n_to_n_mins_value": 48,
      "last_n_mins_percentile": 30,
      "value": 60,
      "percentile": 40
    },
    "comment_uv_over_new_watch_uv": {
      "n": 10,
      "last_n_mins_value": 103,
      "last_2n_to_n_mins_value": 68,
      "last_n_mins_percentile": 40,
      "value": 61,
      "percentile": 20
    },
    "like_uv_over_new_watch_uv": {
      "n": 10,
      "last_n_mins_value": 12,
      "last_2n_to_n_mins_value": 36,
      "last_n_mins_percentile": 60,
      "value": 38,
      "percentile": 30
    }
  }
}

# LiveComparisonIndex_OnAirIndexItem

参数	类型	说明
n	number	描述最近多少分钟的指标值
last_n_mins_value	number	最近 n 分钟该指标的值
last_2n_to_n_mins_value	number	最近 2n 到 n 分钟该指标的值（用于环比）
last_n_mins_percentile	number	最近 n 分钟该指标值打败了 xx% 的在播主播
value	number	整场直播的指标值
percentile	number	整场直播该指标值打败了 xx% 的主播

注意，这里每个字段都有可能会不存在。

# LiveComparisonIndex_EndedIndexItem

参数	类型	说明
value	number	整场直播的指标值
percentile	number	整场直播该指标值打败了 xx% 的主播
median_7_days	number	该指标 7 天中位数

注意，这里每个字段都有可能会不存在。

# LiveEcDataSummary

参数	类型	说明
total_gmv	number	成交金额（单位：分）
total_pay_pv	number	成交次数
total_pay_uv	number	成交人数
total_create_pv	number	订单创建次数
total_create_uv	number	订单创建人数
refund_amount	number	退款金额（单位：分）

注意，文档未列出的指标是未定义。

例子:

{
    "total_gmv": 16564600,
    "total_pay_uv": 537,
    "total_pay_pv": 553,
    "total_create_uv": 590,
    "total_create_pv": 612,
    "refund_amount": 717600
}

# LiveEcConversionMetric

参数	类型	说明
recent_10_min_conversion	LiveEcConversionMetric_ConversionMetric	近10分钟转化率数据
whole_live_conversion	LiveEcConversionMetric_ConversionMetric	整场直播

# LiveEcConversionMetric_ConversionMetric

参数	类型	说明
product_view_click_conversion_ratio	ItemConversionMetric	商品曝光-点击转化率
bubble_view_click_conversion_ratio	ItemConversionMetric	气泡曝光-点击转化率
pay_conversion_ratio	ItemConversionMetric	成交转化率
k_view_pay_conversion_ratio	ItemConversionMetric	千次观看成交金额（单位：分）
update_time	number	更新时间
product_list_click_conversion_ratio	ItemConversionMetric	购物袋商品点击率
shelftime	number	挂车时间（>0 则为挂车）

# LiveEcConversionMetric_ItemConversionMetric

参数	类型	说明
metric_value	number	指标值
median_to_recent_7_days	number	较近7天中位数
within_industry_percentage	number	同行对比
quarterly_growth_rate.value	number	环比（近10分钟转化率数据才有）
quarterly_growth_rate.is_valid	boolean	环比是否是有效值（如果是false说明分母是0）

# LiveEcProfile

参数	类型	说明
profiles	array[LiveEcProfile_DataNodeThirdList]	包含不同用户群体的统计数据
totals	array[LiveEcProfile_DataNodeList]	总体数据统计信息

# LiveEcProfile_DataNodeThirdList

参数	类型	说明
key	string	每个对象包含一个 key，表示用户群体的名称，例如 "已成交用户"、"首次购买用户"、"复购用户"
row	array[LiveEcProfile_DataNodeSecondList]	包含该用户群体下不同分类的统计数据

例子：

{
  "key": "已成交用户",
  "row": [
    {
      "key": "sex_distribution",
      "row": [
        {
          "key": "女",
          "row": {
            "fields": {
              "dim_val": "506",
              "dim_val_ratio": "0.942272",
              "dim_key": "女"
            }
          }
        },
        {
          "key": "男",
          "row": {
            "fields": {
              "dim_key": "男",
              "dim_val": "31",
              "dim_val_ratio": "0.057728"
            }
          }
        }
      ]
    },
    {
      "key": "age_distribution",
      "row": [
        {
          "key": "30-39岁",
          "row": {
            "fields": {
              "dim_val": "234",
              "dim_val_ratio": "0.435754",
              "dim_key": "30-39岁"
            }
          }
        },
        {
          "key": "40-49岁",
          "row": {
            "fields": {
              "dim_val": "261",
              "dim_val_ratio": "0.486034",
              "dim_key": "40-49岁"
            }
          }
        },
        {
          "key": "50岁以上",
          "row": {
            "fields": {
              "dim_key": "50岁以上",
              "dim_val": "42",
              "dim_val_ratio": "0.078212"
            }
          }
        }
      ]
    },
    {
      "key": "province_distribution",
      "row": [
        {
          "key": "天津市",
          "row": {
            "fields": {
              "dim_key": "天津市",
              "dim_val": "11",
              "dim_val_ratio": "0.020484"
            }
          }
        },
        "此处省略剩余的省级行政区"
      ]
    },
    {
      "key": "city_distribution",
      "row": [
        {
          "key": "天津市",
          "row": {
            "fields": {
              "dim_key": "天津市",
              "dim_val": "11",
              "dim_val_ratio": "0.020484"
            }
          }
        },
        "此处省略剩余的地级行政区"
      ]
    },
    {
      "key": "follow_distribution",
      "row": [
        {
          "key": "未关注用户",
          "row": {
            "fields": {
              "dim_val": "500",
              "dim_val_ratio": "0.931099",
              "dim_key": "未关注用户"
            }
          }
        },
        {
          "key": "关注用户",
          "row": {
            "fields": {
              "dim_key": "关注用户",
              "dim_val": "37",
              "dim_val_ratio": "0.068901"
            }
          }
        }
      ]
    },
    {
      "key": "cate_distribution",
      "row": [
        {
          "key": "服饰内衣",
          "row": {
            "fields": {
              "dim_val_ratio": "0.366853",
              "dim_key": "服饰内衣",
              "dim_val": "197"
            }
          }
        },
        {
          "key": "食品饮料",
          "row": {
            "fields": {
              "dim_val_ratio": "0.111732",
              "dim_key": "食品饮料",
              "dim_val": "60"
            }
          }
        },
        "此处省略剩余的消费者类目分布"
      ]
    },
    {
      "key": "ecom_user_level_distribution",
      "row": [
        {
          "key": "新锐白领",
          "row": {
            "fields": {
              "dim_val_ratio": "0.549348",
              "dim_key": "新锐白领",
              "dim_val": "295"
            }
          }
        },
        "此处省略剩余的策略人群"
      ]
    },
    {
      "key": "gmv_per_cnt_distribution",
      "row": [
        {
          "key": "0-99",
          "row": {
            "fields": {
              "dim_val": "330",
              "dim_val_ratio": "0.614525",
              "dim_key": "0-99"
            }
          }
        },
        "此处省略剩余的平均客单价分布"
      ]
    }
  ]
}

# LiveEcProfile_DataNodeSecondList

参数	类型	说明
key	string	每个分类对象都有一个 key，表示分类的名称，例如 "sex_distribution"、"age_distribution"
row	array[LiveEcProfile_DataNodeList]	进一步细分该分类下的数据

这一层级的 key 包含以下枚举：

key	含义
sex_distribution	性别分布
age_distribution	年龄分布
province_distribution	省份分布
city_distribution	城市分布
follow_distribution	关注关系分布
cate_distribution	策略人群分布
ecom_user_level_distribution	商品类目偏好分布
gmv_per_cnt_distribution	平均客单价分布

# LiveEcProfile_DataNodeList

参数	类型	说明
key	string	细分类别的名称，如 "女"、"30-39岁"、"天津市"
row	LiveEcProfile_DataNode	包含具体的统计数值

例子：

{
    "key": "30-39岁",
    "row": {
        "fields": {
            "dim_val": "234",
            "dim_val_ratio": "0.435754",
            "dim_key": "30-39岁"
        }
    }
}

# LiveEcProfile_DataNode

参数	类型	说明
fields.dim_key	string	维度值
fields.dim_val	string	指标值
fields.dim_val_ratio	string	指标值比例

例子：

{
    "fields": {
        "dim_key": "100-299",
        "dim_val": "173",
        "dim_val_ratio": "0.322160"
    }
}

以上例子表示了一个维度值为 100-299 的数据点，数据点的值是 173。

# LiveDistributionChannel

参数	类型	说明
live_dist_channel_source_by_scene_stats	LiveDistributionChannel_LiveDistributionSceneStat	按场景划分的渠道分析统计值
live_dist_channel_source_stats	LiveDistributionChannel_LiveDistributionByFlowTypeStat	按照流量类型、渠道层级划分的渠道分析统计数据

# LiveDistributionChannel_LiveDistributionSceneStat

参数	类型	说明
scene_type	LiveDistributionChannel_LiveDistributionSceneType	场景类型
dist_flow_type_stats	LiveDistributionChannel_LiveDistributionByFlowTypeStat	该场景下的渠道分析统计值
metric_value_total	number	指标值总数
gmv	number	GMV总值（单位：分）
uv	number	UV总值
gmv_per_uv	number	千次看播成交（单位：分）
metric_value	number	指标值
metric_value_ratio	number	在该渠道下的统计值比率
pv	number	pv

例子:

{
    "scene_type": 1,
    "dist_flow_type_stats": [
        {
            "live_dst_channel_type": 1,
            "metric_value": 5285,
            "channel_source_stats": [],
            "metric_value_ratio": 0.041437655342203686
        },
        {
            "live_dst_channel_type": 2,
            "metric_value": 14758,
            "channel_source_stats": [],
            "metric_value_ratio": 0.11571181031981873
        },
        {
            "live_dst_channel_type": 3,
            "metric_value": 107498,
            "channel_source_stats": [],
            "metric_value_ratio": 0.8428505343379776
        }
    ],
    "metric_value_total": 127541
}

# LiveDistributionChannel_LiveDistributionByFlowTypeStat

参数	类型	说明
live_dst_channel_type	LiveDistributionChannel_LiveDistributionFlowType	渠道流量类型
j	LiveDistributionChannel_LiveDistChannelSourceStats	一级类目渠道来源指标划分
gmv	number	GMV总值（单位：分）
uv	number	UV总值
gmv_per_uv	number	千次看播成交（单位：分）(GPV)
pv	number	PV总值
pv_ratio	number	当前层级pv占总pv的比例
uv_ratio	number	uv占比

# LiveDistributionChannel_LiveDistChannelSourceStats

指标渠道来源统计分析统计数据。

参数	类型	说明
level	number	渠道层级
source_channel_id	number	来源渠道ID
sub_channel_source_stats	LiveDistributionChannel_SubLiveDistChannelSourceStats	流量来源子渠道指标数据统计值
gmv	number	GMV总值（单位：分）
uv	number	UV总值
gmv_per_uv	number	千次看播成交（单位：分）(GPV)
gmv_ratio	number	gmv占比
uv_ratio	number	uv占比
source_channel_name	string	渠道名称
pv_ratio	number	当前层级pv占总pv的比例

例子：

{
    "level": 1,
    "source_channel_id": 3,
    "sub_channel_source_stats": [
        {
            "level": 2,
            "source_channel_id": 3,
            "gmv": 0,
            "uv": 0,
            "gmv_ratio": 0.0,
            "uv_ratio": 0.0,
            "source_channel_name": "朋友圈"
        },
        {
            "level": 2,
            "source_channel_id": 4,
            "gmv": 269100,
            "uv": 8,
            "gmv_ratio": 1.0,
            "uv_ratio": 1.0,
            "source_channel_name": "聊天页"
        },
        {
            "level": 2,
            "source_channel_id": 5,
            "gmv": 0,
            "uv": 0,
            "gmv_ratio": 0.0,
            "uv_ratio": 0.0,
            "source_channel_name": "其他"
        }
    ],
    "gmv": 269100,
    "uv": 8,
    "gmv_ratio": 0.125,
    "uv_ratio": 0.11764705882352941,
    "source_channel_name": "分享"
}

# LiveDistributionChannel_SubLiveDistChannelSourceStats

指标渠道来源统计分析统计数据（二级）。

参数	类型	说明
level	number	渠道层级
source_channel_id	number	来源渠道ID
metric_value	number	在该渠道下的统计值
gmv	number	GMV总值（单位：分）
uv	number	UV总值
gmv_per_uv	number	千次看播成交（单位：分）
gmv_ratio	number	gmv占比
uv_ratio	number	uv占比
metric_value_ratio	number	在该渠道下的统计值比率
source_channel_name	string	渠道名称
pv	number	pv
pv_ratio	number	pv在该渠道下的统计值比率

# SingleLiveEcSpuDataPageV2

参数	类型	说明
spu_data_list	array[SingleLiveEcSpuDataPageV2_SpuData]	商品明细数据
total_cnt	number	spu_data_list 的总长度

# SingleLiveEcSpuDataPageV2_SpuData

参数	类型	说明
base_data.src_spu_id	string	商品id
base_data.src	number	店铺名称
base_data.spu_name	string	商品名称
exp_uv	number	商品曝光人数
clk_uv	number	商品点击人数
share_uv	number	商品分享人数
clk_pv	number	商品点击次数
exp_clk_ratio	number	商品曝光点击率
clk_pay_ratio	number	商品点击成交率
gmv	number	商品成交金额（单位：分）
pay_pv	number	商品成交订单数
refund_amount	number	商品退款金额（单位：分）
refund_pv	number	商品退款订单数

文档未列出的指标是无定义的。

# 错误码

错误码	错误信息
公共错误码	点击查看
1	请求参数错误
其他错误码	内部错误