开发者报表获取
一、功能概述
Carty 开发者平台提供 开发者报表获取 接口，供开发者通过服务端接口拉取报表数据。
接口支持按日期维度统计并分页返回，便于开发者进行数据分析、收益核对与运营监控。
二、接口信息
- 接口名称：开发者报表获取
- 接口地址：
/api/report/out-search - 请求方式：
POST - 字符编码：
UTF-8 - Content-Type：
application/json
2.1 域名
三、认证方式（Authorization）
该接口采用 API Key 鉴权方式。
- 请求 Header：
Authorization - 示例值：
rk_0jmtmwkz8grugecy1bp7syh4e6wgg4oa - 获取方式：在系统后台 apikeys 模块中获取
⚠️ 请妥善保管 API Key，避免泄露或提交至公共代码仓库。
四、请求参数
4.1 Header 参数
| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| Authorization | 是 | String | API Key |
| Content-Type | 是 | String | 固定为 application/json |
4.2 Body 参数（JSON）
| 参数名 | 必填 | 类型 | 说明 |
|---|---|---|---|
| start_date | 是 | String | 开始日期，格式：YYYY-MM-DD |
| end_date | 是 | String | 结束日期，格式：YYYY-MM-DD（需 ≥ start_date） |
| group | 是 | Array | 维度, 示例, ["date", "os", "app_id", "ad_type", "placement_id", "country"] |
| page | 是 | Int | 页码，默认 1 |
| page_size | 是 | Int | 每页条数，默认 10 |
请求示例
json
{
"start_date": "2026-02-01",
"end_date": "2026-02-07",
"group": [
"date",
"os",
"app_id",
"ad_type",
"placement_id",
"country"
],
"page": 1,
"page_size": 10
}五、返回参数
5.1 返回结构说明
| 字段 | 类型 | 说明 |
|---|---|---|
| code | Int | 状态码：0 表示成功，非 0 表示失败 |
| message | String | 返回信息 |
| data | Object | 数据对象 |
5.2 data.list 字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| date | String | 日期（YYYY-MM-DD） |
| bid_type | Int | 竞价类型 |
| request | Int | 请求量 |
| fill | Int | 填充量 |
| impression | Int | 展示量 |
| click | Int | 点击量 |
| revenue | Number | 开发者收入 |
| ctr | Number | 点击率（%） |
| ecpm | Number | eCPM |
| ecpc | Number | eCPC |
| fill_rate | Number | 填充率（%） |
| impression_rate | Number | 展示率（%） |
| summary | Object | 汇总数据 |
5.3 data.page 字段说明
| 字段 | 类型 | 说明 |
|---|---|---|
| current | Int | 当前页 |
| page_size | Int | 每页条数 |
| total | Int | 总条数 |
六、返回示例
json
{
"code": 0,
"message": "success",
"data": {
"list": [
{
"date": "2026-02-06",
"request": 541,
"fill": 539,
"impression": 365,
"click": 44,
"revenue": 4.91,
"ctr": 0.12,
"ecpm": 13.45,
"ecpc": 0.11,
"fill_rate": 1,
"impression_rate": 0.68
},
{
"date": "2026-02-05",
"request": 40,
"fill": 35,
"impression": 25,
"click": 6,
"revenue": 1.28,
"ctr": 0.24,
"ecpm": 51.04,
"ecpc": 0.21,
"fill_rate": 0.88,
"impression_rate": 0.71
},
{
"date": "2026-02-04",
"request": 229331,
"fill": 104599,
"impression": 41741,
"click": 20808,
"revenue": 41937.05,
"ctr": 0.5,
"ecpm": 1004.7,
"ecpc": 2.02,
"fill_rate": 0.46,
"impression_rate": 0.4
},
{
"date": "2026-02-03",
"request": 274371,
"fill": 125010,
"impression": 49950,
"click": 25112,
"revenue": 49847.48,
"ctr": 0.5,
"ecpm": 997.95,
"ecpc": 1.99,
"fill_rate": 0.46,
"impression_rate": 0.4
},
{
"date": "2026-02-02",
"request": 45828,
"fill": 21103,
"impression": 8661,
"click": 4190,
"revenue": 8392.84,
"ctr": 0.48,
"ecpm": 969.04,
"ecpc": 2,
"fill_rate": 0.46,
"impression_rate": 0.41
}
],
"summary": {
"request": 550111,
"fill": 251286,
"impression": 100742,
"click": 50160,
"revenue": 100183.56,
"fill_rate": 0.46,
"impression_rate": 0.4,
"ctr": 0.5,
"ecpm": 994.46,
"ecpc": 2
},
"page": {
"current": 1,
"page_size": 10,
"total": 5
}
}
}七、请求示例（curl）
bash
curl --location --request POST 'https://developer.gocarty.net/api/report/out-search' \
--header 'Authorization: rk_mxuyl6eq6lcz3mlkhz89gqcjinmj5qvx' \
--header 'Content-Type: application/json' \
--data-raw '{
"start_date": "2026-02-01",
"end_date": "2026-02-07",
"group": [
"date"
],
"page": 1,
"page_size": 10
}'八、错误码说明（示例）
| code | 含义 |
|---|---|
| 0 | success |
| 非 0 | 参数错误 / 鉴权失败 / 系统异常 |
常见错误原因
- Authorization 缺失或 API Key 无效
- 日期格式错误或时间范围不合法
- page / page_size 参数非法