# Reporting API 接入说明

# 一、申请创建外部应用

接入Reporting API 申请步骤:

1、联系对应AM,提供需开通Reporting API 的“账户ID”和“账户名称”

2、AM进行申请

3、申请通过后,AM提供appId、appKey等应用信息

# 二、token获取方式

# 1. token创建


接口:https://global.e.mi.com/foreign/token/createToken
请求方式: POST
Content-Type:application/json

入参:

字段
类型
是否必传
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


接口:https://global.e.mi.com/foreign/token/refreshToken
请求方式: POST
Content-Type:application/json

入参:

字段
类型
是否必传
refreshToken
String

出参:

字段
类型
备注
accessToken
String
token
expireDate
String
token过期时间
refreshToken
String
更新token,置换token
refreshExpireDate
String
置换token过期时间

# 三、数据查询接口

# 1. 接口1


   接口:https://global.e.mi.com/foreign/data/queryData
   请求方式: POST
   Content-Type:application/json
   调用间隔: 大于2秒

入参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


   接口:https://global.e.mi.com/foreign/data/queryDataName
   请求方式: POST
   Content-Type:application/json
   调用间隔: 大于0.3秒

入参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个。