# Reporting API Access Guide
# Ⅰ. Apply to create external apps.
# Ⅱ. How to obtain token.
# 1. Create token
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
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
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
}
}
# 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.