# Reporting API Access Guide

# Ⅰ. Apply to create external apps.


Application steps for accessing Reporting API:
1. Contact the corresponding AM (Account Manager) to provide the "Account ID" and "Account name" required to activate the Reporting API.
2. AM applies the Reporting API
3. After the application is approved, AM needs to provide appId, appKey, and other app information.

# Ⅱ. How to obtain token.

# 1. Create token


Interface : https://global.e.mi.com/foreign/token/createToken
Request method: POST
Content-Type:application/json

Input parameters:

Field
Type
Necessary to transfer or not
appId
String
Yes
appKey
String
Yes

Output Parameters:

Field
Type
Remark
accessToken
String
Token
expireDate
String
Token expiration time
refreshToken
String
Update token, only for token replacement
refreshExpireDate
String
Token replacement expiration time
{
"code": 0,
"message": "Transferred successfully",
"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. Update token


Interface: https://global.e.mi.com/foreign/token/refreshToken
Request method: POST
Content-Type:application/json

Input parameters:

Field
Type
Necessary to transfer or not
refreshToken
String
Yes

Output parameters:

Field
Type
Remark
accessToken
String
Token
expireDate
String
Token expiration time
refreshToken
String
Update token, replace token
refreshExpireDate
String
Token replacement expiration time

# Ⅲ. Data Query

# 1. Interface 1


Interface: https://global.e.mi.com/foreign/data/queryData
Request method: POST
Content-Type:application/json
Transfer interval: More than 2 seconds

Input parameters 1: (Parameter position: Cookies

Field
Type
Required or not
Remark
access_token
String
Yes
Token
timestamp
Long
Yes
Timestamp
uid
String
Yes
Request unique ID (unique for each request)
ip
String
No
Request IP

Input parameters 2: (Parameter position: body

Field
Type
Required or not
Remark
Enum value
page
Long
No
Page starts from 1 by default
pageSize
Long
No
Max lines per page is 1000
adType
Integer
Yes
Ad type
1: Effect
2: Brand
accountIds
List<Long>
No
Inquire account, check all accounts when it's blank
adCampaignIds
List<Long>
No
Ad campaign ID
adGroupIds
List<Long>
No
Ad group ID
adCreativeIds
List<Long>
No
Ad creative ID
adTagIds
List<String>
No
Ad placement ID
regions
List<String>
No
Country/region list
medias
List<String>
No
Publisher ID
dimensions
List<Integer>
Yes
Ad group dimensions/query method.
Enter 1 by default: Equivalent [1,5]
Ad query dimensions: 1, 2, 3, 4, 9, 10 (currently support 1, 2, 3, 4, 9 multi-selection).
Query method: 5 (Only supports 5).
Fill: [Query dimension, query method]
Example: [1,4,5] [2,5,9]
1: "Campaign",
2: "Ad group",
3: "Ad",
4: "Country/region",
5: "Date",
9: "Ad placement",
10: "Publisher"
begin
String/long
Yes
Query start time, the format is 2022-10-10T00:00:00.000Z, or the timestamp
The start-end period must cover 0:00hrs of query days.
Example: 2022-10-10T00:00:00.000Z - 2022-10-10T23:59:59.999Z
Data from October 10th can be found.
end
Sting/long
Yes
Query end time, the format is 2022-10-16T23:59:59.999Z, or the timestamp
lang
String
Yes
"zh_CN" Chinese
“en_US” English

Parameter 2 example:

{
"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"
}

Output parameters:

Field
Type
Remark
accountId
Long
Account ID
adCampaignId
Long
Ad campaign ID
adGroupId
Long
Ad group ID
adCreativeId
Long
Ad creative ID
geoKey
String
Country/region
tagId
String
Ad placement
expose
Long
Impressions
click
Long
Clicks
activate
Long
Activations
costDisplay
String
Expenditure
ctr
String
CTR
cvr
String
CVR
ecpm
String
ECPM
cpc
String
CPC
cpa
String
CPA

Other extension fields can be ignored for now.Return example:

{
"code": 0,
"message": "Transferred successfully",
"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. Interface 2


Interface: https://global.e.mi.com/foreign/data/queryDataName
Request method: POST
Content-Type:application/json
Transfer interval: More than 0.3 seconds

Input parameters 1: (Parameter position: Cookie

Field
Type
Required or not
Note
access_token
String
Yes
token
timestamp
Long
Yes
Timestamp
uid
String
Yes
Request unique ID (unique for each request)
ip
String
NO
Request IP

Input parameters 2: (Parameter position: body)

Field
Type
Required or not
Note
accountIds
List<Long>
YES
Specific account ID query
adCampaignIds
List<Long>
NO
Ad campaign ID
adGroupIds
List<Long>
NO
Ad group ID
adCreativeIds
List<Long>
NO
Ad creative ID

Parameter example:

{
"accountIds": [
65,307
],
"adCampaignIds":[148],
"adGroupIds":[234,243],
"adCreativeIds":[100205197,100205198,100205249]
}

Output parameters:

Field
Type
Note
accountId
Long
Account ID
accountName
String
Account name
adCampaignId
Long
Ad campaign ID
campaignName
String
Campaign name
adGroupId
Long
Ad group ID
groupName
String
Ad group name
adCreativeId
Long
Ad creative ID
creativeName
String
Ad name

Other extension fields can be ignored for now.Return example:

{
"code": 0,
"message": "Invocation Successful!",
"result": {
"adCount": [
{
"accountId": 65,
"accountName": "Yali",
"adCampaigns": [
{
"adCampaignId": 148,
"campaignName": "Brand\b-no-downloads"
}
],
"adGroups": [
{
"adGroupId": 243,
"groupName": "icon-Exclude Shop"
},
{
"adGroupId": 234,
"groupName": "icon-General Targeting"
}
],
"adCreatives": [
{
"adCreativeId": 100205197,
"creativeName": "you x-1"
},
{
"adCreativeId": 100205198,
"creativeName": "you x-1_copy"
}
]
},
{
"accountId": 307,
"accountName": "Zhang Lei",
"adCampaigns": [],
"adGroups": [],
"adCreatives": [
{
"adCreativeId": 100205249,
"creativeName": "1.317.3.999 Performance Advertising"
}
]
}
]
}
}

# 3. Code reference table


code
Remark
0
Transferred successfully
10001
Invalid token
10002
Invalid appId or appKey
10003
No permissions to check any account
10004
Unauthorized accountId
20001
Request parameter error
20002
Interface calling frequency is too high
100500
Server error

# Ⅳ. Reporting API Q&A

Q: What is the Mi Ads Reporting API feature?

A: API is an app programming interface that provides data transfer and other services.Mi Ads provides Reporting API functionality, allowing agents to obtain ad data locally on their platforms.The Reporting API feature makes it possible to acquire an ad platform's query capabilities, including but not limited to cost, impression, click, and conversion data under the ad account ID, ad campaign ID, and ad creative ID.


Q: How do I apply to enable the Reporting API?

A: Contact the corresponding AM (Account Manager) to get the application method.


Q: What languages does the Reporting API support?

A: English and simplified Chinese.


Q: What is the maximum period for a single data pull?

A: The begin-end period can't exceed 7 days.


Q: What are the time zones for the Reporting API?

A: UTC+00:00.The only time zone currently supported for pulling data is UTC+00:00 of the previous day.For example, if you need to pull data for November 27, 2023 at 8:00 a.m. Beijing time, the start time will be November 27, 2023 at 00:00:00.


Q: How many decremental days of data pulling are supported by the Reporting API?

A: 1 day before.


Q: Is querying hourly data supported?

A: No, only the pulling of daily data is supported for now.


Q: Can the timestamp be an arbitrary time?Does it have to be different for each call?

A: The timestamp corresponds to when the interface was called. It is necessarily different for each call.


Q: What about the format of the UID?Must the UID be different for each request?

A: The format of the string must change with each request.Use UID.


Q: What is the update token interface for?

A: To reduce the risk of appKey leakage.After the interface is created for the first time, the update interface is regularly called with the update token to obtain a new token.


Q: I want to view the data for a given day, but the request returns the data for the following day. For example, when I query the data for November 1st, the data for November 2nd is returned instead.

A: Make sure the period of the days you want to include in your query is precise to the minute and specified relative to UTC+00:00.


Q: How should I set the query's beginning time?

A: The begin-end period must be precise to the minute and specified relative to UTC+00:00.For example, 2022-10-10T00:00:00.000Z - 2022-10-10T23:59:59.999Z

will return all data for October 10, 2022.


Q: Does the Reporting API support querying account names, campaign names and other such information?

A: The only types of query that are currently supported are account ID, ad campaign ID, ad group ID, ad creative ID, and tag ID.If accountIds is blank when performing an account query, all accounts will be queried by default.


Q: Is there a limit on the number of names that can be queried at one time?

A: A single request to query related names can support up to 8,000 names at each level.For example, campaign names, ad group names, and ad names each support a maximum of 8,000 queries.