Report API
中文Overview
The Phoenix Ads platform's Report API,get account's ad data using http request.
Authorization
Each request should has authorization params in http query part.
| Params | Description |
|---|---|
| agent_id | The access identifier, related to ad account, please contact us to get it. |
| secret_key | The secret key, please contact us to get it. |
And:
- The API access frequency is limited to once per second.
- Only in the IP whitelist can access the API, up to 3 IPs. Please contact us to add IPs.
Generic response structure
| Field | Description |
|---|---|
| code | Response code, value 0 means success,more. |
| data | Response data |
| message | - |
Get account list
GET
https://api.phoenix-ads.com/api/v2/ad/accounts
Get all of the related accounts, be used for get the report data.
Request params:
-
Response data:
| Field | Type | Description |
|---|---|---|
| id | number | The account id |
| name | string | The account name |
| zone | number | The account timezone |
Get report data
GET
https://api.phoenix-ads.com/api/v2/ad/account/:account_id/report
Get report data with account dimension,the account_id param in the API path should be the account id.
Request params:
| Field | Name | Type | Default | Description |
|---|---|---|---|---|
| time_range | Date range | string | - | Required,json string {"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"},`since` and `until` means start time and end time. |
| breakdowns | Break down fields | string | [] | An Array string, Optional value: campaign_id、adset_id and ad_id,means break down Campaign、Set and Ad. |
| fields | Response fields | string | [] | Default to get all fields, can be set to the fields below |
| limit | Data count limit | number | - | Required,max to 2000 |
| offset | Data rows offset | number | - | required,using limit and offset for paged data. |
Response data:
| Field | Type | Description |
|---|---|---|
| ds | string | Date,YYYYMMDD-formatted |
| ad_id | string | Ad id |
| ad_name | string | Ad name |
| adset_id | string | Set id |
| adset_name | string | Set name |
| campaign_id | string | Campaign id |
| campaign_name | string | Campaign name |
| cash_cost | string | Cash cost |
| gift_cost | string | Gift cost |
| click | number | Click count |
| event | string | Url-encoded content,each key means event name, value means event count. |
| optimization_event | string | The optimization event name, only present when `adset_id` in breakdowns. |
| impression | number | Impression count |
| install | number | Install count |
Response code
| Code | Description |
|---|---|
| 0 | Success |
| 2600 | Data not ready |
| 4000 | Parameters error |
| 4100 | Unauthorized |
| 4300 | No permission |
| 4400 | API not found |
| 4800 | Access ip not authorized |
| 4900 | Request frequency capped |
| 5000 | Internal error |
Demo
Using Javascript:
const apiHost = 'https://api.phoenix-ads.com';
// authorization params in the http query part
const authParams = {
agent_id: '1234567890',
secret_key: '1234567890'
};
// SOME_FETCH_LIB means the fetch library
const accountRes = await SOME_FETCH_LIB.get(`${apiHost}/api/v2/ad/accounts`, authParams);
// example response data for account list
const accountResDemo = {
code: 0,
data: [
{
id: 1,
name: 'Test Account',
zone: 8
}
]
}
// request params,notice that time_range、breakdowns、fields need convert to json string
const reportParams = {
...authParams,
time_range: JSON.stringify({since: '2023-01-01', until: '2023-02-01'}),
breakdowns: JSON.stringify(['campaign_id']),
fields: JSON.stringify([]),
limit: 100,
offset: 0
};
// the account id is in the url path
const reportRes = await SOME_FETCH_LIB.get(`${apiHost}/api/v2/ad/account/${accountRes.data[0].id}/report`, reportParams);
// example response data for report
const reportResDemo = {
code: 0,
data: [
{
"ad_id": "123456",
"ad_name": "Test Ad",
"adset_id": "123456789",
"adset_name": "Test Ad set",
"campaign_id": "1234567890123456",
"campaign_name": "Test Campaign",
"cash_cost": "0.00000000",
"click": 0,
"ds": "20230201",
"event": "Registration=12",
"gift_cost": "0.00000000",
"impression": 0,
"install": 0
}
]
}