## 广告数据分析接口说明

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

请注意：

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）**

```json
{
    "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）** 

```json
{
    "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）**

```json
{
    "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         | 无效的流量主             |