广告数据分析接口说明

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

请注意:

  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 小程序格子广告

接口总览

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

接口名称 用途 最大时间跨度 接口调用地址(必须使用https)
publisher_adpos_general 获取公众号分广告位数据 90天 https://api.weixin.qq.com/publisher/stat?action=publisher_adpos_general&access_token=ACCESS_TOKEN
publisher_cps_general 获取公众号返佣商品数据 60天 https://api.weixin.qq.com/publisher/stat?action=publisher_cps_general&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_num list返回总条数

返回数据包示例(publisher_adpos_general)

{
    "base_resp":{
        "err_msg":"ok",
        "ret":0
    },
    "list":[
        {
            "slot_id":3030046789020061,
            "ad_slot":"SLOT_ID_WEAPP_INTERSTITIAL",
            "date":"2020-04-13",
            "req_succ_count":443610,
            "exposure_count":181814,
            "exposure_rate":0.409850995,
            "click_count":10095,
            "click_rate":0.055523777,
            "income":52175,
            "ecpm":286.969100289
        }
    ],
    "summary":{
        "req_succ_count":4406394,
        "exposure_count":1797225,
        "exposure_rate":0.407867522,
        "click_count":100167,
        "click_rate":0.055734257,
        "income":578003,
        "ecpm":321.608591022
    },
    "total_num":1
}

二、获取公众号返佣商品数据(publisher_cps_general)

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

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

请注意: 返佣商品广告不需要传递广告位参数。


返回参数说明(publisher_cps_general)

参数 说明
err_msg 返回错误信息
ret 错误码
list: date 日期
list: exposure_count 曝光量
list: click_count 点击量
list: click_rate 点击率
list: order_count 订单量
list: order_rate 下单率
list: total_fee 订单金额(分)
list: total_commission 预估收入(分)
summary: exposure_count 总曝光量
summary: click_count 总点击量
summary: click_rate 总点击率
summary: order_count 总下单量
summary: order_rate 总下单率
summary: total_fee 订单总金额(分)
summary: total_commission 总预估收入(分)
total_num 请求返回总条数

返回数据包示例(publisher_cps_general)

{
    "base_resp":{
        "err_msg":"ok",
        "ret":0
    },
    "list":[
        {
            "date":"20XX-XX-XX",
            "exposure_count":15153,
            "click_count":396,
            "click_rate":38.265151515,
            "order_count":3,
            "order_rate":0.007575758,
            "total_fee":162900,
            "total_commission":25021
        }
    ],
    "summary":{
        "exposure_count":117143,
        "click_count":3442,
        "click_rate":34.033410808,
        "order_count":18,
        "order_rate":0.005229518,
        "total_fee":924082,
        "total_commission":133030
    },
    "total_num":7
}

三、获取公众号结算收入数据及结算主体信息(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: order 1 = 上半月,2 = 下半月
settlement_list: sett_status 1 = 结算中;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)

{
    "base_resp":{
        "err_msg":"ok",
        "ret":0
    },
    "body":"深圳市腾讯计算机系统有限公司",
    "penalty_all":0,
    "revenue_all":5178368698,
    "settled_revenue_all":2613696765,
    "settlement_list":[
        {
            "date":"2020-03-25",
            "zone":"2020年3月1日至15日"
            "month":"202003",
            "order":1,
            "sett_status":1,
            "settled_revenue":718926045,
            "sett_no":"XXX",
            "mail_send_cnt":"0",
            "slot_revenue":[
                {
                    "slot_id":"SLOT_ID_WEAPP_BANNER",
                    "slot_settled_revenue":34139443
                },
                {
                    "slot_id":"SLOT_ID_WEAPP_REWARD_VIDEO",
                    "slot_settled_revenue":684786602
                }
            ]
        }
    ],
    "total_num":1
}

错误码说明

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