广告分析数据接口说明

向所有成为流量主的公众号、小程序、小游戏开发者开放数据接口。通过数据接口,开发者可以获取与公众平台官网统计模块类似但更灵活的数据,还可根据需要进行高级处理。

请注意:

  1. 接口侧数据库中仅存储了2016年1月1日之后的数据,将无法查询到此前的数据,即使查到,也是不可信的脏数据;

  2. 建议开发者在调用接口获取数据后,将数据保存在自身数据库中,以最大化访问的效率,也降低微信侧接口调用的不必要损耗;

  3. 由于数据量较大, 所有接口采取分页获取的方式, 每页最大获取量为90。(eg:total_num 为100,则当page = 1,page_size = 10,则返回前10条;page = 1,page_size = 20,则返回前20条;page = 2,page_size = 10,则返回第11条到第20条)

  4. 广告位枚举值变更说明

    • 由于多个接口都使用了广告位参数,为保证体验的一致性和参数的可读性,我们做了一些变更,所有接口均支持以 广告位类型名称(ad_slot) 传递参数,回包时新增这个名称来代表相关含义。此前的参数 slot_id 也可继续使用并回传。具体为:
广告位类型名称(ad_slot)广告位类型
SLOT_ID_BIZ_BOTTOM公众号底部广告
SLOT_ID_BIZ_MID_CONTEXT公众号文中广告
SLOT_ID_BIZ_VIDEO_END公众号视频后贴
SLOT_ID_BIZ_SPONSOR公众号互选广告
SLOT_ID_BIZ_CPS公众号返佣商品
SLOT_ID_WEAPP_BANNER小程序banner
SLOT_ID_WEAPP_REWARD_VIDEO小程序激励视频
SLOT_ID_WEAPP_INTERSTITIAL小程序插屏广告
SLOT_ID_WEAPP_VIDEO_FEEDS小程序视频广告
SLOT_ID_WEAPP_VIDEO_BEGIN小程序视频前贴
SLOT_ID_WEAPP_BOX小程序格子广告
SLOT_ID_WEAPP_TEMPLATE小程序原生模板广告
SLOT_ID_WEAPP_COVER封面广告

接口总览

广告分析接口目前可用于获得“公众平台 → 流量主 → 数据统计”页面展示的部分广告数据和“公众平台 → 流量主 → 财务管理”页面展示的部分收入数据,与小程序相关的接口列表如下:

接口名称用途最大时间跨度接口调用地址(必须使用https)
publisher_adpos_general获取小程序广告汇总数据90天https://api.weixin.qq.com/publisher/stat?action=publisher_adpos_general&access_token=ACCESS_TOKEN
publisher_adunit_general获取小程序广告细分数据90天https://api.weixin.qq.com/publisher/stat?action=publisher_adunit_general&access_token=ACCESS_TOKEN
get_adunit_list获取小程序广告位清单https://api.weixin.qq.com/publisher/stat?action=get_adunit_list&access_token=ACCESS_TOKEN
publisher_settlement获取小程序结算收入数据及结算主体信息https://api.weixin.qq.com/publisher/stat?action=publisher_settlement&access_token=ACCESS_TOKEN

接口调用请求说明

一、获取小程序广告汇总数据(publisher_adpos_general)

需要向相应接口调用地址增加以下GET请求参数:

参数是否必须说明
page返回第几页数据
page_size当页返回数据条数
start_date获取数据的开始时间 yyyy-mm-dd
end_date获取数据的结束时间 yyyy-mm-dd
ad_slot广告位类型名称

请注意: 如果不传递广告位类型名称,将默认返回全部类型广告位的数据。

返回参数说明(publisher_adpos_general)

参数说明
err_msg返回错误信息
ret错误码
list: slot_id广告位类型id
list: ad_slot广告位类型名称
list: date日期
list: req_succ_count拉取量
list: exposure_count曝光量
list: exposure_rate曝光率
list: click_count点击量
list: click_rate点击率
list: income收入(分)
list: ecpm广告千次曝光收益(分)
summary: req_succ_count总拉取量
summary: exposure_count总曝光量
summary: exposure_rate总曝光率
summary: click_count总点击量
summary: click_rate总点击率
summary: income总收入(分)
summary: ecpm广告千次曝光收益(分)
total_numlist返回总条数

返回数据包示例(publisher_adpos_general)

  1. {
  2. "base_resp":{
  3. "err_msg":"ok",
  4. "ret":0
  5. },
  6. "list":[
  7. {
  8. "slot_id":3030046789020061,
  9. "ad_slot":"SLOT_ID_WEAPP_INTERSTITIAL",
  10. "date":"2020-04-13",
  11. "req_succ_count":443610,
  12. "exposure_count":181814,
  13. "exposure_rate":0.409850995,
  14. "click_count":10095,
  15. "click_rate":0.055523777,
  16. "income":52175,
  17. "ecpm":286.969100289
  18. }
  19. ],
  20. "summary":{
  21. "req_succ_count":4406394,
  22. "exposure_count":1797225,
  23. "exposure_rate":0.407867522,
  24. "click_count":100167,
  25. "click_rate":0.055734257,
  26. "income":578003,
  27. "ecpm":321.608591022
  28. },
  29. "total_num":1
  30. }
二、获取小程序广告细分数据(publisher_adunit_general)

需要向相应接口调用地址增加以下GET请求参数:

参数是否必须说明
page返回第几页数据
page_size当页返回数据条数
start_date获取数据的起始日期 yyyy-mm-dd
end_date获取数据的结束时间 yyyy-mm-dd
ad_slot广告位类型名称
ad_unit_id广告位id

