菜单

综合报表

注意：接入Api前请先熟悉api签名机制（参考接口鉴权说明）, 即Api请求样例中的一些http请求头的来源

使用前说明：

● 申请开通报表API权限后：需要等大概等2到3小时左右才能获取到数据（否则数据列表是空，请耐心等待）

（如何确认是否有权限：登录TopOn后台，右上角下拉列表--账户管理--key页面，若有全局Publisher Key相应参数，则为已开通权限；若无，请联系TopOn运营开通权限。）

● 正常能获取到数据后，只能获取到申请开通权限那天向前推10天之后的数据，比如2月24号开通权限，只能获取到2月14号及之后日期的数据
● 历史数据不会更新（除非当时数据不完整，重拉过数据）
● 当天TopOn统计的数据（展示，点击等）每10分钟更新一次，更新频率基本和后台一致（时机不同可能会稍微延迟于后台）
● 昨天的三方数据（或者昨天的三方数据，三方收益，三方展示等）每两小时更新一次，会比开发者后台延迟2到3小时左右，比如开发者后台9点看到完整三方收益，openapi可能需要到12点左右

使用注意:

● 当请求参数group_by中存在维度scenario/traffic_group/channel/sdk_version/app_version中任意一个时，响应不返回api相关指标（request_api，fillrate_api，impression_api，click_api，ctr_api，ecpm_api，unit_ecpc，unit_ecpr）以及ecpm，ecpc，ecpr，revenue，black_revenue，black_ecpm，revenue_gap，ecpm_gap，impression_gap，click_gap
● 注意：所有带有API的相关指标为TopOn从三方平台广告后台拉取的数据。因此无法划分到场景、流量分组、渠道、SDK版本、应用版本等维度。不能划分的原因是三方平台后台实际上无法获得TopOn SDK统计到的场景、流量分组、渠道、SDK版本、应用版本等维度。
● 显示dau条件：
1. grouby条件必须只包含（一个或任意多个）以下维度："date","app","area","placement","scenario","channel"
2. filter过滤条件不要包含：network_firm_id_list，adsource_id_list
3. 如果grouby维度没有选中日期date，那么请求参数日期跨度必须只有一天，即startdate=enddate
●  显示deu条件：
1. grouby条件必须只包含（一个或任意多个）以下维度："date","app","area","placement","scenario","channel","adformat"
2. filter过滤条件不要包含：network_firm_id_list，adsource_id_list
3. 如果grouby维度没有选中日期date，那么请求参数日期跨度必须只有一天，即startdate=enddate
4. grouby维度有选中adformat时，必须也选中placement

使用技巧:

● 获取多个App数据：批量传入多个app_id，group by app即可 
● 获取多天数据：startdate和enddate传入一个时间段，group by date_time即可，由于数据更新不会很频繁，而且历史数据基本不会更新，建议每天更新最近2天数据就可以了
● 数据汇总：group by到最细维度，可以拿到结果后再作sum计算
 

1. 请求URL

https://api.toponad.net/v2/fullreport

2. 请求方式

POST

3. 请求参数

字段 类型 是否必传 备注 样例
startdate Int Y 开始日期，格式：YYYYmmdd 20190501
enddate Int Y 结束日期，格式：YYYYmmdd 20190506
app_id_list Array[String] N 开发者后台的应用ID列表 [“a600e6fbeac98c”]
placement_id_list Array[String] N 开发者后台的广告位ID列表 [“b601ce4ca8de81”]
time_zone String N 时区，枚举值：UTC-8、UTC+8、UTC+0，不传则默认使用开发者账号时区 “UTC-8”
network_firm_id_list Array[int32] N

广告平台ID列表，一些特殊平台ID:

TopOn Adx: 66

TopOn 交叉推广: 35

 [1,2]
adsource_id_list Array[int32] N 广告源ID列表 [121]
area_list Array[String] N 国家列表 [“US”,"CN"]
group_by Array[String] N

筛选维度列表，注意：最多只允许6个维度，支持的维度如下：
 date（日期，默认值）， app（应用）， placement（广告位）， adformat（广告样式）， area（地区）， network（广告平台账号）， adsource（广告源）， network_firm_id（广告平台）， scenario（广告场景）， traffic_group（流量分组）， channel（渠道）， sdk_version（sdk版本）， app_version（应用版本）。

 ["app","placement","area"]
metric Array[String] N

