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
    }
  ]
}