Report API
English概述
Phoenix Ads 平台 Report 接口,通过 http 接口获取广告账户相关报表。
请求鉴权
所有请求都需要带上鉴权参数,位于 http 请求 query 部分
| 参数 | 描述 |
|---|---|
| agent_id | 接入身份标识,与广告账户绑定,请联系我们获取 |
| secret_key | 密钥,请联系我们获取 |
另外:
- 接口访问频率限制为 1次/秒
- 仅限ip白名单内的地址能访问接口,最多 3 个ip,请联系我们授权访问ip
通用返回结构
| 字段 | 说明 |
|---|---|
| code | 返回码,0表示成功,详见下方 |
| data | 返回结果 |
| message | - |
获取账户列表
GET
https://api.phoenix-ads.com/api/v2/ad/accounts
获取对应的账户信息,可用于后续请求报告传入账户id
请求参数:
-
返回结果:
| 字段 | 类型 | 说明 |
|---|---|---|
| id | number | 账户 id |
| name | string | 账户名 |
| zone | number | 账户时区 |
获取账户报告
GET
https://api.phoenix-ads.com/api/v2/ad/account/:account_id/report
以广告账户维度获取报告数据,接口地址account_id参数为上面获取到的账户id
请求参数:
| 字段 | 名称 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| time_range | 查询范围 | string | - | 必填,json字符串 {"since": "YYYY-MM-DD", "until": "YYYY-MM-DD"},since和until即开始和结束时间 |
| breakdowns | 细分字段 | string | [] | 数组字符串,可选campaign_id、adset_id和ad_id,即细分Campaign、Set和Ad |
| fields | 返回字段 | string | [] | 默认返回全部字段,可选值见下方返回结果字段 |
| limit | 数据条数限制 | number | - | 必填,最大不超过2000 |
| offset | 数据偏移量 | number | - | 必填,结合limit与offset可实现分页 |
返回结果:
| 字段 | 类型 | 说明 |
|---|---|---|
| ds | string | 时间,YYYYMMDD格式 |
| ad_id | string | 广告 id |
| ad_name | string | 广告名 |
| adset_id | string | 广告Set id |
| adset_name | string | 广告Set名 |
| campaign_id | string | 广告Campaign id |
| campaign_name | string | 广告Campaign名 |
| cash_cost | string | 实际花费 |
| gift_cost | string | 赠金花费 |
| click | number | 点击量 |
| event | string | urlEncode形式的内容,其中key为深度事件名称,value为深度事件数量 |
| optimization_event | string | 优化事件名称,需 set 展开后才返回 |
| impression | number | 曝光量 |
| install | number | 下载量 |
返回码
| 返回码 | 说明 |
|---|---|
| 0 | 成功 |
| 2600 | 数据未准备好 |
| 4000 | 参数错误 |
| 4100 | 鉴权失败 |
| 4300 | 无权限 |
| 4400 | 接口不存在 |
| 4800 | 请求 ip 未授权 |
| 4900 | 请求频率超限制 |
| 5000 | 内部错误 |
完整请求示例
以 Javascript 语言为例:
const apiHost = 'https://api.phoenix-ads.com';
// 全局鉴权参数,位于请求query部分
const authParams = {
agent_id: '1234567890',
secret_key: '1234567890'
};
// SOME_FETCH_LIB 代表网络请求库
const accountRes = await SOME_FETCH_LIB.get(`${apiHost}/api/v2/ad/accounts`, authParams);
// 账户返回示例
const accountResDemo = {
code: 0,
data: [
{
id: 1,
name: 'Test Account',
zone: 8
}
]
}
// 构造请求参数,注意time_range、breakdowns、fields参数需要转为json字符串
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
};
// url带入账户id查询报告
const reportRes = await SOME_FETCH_LIB.get(`${apiHost}/api/v2/ad/account/${accountRes.data[0].id}/report`, reportParams);
// 报告返回示例
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
}
]
}