接入GroMore的媒体可使用以下功能。
GroMore数据API支持您通过API的方式拉取在GroMore的天级、小时级数据报表中的各个预估数据与API数据指标(支持的指标详情见末尾附录),支持使用不同的筛选条件进行查询拉取。可以帮助媒体开发者及时监测广告收益在不同广告平台的变化,来及时调整对于不同广告平台的选择、配置和策略。
注意事项:该API为GroMore数据拉取专用API,非穿山甲API。
需注意:仅返回用于穿山甲聚合内的流量的数据。
获取路径:穿山甲后台-接入-API接入文档(点击链接跳转)
所有请求都必须要带上这些字段,用来保证用户能安全地请求接口
字段 | 类型 | 描述 | 校验规则 | 是否必填 |
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 | 存在且不为空;使用指定算法验签 | 是 |
接口说明:小时粒度的数据报告API将帮助媒体开发者及时监测广告收益在不同广告平台的变化,来及时调整对于不同广告平台的选择、配置和策略。仅返回用于穿山甲聚合内的流量的数据。
时效性: 小时级数据的时效性期望:最多延迟2小时。
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****
字段 | 类型 | 描述 | 示例值 | 默认值 | 校验规则 | 是否必填 |
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 | 否 |
字段 | 类型 | 描述 |
code | integer | 业务状态码 |
message | string | 状态码描述 |
data | MediationIncomeReportData | 详细的数据 |
MediationIncomeReportData
字段 | 类型 | 描述 |
reportlist | MediationIncomeReportItem[] | 报告数据 |
summery | MediationIncomeReportItem | 数据总指标 |
currency | string | 货币类型,"cny" 或 "usd" |
total | integer | 符合条件的数据总条数 |
MediationIncomeReportItem 对象中会返回用户期望查询的指标和传入的维度,类似SQL查询返回的结果。
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×tamp=1641784533&user_id=459&version=2.0&sign=c70aed8ddee*****
字段 | 类型 | 说明 | 示例 | 默认值 | 是否必填 |
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 | 否 |
字段 | 数据类型 | 说明 |
code | string | 状态码 |
message | string | 错误码描述 |
data | MediationIncomeReportData | 详细的数据 |
MediationIncomeReportData
字段 | 类型 | 描述 |
report_list | MediationIncomeReportItem[] | 报告数据 |
total | int | 符合条件的数据总条数 |
has_next | int | 在当前 offset 和 limit 限制下,是否还存在未拉取的数据。 1有,0无 |
currency | string | 货币类型 |
MediationIncomeReportItem 对象中会返回用户期望查询的指标和传入的维度,类似SQL查询返回的结果。
状态码 | 描述 | 解决方案 |
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为筛选条件 |
字段 | 描述 | 支持的接口 |
date | 天级粒度的日期 | 天级 |
site_id | gromore聚合管理中的应用ID | 小时级、天级 |
adunittype | 聚合管理中广告位的类型 | 小时级 |
ad_unit_type | 聚合管理中广告位的类型 | 天级 |
adunit_id | 聚合管理中广告位的ID | 小时级 |
ad_unit_id | 聚合管理中广告位的ID | 天级 |
network | 代码位所属的广告网络 | 小时级、天级 |
code_id | 代码位ID | 小时级、天级 |
os | 系统类型 | 小时级 |
字段 | 特殊说明 | 描述 |
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 |
Q:数据接口访问成功且code码返回100,但响应里没有数据
A:聚合数据API接口仅可查询具有聚合属性代码位在GroMore中使用的广告数据,即【GroMore】-【收益报表】下的数据。
穿山甲SDK的数据无法查询,即【数据】-【广告数据报表】下的数据。穿山甲SDK Reporting API可通过平台在线客服入口申请。
Q:接口提示"身份验证失败"
A:需要检查sign的生成是否正确,该值有3分钟过期机制。可直接执行文档中的样例代码生成接口访问链接验证数据可以正常拉取
Q:能否提供分用户、设备号等维度的数据报告?
A:抱歉,暂时无法提供
Q:能否提供PHPdemo示例?
A:已提供生成签名的demo,请求的demo暂时无法提供。
Online Customer Service24/7 Online Customer Service BotManual customer service, weekdays 10~ 12 o'clock/14~ 19 o'clock