文档

# 广告分析数据接口说明

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

# 1. 接口侧数据库中仅存储了2019年9月1日之后的数据，将无法查询到此前的数据，即使查到，也是不可信的脏数据；
# 2. 建议开发者在调用接口获取数据后，将数据保存在自身数据库中，以最大化访问的效率，也降低QQ侧接口调用的不必要损耗；
# 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）

由于多个接口都使用了广告位参数，为保证体验的一致性和参数的可读性，所有接口均支持以 广告位类型名称（ad_slot） 传递参数，回包时新增这个名称来代表相关含义。具体为：

广告位类型名称（ad_slot） 广告位类型
SLOT_ID_APPBOX 盒子广告
SLOT_ID_BANNER banner广告
SLOT_ID_BLOCK 积木广告
SLOT_ID_CARD 卡片广告
SLOT_ID_FEEDS feeds广告
SLOT_ID_INTERSTITIAL 插屏广告
SLOT_ID_LOADING loading广告
SLOT_ID_REWARDEDVIDEO 激励视频广告

# 接口总览

广告分析接口目前可用于获得“功能 → 广告接入 → 广告数据”页面展示的部分广告数据。接口列表如下:

接口名称 用途 最大时间跨度 接口调用地址（必须使用https）
publisher_adpos_general 获取广告汇总数据 90天 https://api.q.qq.com/api/getAdvData?action=publisher_adpos_general&access_token=ACCESS_TOKEN
publisher_adunit_general 获取广告细分数据 90天 https://api.q.qq.com/api/getAdvData?action=publisher_adunit_general&access_token=ACCESS_TOKEN

即：需要向相应接口调用URL 增加以下Key

参数 是否必须 说明
action 是 接口名
access_token 是 接口调用凭证

# 获取access_token 示例

APPID 和 SECRET 见“开发 → 开发设置” 页面

$ curl 'https://api.q.qq.com/api/getToken?grant_type=client_credential&appid=APPID&secret=SECRET'
1

# 广告汇总数据

# publisher_adpos_general

需要向相应接口调用地址增加以下POST请求参数（json）

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

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

# 请求示例

$ curl -d '{"page":1,"page_size":1,"start_date":"2021-06-01","end_date":"2021-06-01","ad_slot":"SLOT_ID_BANNER"}' -H 'Content-type: application/json' 'https://api.q.qq.com/api/getAdvData?action=publisher_adpos_general&access_token=ACESS_TOKEN'
1

# 返回参数说明

参数 说明
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返回总条数

# 返回数据包示例

{
    "base_resp":{
        "err_msg":"ok",
        "ret":0
    },
    "list":[
        {
            "slot_id":1045256048275972,
            "ad_slot":"SLOT_ID_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
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

# 广告细分数据

# publisher_adunit_general

需要向相应接口调用地址增加以下POST请求参数（json）

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

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

# 请求示例

$ curl -d '{"page":1,"page_size":1,"start_date":"2021-06-01","end_date":"2021-06-01","ad_slot":"SLOT_ID_BANNER","ad_unit_id":"ckl435l2m3n110g9c30878ddk2labzp"}' -H 'Content-type: application/json' 'https://api.q.qq.com/api/getAdvData?action=publisher_adunit_general&access_token=ACESS_TOKEN'
1

# 返回参数说明

参数 说明
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 list返回总条数

# 返回数据包示例

{
    "base_resp":{
        "err_msg":"ok",
        "ret":0
    },
    "list":[
        {
            "ad_unit_id":"ckl435l2m3n110g9c30878ddk2labzp",
            "ad_unit_name":"插屏广告",
            "stat_item":{
                "ad_slot":"SLOT_ID_INTERSTITIAL",
                "date":"2020-04-10",
                "req_succ_count":138250,
                "exposure_count":74771,
                "exposure_rate":0.54083906,
                "click_count":2242,
                "click_rate":0.029984887,
                "income":93883,
                "ecpm":6.790813743
            }
        }
    ],
    "total_num":1
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 错误码说明

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

← 交互 →