# Reporting API 接入说明
# 一、申请创建外部应用
接入Reporting API 申请步骤:
1、联系对应AM,提供需开通Reporting API 的“账户ID”和“账户名称”
2、AM进行申请
3、申请通过后,AM提供appId、appKey等应用信息
# 二、token获取方式
# 1. token创建
入参:
字段 | 类型 | 是否必传 |
appId | String | 是 |
appKey | String | 是 |
出参:
字段 | 类型 | 备注 |
accessToken | String | token |
expireDate | String | token过期时间 |
refreshToken | String | 更新token,只能用来置换token |
refreshExpireDate | String | 置换token过期时间 |
{
"code": 0,
"message": "调用成功!",
"result": {
"accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhcHBJZCI6Indtc2oiLCJhcHBLZXkiOiJhYmMxMjMiLCJleHAiOjE2NjU3NDMyODR9.PqIZJbQdrgWe-pseyhJo3sxsGZroIBiasaSmKkh9QCM",
"expireDate": "2022-10-14T10:28:04.570Z",
"refreshExpireDate": "2022-10-21T09:28:04.570Z",
"refreshToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJncmFudF90eXBlIjoicmVmcmVzaCIsImFwcElkIjoid21zaiIsImFwcEtleSI6ImFiYzEyMyIsImV4cCI6MTY2NjM0NDQ4NH0.uD3TAbgU6X8ouX-Ra7A4LVKMgb_qi7btNagaG2_2ccY"
}
}
# 2. 更新token
入参:
字段 | 类型 | 是否必传 |
refreshToken | String | 是 |
出参:
字段 | 类型 | 备注 |
accessToken | String | token |
expireDate | String | token过期时间 |
refreshToken | String | 更新token,置换token |
refreshExpireDate | String | 置换token过期时间 |
# 三、数据查询接口
# 1. 接口1
入参1: (参数位置: Cookie)
字段 | 类型 | 是否必填 | 备注 |
access_token | String | 是 | token |
timestamp | Long | 是 | 时间戳 |
uid | String | 是 | 请求唯一id(每次请求均唯一) |
ip | String | 否 | 请求IP |
入参2: (参数位置: body)
字段 | 类型 | 是否必填 | 备注 | 枚举值 |
page | Long | 否 | 页码从1开始 ,默认1 | |
pageSize | Long | 否 | 每页条数, 最大1000条 | |
adType | Integer | 是 | 广告类型 | 1:效果, 2:品牌 |
accountIds | List<Long> | 否 | 查询账户,为空时默认查询所有账户 | |
adCampaignIds | List<Long> | 否 | 广告计划Id | |
adGroupIds | List<Long> | 否 | 广告组Id | |
adCreativeIds | List<Long> | 否 | 广告创意Id | |
adTagIds | List<String> | 否 | 广告位Id | |
regions | List<String> | 否 | 国家/地区列表 | |
medias | List<String> | 否 | 媒体Id | 媒体ID对照信息 |
dimensions | List<Integer> | 是 | 分组维度/查询方式。 默认填1:等同[1,5] 广告查询维度: 1、2、3、4、9、10 (目前支持1、2、3、4、9 可多选)。 查询方式:5 (仅支持5 )。 填值:[查询维度,查询方式] 举例:[1,4,5] [2,5,9] | 1: "广告计划", 2: "广告组", 3: "广告创意", 4: "国家/地区", 5: "日期", 9: "广告位", 10: "媒体" |
begin | String/long | 是 | 查询起始时间,格式2022-10-10T00:00:00.000Z 或 时间戳 | 起始-结束时间段内必须涵盖查询天数的0点。 例如:2022-10-10T00:00:00.000Z - 2022-10-10T23:59:59.999Z 可查出10号的数据。 |
end | Sting/long | 是 | 查询截止时间,格式2022-10-16T23:59:59.999Z 或 时间戳 | |
lang | String | 是 | "zh_CN" 中文 “en_US” 英文 |
参数2样例:
{
"accountIds":[857],
"pageSize": 100,
"page": 1,
"adCampaignIds": [],
"adType": 1,
"adGroupIds": [],
"adCreativeIds": [],
"adTagIds": [],
"regions": [
"AF",
"AL"
],
"medias": [
656,
402
],
"dimensions": [
1
],
"begin": "2022-10-11T00:00:00.000Z",
"end": "2022-10-17T23:59:59.999Z",
"lang": "zh_CN"
}
出参:
字段 | 类型 | 备注 |
accountId | Long | 账户Id |
adCampaignId | Long | 广告计划Id |
adGroupId | Long | 广告组Id |
adCreativeId | Long | 广告创意Id |
geoKey | String | 国家 |
tagId | String | 广告位 |
expose | Long | 曝光 |
click | Long | 点击 |
activate | Long | 激活 |
costDisplay | String | 花费 |
ctr | String | CTR |
cvr | String | CVR |
ecpm | String | ECPM |
cpc | String | 点击成本 |
cpa | String | 激活成本 |
其他扩展字段可暂不关注。返回样例:
{
"code": 0,
"message": "调用成功!",
"result": {
"current": 1,
"pages": 1,
"records": [
{
"accountId": 65,
"activate": 2000,
"adCampaignId": 120,
"adCreativeId": 100000075,
"adGroupId": 136,
"adType": null,
"billingType": 4,
"city": "",
"click": 2000,
"close": 0,
"cost": 200000000,
"costDisplay": "2000.00",
"cpa": "1.0000",
"cpc": "1.0000",
"ctr": "100.00",
"cvr": "100.00",
"download": 1000,
"ecpm": "1000.0000",
"end": 0,
"expose": 2000,
"fullScreen": 0,
"geoKey": "",
"half": 0,
"installed": 1000,
"mediaType": "18",
"parentAccountId": 0,
"province": "",
"quarter": 0,
"recordDate": "2022-09-20T00:00:00.000Z",
"region": "IN",
"start": 0,
"tagId": "1.307.1.1",
"threeQuarter": 0
},
{
"accountId": 65,
"activate": 0,
"adCampaignId": 3552,
"adCreativeId": 100005762,
"adGroupId": 12079,
"adType": null,
"billingType": 11,
"city": "",
"click": 6,
"close": 0,
"cost": 200,
"costDisplay": "0.00",
"cpa": "0.0000",
"cpc": "0.0003",
"ctr": "9.52",
"cvr": "0.00",
"download": 0,
"ecpm": "0.0317",
"end": 0,
"expose": 63,
"fullScreen": 0,
"geoKey": "",
"half": 0,
"installed": 0,
"mediaType": "312",
"parentAccountId": 0,
"province": "",
"quarter": 0,
"recordDate": "2022-09-19T00:00:00.000Z",
"region": "IN",
"start": 0,
"tagId": "1.312.1.1",
"threeQuarter": 0
},
{
"accountId": 65,
"activate": 0,
"adCampaignId": 3550,
"adCreativeId": 100005737,
"adGroupId": 12048,
"adType": null,
"billingType": 11,
"city": "",
"click": 0,
"close": 0,
"cost": 150,
"costDisplay": "0.00",
"cpa": "0.0000",
"cpc": "0.0000",
"ctr": "0.00",
"cvr": "0.00",
"download": 0,
"ecpm": "0.0455",
"end": 0,
"expose": 33,
"fullScreen": 0,
"geoKey": "",
"half": 0,
"installed": 0,
"mediaType": "343",
"parentAccountId": 0,
"province": "",
"quarter": 0,
"recordDate": "2022-09-19T00:00:00.000Z",
"region": "IN",
"start": 0,
"tagId": "1.343.4.2",
"threeQuarter": 0
}
],
"size": 10,
"total": 3
}
}
# 2. 接口2
入参1: (参数位置: Cookie)
字段
| 类型
| 是否必填
| 备注
|
access_token
| String
| 是
| token
|
timestamp
| Long
| 是
| 时间戳
|
uid
| String
| 是
| 请求唯一id(每次请求均唯一)
|
ip
| String
| 否
| 请求IP
|
入参2: (参数位置: body)
字段
| 类型
| 是否必填
| 备注
|
accountIds
| List<Long>
| 是
| 具体查询账户Id
|
adCampaignIds
| List<Long>
| 否
| 广告计划Id
|
adGroupIds
| List<Long>
| 否
| 广告组Id
|
adCreativeIds
| List<Long>
| 否
| 广告创意Id
|
参数样例:
{
"accountIds": [
65,307
],
"adCampaignIds":[148],
"adGroupIds":[234,243],
"adCreativeIds":[100205197,100205198,100205249]
}
出参:
字段
| 类型
| 备注
|
accountId
| Long
| 账户Id
|
accountName
| String
| 账户名称
|
adCampaignId
| Long
| 广告计划Id
|
campaignName
| String
| 广告计划名称
|
adGroupId
| Long
| 广告组Id
|
groupName
| String
| 广告组名称
|
adCreativeId
| Long
| 广告创意Id
|
creativeName
| String
| 广告创意名称
|
其他扩展字段可暂不关注。返回样例:
{
"code": 0,
"message": "调用成功!",
"result": {
"adCount": [
{
"accountId": 65,
"accountName": "亚丽",
"adCampaigns": [
{
"adCampaignId": 148,
"campaignName": "品牌\b-非下载"
}
],
"adGroups": [
{
"adGroupId": 243,
"groupName": "icon-排除商店"
},
{
"adGroupId": 234,
"groupName": "icon-通投"
}
],
"adCreatives": [
{
"adCreativeId": 100205197,
"creativeName": "you x-1"
},
{
"adCreativeId": 100205198,
"creativeName": "you x-1_copy"
}
]
},
{
"accountId": 307,
"accountName": "张磊",
"adCampaigns": [],
"adGroups": [],
"adCreatives": [
{
"adCreativeId": 100205249,
"creativeName": "1.317.3.999效果广告"
}
]
}
]
}
}
# 3.code码对照表
code | 备注 |
0 | 调用成功 |
10001 | 无效token |
10002 | 无效appId或appKey |
10003 | 无任何账户查询权限 |
10004 | accountId未授权 |
20001 | 请求参数异常 |
20002 | 接口调用频率过高 |
100500 | 服务端异常 |
# 四、Q&A
Q:Miads Reporting API 的功能?
A:API是一种应用程序接口,通过API可提供传输数据和服务功能。Miads提供Reporting API的能力,可为代理商在自有平台本地完成获取广告数据的功能。通过Reporting API功能可以获取广告平台的报表查询功能,包括但不限ad account ID、ad campaign ID、ad creative ID层级下的消耗、曝光、点击、转化等数据。
Q:如何申请开通Reporting API ?
A:系对应AM获取申请流程。
Q:Reporting API 支持什么语言?
A:中文和英文。
Q:单次拉取数据的时间跨度是多长?
A: begin - end 跨度不能大于7天。
Q: Reporting API的时区?
A:零时区。目前只支持t-1天级零时区的数据拉取。例如:需要拉取2023年11月27日,北京时间8:00的数据,则开始时间为2023年11月27日 00:00:00。
Q:Reporting API支持的数据拉取递减天数?
A:T-1天。
Q:是否支持查询小时级的数据?
A:不支持,目前只支持以天为级别的数据拉取。
Q:时间戳可以是任意时间吗?每次调用都会有变化吗?
A:时间戳的时间是调用接口的当前时间,且每次调用都需要有变化。
Q:uid的格式?uid每次请求需要改变吗?
A:String格式,每次请求要变。uid即可。
Q:更新token接口的作用?
A:为了降低appKey的泄露风险。第一次创建接口获取token后,定时用更新token调用更新接口来获取新的token。
Q:想查看当日数据,但是请求返回的是第二天的数据,例如:想查询11月1日的数据,但是返回的是11月2日的数据。
A:需要保证查询时间段包含想要查询天数的0点即可。
Q:查询的起始时间应该如何设置?
A:起始-结束时间段内必须涵盖查询天数的0点。例如:2022-10-10T00:00:00.000Z - 2022-10-10T23:59:59.999Z
可查出10号的数据。
Q:是否支持查询账户名称、campaign名称等信息。
A:目前只支持查询账户ID、campaign ID、group ID、creative ID、tag ID。查询账户是accountIds为空,则默认查询所有账户。
Q:单次查询名称的数量限制?
A:单次请求查询相关名称,单个层级最大支持8000个。例如广告计划名称、广告组名称、广告创意名称分别最大支持查询8000个。