请注意: 当需要获取全部广告位的细分数据时,无需传递广告位类型名称及广告位id;当需要获取某类型广告位的细分数据时,仅需传递广告位类型名称;当需要获取某广告位id的细分数据时,仅需传递广告位id。

返回参数说明(publisher_adunit_general)

参数说明
err_msg返回错误信息
ret错误码
list: ad_unit_id广告位id
list: ad_unit_name广告位名称
list: stat_item: ad_slot广告位类型名称
list: stat_item :date数据日期
list: stat_item :req_succ_count拉取量
list: stat_item :exposure_count曝光量
list: stat_item: exposure_rate曝光率
list: stat_item :click_count点击量
list: stat_item :click_rate点击率
list: stat_item :income收入
list: stat_item :ecpm广告千次曝光收益(分)
total_num请求返回总数

返回数据包示例(publisher_adunit_general)

  1. {
  2. "base_resp":{
  3. "err_msg":"ok",
  4. "ret":0
  5. },
  6. "list":[
  7. {
  8. "ad_unit_id":"adunit-9cedd8514XXXX",
  9. "ad_unit_name":"激励视频长广告",
  10. "stat_item":{
  11. "ad_slot":"SLOT_ID_WEAPP_REWARD_VIDEO",
  12. "date":"2020-04-10",
  13. "req_succ_count":138250,
  14. "exposure_count":74771,
  15. "exposure_rate":0.54083906,
  16. "click_count":2242,
  17. "click_rate":0.029984887,
  18. "income":93883,
  19. "ecpm":6.790813743
  20. }
  21. }
  22. ],
  23. "total_num":1
  24. }
三、获取小程序广告位清单(get_adunit_list)

需要向相应接口调用地址增加以下GET请求参数:

参数是否必须说明
page返回第几页数据
page_size当页返回数据条数
ad_slot广告位类型名称
ad_unit_id广告位id

请注意: 当需要获取全部广告位的清单时,无需传递广告位类型名称及广告位id;当需要获取某类型广告位的清单时,仅需传递广告位类型名称;当需要获取某广告位id的数据时,仅需传递广告位id。

返回参数说明(get_adunit_list)

参数说明
err_msg返回错误信息
ret错误码
ad_slot广告位类型名称
ad_unit_id广告位ID
ad_unit_name广告位名称
ad_unit_size广告位尺寸
ad_unit_status广告位状态

返回数据包示例(get_adunit_list)

  1. {
  2. "base_resp":{
  3. "err_msg":"ok",
  4. "ret":0
  5. },
  6. "ad_unit":[
  7. {
  8. "ad_slot":"SLOT_ID_WEAPP_REWARD_VIDEO",
  9. "ad_unit_id":"adunit-e9418ee19XXXXX",
  10. "ad_unit_name":"rewaXXXX",
  11. "ad_unit_size":[
  12. {
  13. "height":166,
  14. "width":582
  15. }
  16. ],
  17. "ad_unit_status":"AD_UNIT_STATUS_ON",
  18. "ad_unit_type":"AD_UNIT_TYPE_REWARED_VIDEO",
  19. "appid":"wx0afc78670fXXXX",
  20. "video_duration_max":30,
  21. "video_duration_min":6
  22. }
  23. ],
  24. "total_num":1
  25. }
四、获取小程序结算收入数据及结算主体信息(publisher_settlement)

需要向相应接口调用地址增加以下GET请求参数:

参数是否必须说明
page数据返回页数
page_size每页返回数据条数
start_date获取数据的开始时间 yyyy-mm-dd
end_date获取数据的结束时间 yyyy-mm-dd

请注意: 只要与获取数据的起止时间有重合,结算区间对应的数据都将返回。例如,请求2月11日至3月26日的数据,将会返回2月上半月、2月下半月、3月上半月、3月下半月四个结算区间的数据。

返回参数说明(publisher_settlement)

参数说明
err_msg返回错误信息
ret错误码
body主体名称
revenue_all累计收入
penalty_all扣除金额
settled_revenue_all已结算金额
settlement_list: date数据更新时间
settlement_list: zone日期区间
settlement_list: month收入月份
settlement_list: order1 = 上半月,2 = 下半月
settlement_list: sett_status1 = 结算中;2、3 = 已结算;4 = 付款中;5 = 已付款
settlement_list: settled_revenue区间内结算收入
settlement_list: sett_no结算单编号
settlement_list: mail_send_cnt申请补发结算单次数
settlement_list: slot_revenue: slot_id产生收入的广告位
settlement_list: slot_revenue: slot_settled_revenue该广告位结算金额
total_num请求返回总条数

返回数据包示例(publisher_settlement)

  1. {
  2. "base_resp":{
  3. "err_msg":"ok",
  4. "ret":0
  5. },
  6. "body":"深圳市腾讯计算机系统有限公司",
  7. "penalty_all":0,
  8. "revenue_all":5178368698,
  9. "settled_revenue_all":2613696765,
  10. "settlement_list":[
  11. {
  12. "date":"2020-03-25",
  13. "zone":"2020年3月1日至15日"
  14. "month":"202003",
  15. "order":1,
  16. "sett_status":1,
  17. "settled_revenue":718926045,
  18. "sett_no":"XXX",
  19. "mail_send_cnt":"0",
  20. "slot_revenue":[
  21. {
  22. "slot_id":"SLOT_ID_WEAPP_BANNER",
  23. "slot_settled_revenue":34139443
  24. },
  25. {
  26. "slot_id":"SLOT_ID_WEAPP_REWARD_VIDEO",
  27. "slot_settled_revenue":684786602
  28. }
  29. ]
  30. }
  31. ],
  32. "total_num":1
  33. }

错误码说明

错误码返回值含义
45009请求过于频繁, 请稍后尝试
45010无效的接口名
1701参数错误
2009无效的流量主