当同时选了all和其他指标时即返回全部指标： default（默认的一些指标：dau，arpu，request，fillrate，impression，click，ecpm，revenue，impression_api，click_api，ecpm_api），
all（全部指标），
dau（DAU）,
arpu（人均收益，单位美元），
cy_arpu（人均收益，单位按开发者币种），
request（广告请求数），
fillrate（广告填充率）， impression（展示数），
click（点击数），
ctr（点击率），
ecpm（ECPM），
revenue（收益），
request_api（三方广告平台的广告请求数），
fillrate_api（三方广告平台的广告填充率），
impression_api（三方广告平台的展示数），
click_api（三方广告平台的点击数），
ctr_api（三方广告平台的点击率），
ecpm_api（三方广告平台的ECPM），
 estimate_revenue（预估收益，美元单位）， estimate_revenue_ecpm（预估ECMP，美元单位），
ready_request（isReady调用次数），
ready_rate（isReady成功率）， cy_estimate_revenue（按开发者账号币种返回的预估收益）， cy_estimate_revenue_ecpm（按开发者账号币种返回的预估ECMP） bid_request（询价，仅竞价广告源会返回此数据。） bid_filled_request_rate(询价响应率，仅竞价广告源会返回此数据） bid_filled_request_ecpm(询价响应eCPM，仅竞价广告源会返回此数据，按开发者账号币种返回)

full_app_revenue(对应Meta App的整体收益，只有当前账号有Meta数据时才会返回。不支持维度拆分，所有维度均仅返回对应Meta App的数据)

 ["dau","arpu","request","click","ctr_api"]
start Int N 偏移数，代表从第几条数据开始，默认为0 0
limit Int N 每次拉取数据的最大条数，默认是1000，可选[1,1000] 1000

 

4. 返回参数

维度及筛选条件：

字段 类型 是否必传 备注
count Int Y 总条数
date String Y 日期，格式：YYYYmmdd。group_by有选才有返回
app Object N 应用信息，group_by有选app维度时才返回
app.id String N 开发者后台的应用ID
app.name String N 应用名称
app.platform String N 应用的系统平台
app.pkg_name String N 应用的包名
placement Object N 广告位信息，group_by有选placement维度时才返回
placement.id String N 开发者后台的广告位ID
placement.name String N 广告位名称
adformat String N 广告样式，group_by有选adformat维度时才有返回，枚举值：Rewarded Video、Interstitial、Banner、Native、Splash
area String N 国家码。group_by有选area维度时才有返回
network_firm_id String N 广告平台ID，group_by有选network_firm_id维度才有返回
network_firm String N 广告平台名称，group_by有选network_firm_id维度才有返回
network String N 广告平台账号ID，group_by有选network维度才有返回
network_name String N 广告平台账号名称，group_by有选network维度才有返回
adsource Object N 广告源信息，group_by有选adsource维度时才返回
adsource.network String N 广告源所属的广告平台名称
adsource.token String N 广告源的三方ID信息，请求广告的appid，slotid等
adsource.slot_id String N 第三方广告平台ID
adsource.adsource_id String N 广告源id
adsource.adsource_name String N 广告源名称
scenario Object N 广告场景信息，group_by有选scenario维度时才返回
scenario.id String N TopOn内部广告场景id（"1"代表默认场景），仅用于TopOn内部标记广告场景，开发者请使用custom_uuid字段进行广告场景匹配
scenario.name String N 广告场景名称
scenario.custom_uuid String N 自定义广告场景ID（"1"代表默认场景），对应后台广告场景管理页面显示的广告场景ID，即SDK上传的广告场景ID
traffic_group Object N 流量分组信息，group_by有选traffic_group维度时才返回
traffic_group.id String N 流量分组id
traffic_group.name String N 流量分组名称
traffic_group.segment_id Int N 流量分组数字id，注意：默认流量分组时segment_id=0,不会返回
channel String N 渠道名称，group_by有选channel维度才有返回
sdk_version String N SDK版本，group_by有选sdk_version维度才有返回
app_version String N 应用版本，group_by有选app_version维度才有返回
time_zone String N 时区，枚举值：UTC+8、UTC+0、UTC-8
currency String N 开发者账号币种，该字段与revenue字段组成的收益需与开发者后台报表的收益一致

指标：

字段 类型 是否必传 指标类型 指标分类 备注
dau String N TopOn数据 用户行为 DAU，根据group_by条件才有返回
deu String N DEU
engaged_rate String N 渗透率
imp_dau String N 展示 / DAU
imp_deu String N 展示 / DEU
dau_launch int N 启动DAU，注意：该值为0时，响应不返回该指标
new_users String N 新用户
new_user_rate String N 新用户占比
cy_estimate_revenue String N 收益数据 预估收益，按开发者账号币种返回的预估收益
cy_estimate_revenue_ecpm String N 预估收益，按开发者账号币种返回的预估eCPM，计算方式和estimate_revenue_ecpm一样
estimate_revenue String N （后续会下线，不推荐使用）预估收益，币种：美元
estimate_revenue_ecpm String N 预估eCPM，根据预估收益和TopOn统计的展示计算出预估eCPM，计算公式：（预估收益/TopOn统计的展示）*1000。注： 1、预估 eCPM当天提供； 2、常规广告源基于手动填写的eCPM价格计算，竞价广告源基于实时竞价价格计算
ecpm String N eCPM，TopOn通过报表API向广告平台拉取到的实际收益和TopOn统计的展示计算出eCPM，计算公式：（收益/TopOn统计的展示）*1000。注：eCPM延迟1天提供
ecpc String N eCPC，TopOn通过报表API向广告平台拉取到的实际收益和TopOn统计的点击量计算出eCPC，计算公式：（收益/TopOn统计的点击量）*1000。注：eCPC 数据延迟1天提供
ecpr String N eCPR，TopOn根据计算的预估收益和统计的请求数计算出eCPR，计算公式：（预估收益/TopOn统计的请求数）*1000。
bid_request int N 竞价数据 询价，仅竞价广告源会返回此数据
bid_filled_request_rate String N 询价响应率，仅竞价广告源会返回此数据
bid_filled_request_ecpm String N 询价响应eCPM，仅竞价广告源会返回此数据，按开发者账号币种返回
load String N 广告请求展示 流量请求，注意：当选了某些group_by维度(例如：network_firm_id)，响应为“0”
loads_filled int N 流量填充数，注意：当选了某些group_by维度(例如：network_firm_id)，或者该值为0时，响应不返回该指标
load_fillrate String N 流量填充率，注意：当选了某些group_by维度(例如：network_firm_id)，响应不返回该指标
request String N 广告源请求
request_filled int N 广告源填充数，注意：该值为0时，响应不返回该指标
fillrate String N 广告源填充率
impression String N 展示
impression_rate String N 展示率
click String N 点击
ctr String N 点击率
ready_request String N 广告Ready数据 查询isReady
ready_rate String N isReady成功率
scenario_entry int N 到达广告场景，注意：该值为0时，响应不返回该指标
scenario_entry_ready_rate String N 广告Ready率
day2_retention String N 其他数据 次日留存（后台无此指标）
revenue_gap String N 收益GAP
ecpm_gap String N eCPM GAP
impression_gap String N 展示Gap
click_gap String N 点击Gap
request_api String N API数据 广告请求展示 请求API
fillrate_api String N 填充率API
impression_api String N 展示API
click_api String N 点击API
ctr_api String N 点击率API
cy_arpu String N 收益数据 ARPDAU，有dau才有该项返回，单位：按开发者账号币种
arpu String N （后续会下线，不推荐使用）ARPDAU，有dau才有该项返回，单位：美元
estimated_revenue_arpu String N 预估ARPDAU，有dau才有该项返回，单位：按开发者账号币种
revenue String N 收益API，币种为开发者账号币种
ecpm_api String N eCPM API，TopOn通过报表API向广告平台拉取到的实际收益和展示API计算出eCPM API，计算公式：（收益/展示API）*1000。注：eCPM API延迟1天提供
unit_ecpc String N eCPC API，计算公式：媒体收益/媒体侧点击次数*1000。注：eCPC API延迟1天提供
unit_ecpr String N eCPR API，计算公式：收益API/请求API *1000。部分广告平台不支持请求API数据，请区分广告平台查看此指标。注：eCPR API延迟1天提供

 

5. 样例

请求样例：

curl --location --request POST 'https://openapi.toponad.com/v2/fullreport' \
--header 'X-Up-Key: 877f8ae9c6e9ca82c0==5b5fff594c373axxx' \
--header 'X-Up-Signature: CE12B506DBCD868C2C6F09E08C139CBC' \
--header 'X-Up-Timestamp: 1626161553000' \
--header 'Content-Type: application/json' \
--data-raw '{
    "startdate": 20210201,
    "enddate": 20210223,
    "group_by": ["adsource"],
    "metric": ["all"],
    "limit": 1000,
    "start": 0,
    "app_id_list": ["a6012251c3df52"],
    "placement_id_list": ["b601226022d218"]
}'


返回样例：


{
    "count": 64,
    "records": [{
        "adsource": {
            "network": "TouTiao",
            "token": "{\"app_id\":\"5008225\",\"slot_id\":\"908225577\",\"is_video\":\"1\"}"
        },
        "revenue": "12995.80"
    }]
     "currency": "USD"
}


上一个
数据报表API
下一个
留存价值报表
最近修改: 2025-07-30Powered by