# 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过期时间

# 三、数据查询接口

接口：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>	否	国家/地区列表	国家/地区ID对照信息
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
    }
}

# 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为空，则默认查询所有账户。