English
Log In
You can then view all documents
GroMore/GroMore SDK与API接入/小时级/天级数据报表API
小时级/天级数据报表API
Last updated 2022-04-25 20:39:26

接入GroMore的媒体可使用以下功能。

一、功能介绍

GroMore数据API支持您通过API的方式拉取在GroMore的天级、小时级数据报表中的各个预估数据与API数据指标(支持的指标详情见末尾附录),支持使用不同的筛选条件进行查询拉取。可以帮助媒体开发者及时监测广告收益在不同广告平台的变化,来及时调整对于不同广告平台的选择、配置和策略。

注意事项:该API为GroMore数据拉取专用API,非穿山甲API。

需注意:仅返回用于穿山甲聚合内的流量的数据。

二、接入文档

1、权限认证

1. Security key获取

获取路径:穿山甲后台-接入-API接入文档(点击链接跳转

2. 验签说明

  • 客户端逻辑:去掉请求参数中sign字段和值为空的字段,比如:sign_str=(k1=v1&k2=v2...kn=vn) + (xxx) 其中,k1、k2...kn的排序按照字典序排序,xxx是 security_key使用 MD5哈希算法对第一步生成的sign_str进行签名,得到数字签名。sign = MD5(sign_str)
  • 服务端逻辑在接到请求后会重复如上的第一、二步工作以得到当前请求期望的数字签名。用期望的数字签名和客户端发送过来的数字签名做比对,如果完全一致则认为该请求通过安全验证,否则直接拒绝该请求。

3. 验签相关的请求参数

所有请求都必须要带上这些字段,用来保证用户能安全地请求接口

字段

类型

描述

校验规则

是否必填

user_id

integer

媒体账号id

对应账号必须存在且状态为"运行中"

role_id

integer

子账号id

对应子账号必须存在且从属于主账号;并且需要主账户在平台“角色管理”中选择角色后点击“数据”,配置“查看全部数据”权限,否则子账号无权限查看ecpm、revenue等财务相关数据。

current_time

string

当前时间(秒级),小时级报表的时间戳

请求提交时间的三分钟内

小时级报表接口必填

timestamp

integer

时间戳(秒),天级报表的时间戳

请求提交时间的三分钟内

天级报表接口必填

sign_type

string

哈希算法(取值MD5)

只能使用已支持的算法(MD5)

version

string

API版本号

固定版本号:"2.0"

sign

string

通过指定哈算算法生成的签名,用于校验token

存在且不为空;使用指定算法验签

4. 生成签名sign的代码示例

python 2.7

Java 8

PHP 7

2、小时级数据报表

接口说明:小时粒度的数据报告API将帮助媒体开发者及时监测广告收益在不同广告平台的变化,来及时调整对于不同广告平台的选择、配置和策略。仅返回用于穿山甲聚合内的流量的数据。

时效性: 小时级数据的时效性期望:最多延迟2小时。

  • 请求path:/union_media/open/api/v1/mediation/get_hour_report_data
  • 请求方法:GET
  • 请求示例

1. 请求示例

HTTP示例

https://www.csjplatform.com/union_media/open/api/v1/mediation/get_hour_report_data?current_time=2022-01-06 21:53:15&dimensions=site_id&end_time=2022-01-06 18:00:00&metric=ret_cnt,req_cnt&role_id=459&sign_type=MD5&start_time=2022-01-06 16:00:00&user_id=459&version=2.0&sign=a760c4b6****

代码示例

Python 2.7
Java 8

响应示例

2. 请求参数

字段

类型

描述

示例值

默认值

校验规则

是否必填

dimensions

String

用于聚合的维度,当前支持的所有维度见附录。

"site_id,adunittype"

按小时维度聚合

多个维度需要用英文逗号分隔

metric

string

需要查询的数据指标,目前支持的所有指标见附录。

"ret_cnt,req_cnt"

req_cnt, ret_cnt, fill_rate, imp_cnt, clk_cnt, clk_rate

多个指标需要用英文逗号分隔

site_ids

string

把传入的应用ID作为筛选条件

"123456,654321"

-

多个应用ID需要用英文逗号分隔

adunittypes

string

把传入的广告位类型作为筛选条件,当前支持的广告位类型见附录

"1,2,3,4,5,6,8"

-

多个广告位类型需要用英文逗号分隔

adunit_ids

string

把传入的广告位ID作为筛选条件

"123,456,789"

-

多个广告位ID需要用英文逗号分隔

network

string

把传入的广告网络作为筛选条件,当前支持的广告网络见附录

"1,2,3,4,5"

-

多个广告网络需要用英文逗号分隔

code_ids

string

把传入的代码位ID作为筛选条件

"123456,654321"

-

多个代码位ID需要用英文逗号分隔

os

string

把传入的系统类型作为筛选条件

"ios"

-

只能是 "ios" 或 "android"

start_time

string

开始时间,格式为 "0000-00-00 00:00:00"

"2020-10-21 12:00:00"

-

目前仅仅支持整小时

end_time

string

结束时间,格式为 "0000-00-00 00:00:00"

"2020-10-21 13:00:00"

-

目前仅仅支持整小时

offset

integer

偏移数,代表从第几条数据开始

0

0


limit

integer

每次查询的最大数量,可用区间为 [1, 5000],最大支持5000

100

100

数量范围只能在区间 [1, 5000] 内

time_zone

integer

查询时使用的时区

8

8

只能是 0 或 8

3. 响应数据

字段

类型

描述

code

integer

业务状态码

message

string

状态码描述

data

MediationIncomeReportData

详细的数据

MediationIncomeReportData

字段

类型

描述

reportlist

MediationIncomeReportItem[]

报告数据

summery

MediationIncomeReportItem

数据总指标

currency

string

货币类型,"cny" 或 "usd"

total

integer

符合条件的数据总条数

MediationIncomeReportItem 对象中会返回用户期望查询的指标和传入的维度,类似SQL查询返回的结果。

3、天级数据报表

  • 请求path:/union_media/open/api/mediation/get_daily_income_report_data
  • 请求方法:GET

1. 请求示例

HTTP示例

https://www.csjplatform.com/union_media/open/api/mediation/get_daily_income_report_data?dimensions=site_id&end_date=2022-01-06&metrics=ret_cnt,req_cnt&role_id=459&sign_type=MD5&start_date=2022-01-06&timestamp=1641784533&user_id=459&version=2.0&sign=c70aed8ddee*****

代码示例

Python 2.7
Java 8

响应示例

2. 请求参数

字段

类型

说明

示例

默认值

是否必填

dimensions

string

用于聚合的维度,当前支持的所有维度见附录。

"site_id,ad_unit_type"

"date,site_id,ad_unit_type,ad_unit_id,network"

metrics

string

需要查询的数据指标,目前支持的所有指标见附录。

"waterfall_req_cnt,waterfall_send_cnt"

"req_cnt,ret_cnt,imp_cnt,clk_cnt,ecpm,revenue,api_req_cnt,api_ret_cnt,api_clk_cnt,api_ecpm,api_revenue"

site_ids

string

把传入的应用ID作为筛选条件

5145943

-

ad_unit_types

int

把传入的广告位类型作为筛选条件,当前支持的广告位类型见附录

1,2,3,4,5

-

code_ids

String

把传入的代码位ID作为筛选条件

123456,654321

-

ad_unit_ids

string

把传入的广告位ID作为筛选条件

8013

-

os

string

把传入的系统类型作为筛选条件

android

-

network

string

把传入的广告网络作为筛选条件,当前支持的广告网络见附录

1,2,3

-

start_date

string

开始日期,不能早于当前日期的三个月。

开始日期到结束日期的跨度小于1天将展示当天数据,并且跨度不能超过1个月

2021-11-10

-

end_date

string

结束日期,不能小于开始日期

2021-11-10

-

limit

int

每次查询数据的最大数量,可选[1,5000],最大支持5000

10

100

offset

int

偏移数,代表从第几条数据开始

0

0

3. 响应数据

字段

数据类型

说明

code

string

状态码

message

string

错误码描述

data

MediationIncomeReportData

详细的数据

MediationIncomeReportData

字段

类型

描述

report_list

MediationIncomeReportItem[]

报告数据

total

int

符合条件的数据总条数

has_next

int

在当前 offset 和 limit 限制下,是否还存在未拉取的数据。 1有,0无

currency

string

货币类型

MediationIncomeReportItem 对象中会返回用户期望查询的指标和传入的维度,类似SQL查询返回的结果。

4、返回状态码说明

状态码

描述

解决方案

100

成功

101

身份验证失败

检查签名字符串是否按要求生成的

102

无效的userid

检查传入的user_id是否是gromore平台上显示的帐号ID

107

无访问权限

当前role_id没有权限访问该接口,请联系主账户管理员获取权限

108

服务异常

请稍后发起重试,如多次重试无效则联系平台客服

114

日期跨度不符合规则(不超过三个月)

检查开始日期和结束日期是否超过了三个月

115

参数错误,具体描述以实际返回为准。包括:接口版本信息不正确,sign_type仅仅支持MD5,时间戳格式错误,当前时间不满足,时间格式输入错误,开始时间不可以大于结束时间等

根据实际返回的描述去检查自己传入的参数是否正确。

116

服务内部错误

请稍后发起重试,如多次重试无效则联系平台客服

117

子账户没有siteid

检查传入的role_id是否有要查询应用的权限

118

没有ecpm和revenue查看权限

检查传入的role_id是否有财务数据查询权限

119

子账户没有指定的该siteid

子账号必须指定要查询的应用ID为筛选条件

5、附录

1. 聚合维度(dimensions)

字段

描述

支持的接口

date

天级粒度的日期

天级

site_id

gromore聚合管理中的应用ID

小时级、天级

adunittype

聚合管理中广告位的类型

小时级

ad_unit_type

聚合管理中广告位的类型

天级

adunit_id

聚合管理中广告位的ID

小时级

ad_unit_id

聚合管理中广告位的ID

天级

network

代码位所属的广告网络

小时级、天级

code_id

代码位ID

小时级、天级

os

系统类型

小时级

2. 数据指标(metric)

字段

特殊说明

描述

waterfall_req_cnt

这些是瀑布流粒度的指标,不支持瀑布流以下的维度,即不支持代码位和广告网络维度

流量请求量

waterfall_send_cnt

流量返回量

waterfall_sr

流量填充率(waterfall_send_cnt / waterfall_req_cnt)

req_cnt

这些是代码位粒度的指标

广告请求量,Gromore向广告网络发送请求的次数。一次流量请求可能触发多次广告请求。

ret_cnt

广告返回量,Gromore向广告网络发送请求后,成功返回广告的次数

fill_rate

广告填充率 = ret_cnt / req_cnt。Gromore向广告平台发送请求后,返回成功的占比

imp_cnt

瀑布流和代码位粒度都支持的指标

展示量,Gromore统计的广告曝光次数,由于统计口径差异、网络丢包等因素,Gromore的展示数据与广告网络展示数据可能存在差异

ssr

展示率 = imp_cnt / ret_cnt。Gromore收到来自广告平台的广告返回后,展示成功的占比。

clk_cnt

点击量,Gromore统计的广告点击数,由于部分广告网络不提供点击回调,Gromore统计的点击数据与广告网络点击数据可能存在差异。

clk_rate

点击率 = clk_cnt / imp_cnt。Gromore展示广告平台的广告后,广告被点击的占比。

ecpm

预估 eCPM(查询时间范围内的平均千次展示收益)= revenue/ (imp_cnt/1000)

revenue

预估收益(单位为元,币种为帐号的币种),标准代码位预估收益=SUM(瀑布流中设置的期望CPM*Gromore统计的展示/1000),竞价代码位预估收益=SUM(每次展示对应的实时价格)

api_ecpm

这三个指标,支持小时级和天级报表。

对于小时级报表,只支持穿山甲代码位。如果需要查询这些指标的小时级数据,只支持代码位维度

通过Reporting API获取的收益和展示数计算出来的每千次广告展示收益,公式为 eCPM API = (收益API /展示API)*1000。

api_revenue

通过Reporting API获取的收益,经实时汇率转换为账号的货币单位。

api_imp_cnt

通过Reporting API获取的展示数,由于网络环境和口径差异等情况,与Gromore统计的可能有一定差异。

api_req_cnt

这些指标,只支持天级报表。如果想要查询这些指标,需要在Gromore平台配置广告网络后才支持返回数据。

通过Reporting API获取的广告请求数

api_ret_cnt

通过Reporting API获取的广告返回数

api_clk_cnt

通过Reporting API获取的广告点击数

api_ssr

展示率API = api_imp_cnt / api_ret_cnt

api_fill_rate

填充率API = api_ret_cnt / api_req_cnt

api_show_gap_rate

Gromore统计展示量与广告平台统计展示量的差异,公式为 展示gap=(imp_cnt - api_imp_cnt) / api_imp_cnt

api_click_gap_rate

Gromore统计点击量与广告平台统计点击量的差异,公式为 点击gap=(点击 - 点击API) / 点击API

3. 枚举

广告位类型(adunittypes)

广告网络(network)

6、常见FAQ

Q:数据接口访问成功且code码返回100,但响应里没有数据

A:聚合数据API接口仅可查询具有聚合属性代码位在GroMore中使用的广告数据,即【GroMore】-【收益报表】下的数据。

穿山甲SDK的数据无法查询,即【数据】-【广告数据报表】下的数据。穿山甲SDK Reporting API可通过平台在线客服入口申请。

Q:接口提示"身份验证失败"

A:需要检查sign的生成是否正确,该值有3分钟过期机制。可直接执行文档中的样例代码生成接口访问链接验证数据可以正常拉取

Q:能否提供分用户、设备号等维度的数据报告?

A:抱歉,暂时无法提供

Q:能否提供PHPdemo示例?

A:已提供生成签名的demo,请求的demo暂时无法提供。


Contents
Contact us