数据开放 API

通过 API Key，从您自己的服务端按推广链接或应用（APP）查询访问数与安装数，支持区间合计与按天明细，便于接入自有的 BI、报表或投放系统。


接口地址	`https://openapi.roibest.com/open/v1/stats`
请求方式	`GET`
鉴权方式	请求头 `X-Api-Key`
响应格式	JSON（UTF-8）
时区	UTC+0
可查询范围	最近 90 天内，单次最长 30 天

快速开始

使用主账号登录 ROIBest 后台，点击右上角头像 →「开放 API」→「生成 API Key」，并完成邮箱验证。
API Key 明文仅在生成成功时展示一次，请立即复制或下载，妥善保存在服务端。
在服务端发起第一次请求（将示例中的 ID 和 Key 替换为您自己的）：

curl -s 'https://openapi.roibest.com/open/v1/stats?promote_url_id=6347317793&start_date=2026-10-01&end_date=2026-10-07&group_by=day' \
  -H 'X-Api-Key: rbk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

鉴权

在每个请求的请求头中携带 API Key：

X-Api-Key: rbk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API Key 只能通过请求头传递，放在 URL 参数或请求体中均视为未携带。
仅主账号可以生成和管理 API Key，每个主账号同一时间仅有 1 把有效 Key。
在后台「重新生成」后，旧 Key 立即失效。请先准备好替换服务端配置，再执行重新生成。

安全提示

API Key 仅限服务端使用，请勿写入网页、移动端 App 或公开的代码仓库。如怀疑泄露，请立即在后台重新生成。

调用频率

每分钟最多 10 次请求。超出后返回 HTTP 429，请稍候再试。

建议

需要逐日数据时，请使用 group_by=day 一次查询完整区间（最长 30 天），无需逐天调用。
需要查询多个推广链接或应用时，请分批、错峰调用。

查询统计数据

GET https://openapi.roibest.com/open/v1/stats

请求参数

所有参数均通过 URL 参数（Query String）传递。

参数名	类型	是否必须	参考值	描述
promote_url_id	string	二选一	6347317793	推广链接 ID
app_id	string	二选一	1024	应用 ID
start_date	string	否	2026-10-01	开始日期，格式 `YYYY-MM-DD`，包含当天
end_date	string	否	2026-10-07	结束日期，格式 `YYYY-MM-DD`，包含当天
group_by	string	否	day	不传：返回区间合计；传 `day`：返回逐日数据

查询规则：

promote_url_id 与 app_id 必须且只能传其中一个。
日期均按 UTC+0 计算，例如 2026-10-01 指 UTC 时间 2026-10-01 00:00:00 至 23:59:59。
开始、结束日期都不传时查询今天；只传其中一个时，仅查询该日。
结束日期不能晚于今天（UTC+0）。
单次查询区间最长 30 天（含开始、结束日期）。
仅支持查询最近 90 天内的数据：开始日期不能早于今天往前推 90 天。例如今天（UTC+0）为 11 月 6 日，最早可查询 8 月 8 日。
只能查询本账号下的推广链接和应用；已删除或已隐藏的同样可以查询，响应中通过 deleted、hidden 字段标识。

响应参数

参数名	类型	描述
code	int	业务码，`0` 表示成功
msg	string	结果说明（英文），成功时为 `success`
request_id	string	请求 ID，反馈问题时请提供
data.promote_url_id	string \| null	按推广链接查询时为该 ID，否则为 `null`
data.app_id	string \| null	按应用查询时为该 ID，否则为 `null`
data.deleted	bool	是否已删除
data.hidden	bool	是否已在后台隐藏
data.metrics	string[]	本次返回的指标，当前为 `["visit", "install"]`
data.timezone	string	统计时区，固定为 `UTC`
data.start_date	string	本次查询的开始日期
data.end_date	string	本次查询的结束日期
data.total	object	不传 `group_by` 时返回，为区间内 `visit`、`install` 的合计
data.rows	array	`group_by=day` 时返回，每天一条，按日期升序；无数据的日期同样返回，计数为 0
data.rows[].date	string	日期 `YYYY-MM-DD`
data.rows[].visit	int	访问数
data.rows[].install	int	安装数

示例：查询区间合计

GET /open/v1/stats?promote_url_id=6347317793&start_date=2026-10-01&end_date=2026-10-02

{
  "code": 0,
  "msg": "success",
  "request_id": "9f1c2e7a4b3d4c6e8a0b1c2d3e4f5a6b",
  "data": {
    "app_id": null,
    "promote_url_id": "6347317793",
    "deleted": false,
    "hidden": false,
    "timezone": "UTC",
    "metrics": ["visit", "install"],
    "start_date": "2026-10-01",
    "end_date": "2026-10-02",
    "total": { "visit": 180, "install": 21 }
  }
}

示例：按天查询

GET /open/v1/stats?app_id=1024&start_date=2026-10-01&end_date=2026-10-03&group_by=day

{
  "code": 0,
  "msg": "success",
  "request_id": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
  "data": {
    "app_id": "1024",
    "promote_url_id": null,
    "deleted": false,
    "hidden": false,
    "timezone": "UTC",
    "metrics": ["visit", "install"],
    "start_date": "2026-10-01",
    "end_date": "2026-10-03",
    "rows": [
      { "date": "2026-10-01", "visit": 100, "install": 12 },
      { "date": "2026-10-02", "visit": 80, "install": 9 },
      { "date": "2026-10-03", "visit": 0, "install": 0 }
    ]
  }
}

指标说明

指标	说明
访问数（visit）	对应后台「推广链接 → 数据详情」中「广告访问」与「Chrome 访问」之和
安装数（install）	对应后台「推广链接 → 数据详情」中的「安装」

两项指标均已过滤系统识别出的无效流量。
统计日期按 UTC+0 划分，当天数据为截至查询时刻的累计值。

错误码

请求失败时，HTTP 状态码与业务码同时返回（HTTP 429 除外），响应示例：

{ "code": 40003, "msg": "date range must not exceed 30 days", "request_id": "9f1c2e7a4b3d4c6e8a0b1c2d3e4f5a6b" }

HTTP 状态码	业务码	说明	处理建议
400	40001	`promote_url_id` / `app_id` 缺失、同时传入或格式错误	二者只传其一，且为纯数字
400	40002	日期格式错误、开始日期晚于结束日期，或结束日期晚于今天	检查日期参数
400	40003	查询区间超过 30 天	拆分为多次查询
400	40004	开始日期超出最近 90 天的可查询范围	将开始日期调整到最近 90 天内
400	40005	`group_by` 取值错误	不传，或传 `day`
401	40101	API Key 缺失、无效或已被重新生成	检查请求头 `X-Api-Key`，确认使用的是最新的 Key
401	40102	账号未激活或受限	未激活请先完成账号激活，其他情况请联系客户经理
404	40401	推广链接或应用不存在，或不属于当前账号	检查 ID 是否正确、是否属于当前账号
429	—	超出调用频率限制	等待 1 分钟后重试，并降低调用频率
500	50001	服务内部错误	稍后重试；持续出现请携带 `request_id` 联系客户经理
503	50301	服务繁忙，暂时无法查询	稍后重试，请勿在短时间内密集重试

重试建议

429：等待 1 分钟后再重试。
500、503：按递增间隔（如 2 秒、4 秒、8 秒）重试，最多 3 次。
其他 4xx 错误：重试不会成功，请修正请求后再发起。

#数据开放 API

#快速开始

#鉴权

#调用频率

#查询统计数据

#请求参数

#响应参数

#示例：查询区间合计

#示例：按天查询

#指标说明

#错误码