# 基础 API 接口

## 一、概览

提供两个数据查询接口：

| **action** | **时间口径** | **说明** |
| --- | --- | --- |
| monetize_daily_data | 活跃日期 | 经营总览——以**活跃日期**为维度，查询某天所有活跃用户带来的收入和规模数据 |
| monetize_trace_data | 注册日期 | 用户增长与变现——以**注册日期**为维度，追踪某批注册用户从注册到 90 天的买量、变现、ROI 表现 |

**公共信息**

| **项目** | **内容** |
| ---- | --- |
| 接口地址 | https://api.weixin.qq.com/publisher/stat |
| 请求方式 | GET |
| 数据格式 | JSON |
| 频率限制 | 每分钟每 appid 每 action 最多 5 次 |
| 金额单位 | 元（RMB） |
| 日期格式 | YYYYMMDD |
| 数值精度 | 不做固定位数四舍五入；分母为 0 的派生指标（ROI、CPA、ARPU 等）返回 0 |
| 问题排查 | 每次请求返回唯一 trace_id，用于定位日志 |

---

## 二、活跃日期口径（monetize_daily_data）

以**活跃日期**为维度，查询某天所有活跃用户带来的收入和规模数据。支持批量查询，传入多个时间段。始终返回全渠道、内渠、外渠三组数据。

### 调用地址

```
GET https://api.weixin.qq.com/publisher/stat?action=monetize_daily_data&access_token=ACCESS_TOKEN&appid=APPID&filters={FILTERS_JSON_STRING}
```

### 请求参数

| **参数** | **类型** | **必填** | **说明** |
| --- | --- | --- | --- |
| appid | string | 是 | 小游戏 appid |
| filters | array | 是 | 时间段列表，支持批量查询，至少传一个 |

#### FilterRange

时间段，用于批量查询。

| **字段** | **类型** | **必填** | **说明** |
| --- | --- | --- | --- |
| label | string | 否 | 自定义标签，原样回显到对应结果中（如 "本月" / "上月"），不传则为空 |
| begin_ds | string | 是 | 开始日期，YYYYMMDD |
| end_ds | string | 是 | 结束日期，YYYYMMDD |

### 返回结构

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| ret | number | 否 | 错误码，0表示成功，非0表示失败，具体含义见错误码说明|
| err_msg | string | 否 | 错误信息 |
| trace_id | string | 否 | 本次请求的唯一标识，用于问题排查。出现异常时提供该值便于定位日志 |
| results | array | 否 | 每项对应一组 filters 的结果且顺序一致 |

#### DailyDataResult

单个时间段的经营总览结果。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| filter | object(FilterRange) | 否 | 对应请求中的该 filter，原样回显，用于结果与请求对齐 |
| summary | object(DailyDataSummary) | 否 | 整个时间段的汇总数据 |
| daily_list | array | 否 | 逐日明细，每天一条 |

#### DailyDataSummary

整个时间段的汇总数据。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| all_channel | object(ChannelData) | 否 | 全渠道收入数据 |
| inner_channel | object(ChannelData) | 否 | 内渠（腾讯自有流量）收入数据 |
| outer_channel | object(ChannelData) | 否 | 外渠收入数据 |
| total_user_reg_cnt | number | 否 | 综合注册人数（时间段汇总） |
| advertise_user_reg_cnt | number | 否 | 买量注册人数（时间段汇总） |
| natural_user_reg_cnt | number | 否 | 自然量注册人数（时间段汇总） |
| daily_avg_active_users_cnt | number | 否 | 日均活跃用户数 DAU（时间段汇总） |

#### DailyDataItem

单日明细。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| ds | string | 否 | 活跃日期，YYYYMMDD |
| all_channel | object(ChannelData) | 否 | 当日全渠道收入数据 |
| inner_channel | object(ChannelData) | 否 | 当日内渠收入数据 |
| outer_channel | object(ChannelData) | 否 | 当日外渠收入数据 |
| total_user_reg_cnt | number | 否 | 当日综合注册人数 |
| advertise_user_reg_cnt | number | 否 | 当日买量注册人数 |
| natural_user_reg_cnt | number | 否 | 当日自然量注册人数 |
| active_users_cnt | number | 否 | 当日活跃用户数 |

#### ChannelData

渠道收入数据。summary 与 daily_list 中的 all_channel/inner_channel/outer_channel 均为此结构。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| ad_income | number | 否 | 综合收入 = 买量分成 + 广告金 + 自然量分成，元 |
| monetize_ad_income | number | 否 | 买量分成收入，元 |
| ad_fund | number | 否 | 买量广告金收入，元 |
| natural_monetize_ad_income | number | 否 | 自然量分成收入，元 |
| ad_cost | number | 否 | 买量消耗，元 |
| ad_roi | number | 否 | ROI = 综合收入 / 买量消耗 |

### 请求示例

```bash
curl -sS -G 'https://api.weixin.qq.com/publisher/stat' \
  --data-urlencode 'action=monetize_daily_data' \
  --data-urlencode 'access_token=ACCESS_TOKEN' \
  --data-urlencode 'appid=APPID' \
  --data-urlencode 'filters=[{"label":"示例","begin_ds":"20260601","end_ds":"20260601"}]'
```

### 返回示例

返回 JSON

```json
{
  "ret": 0,
  "err_msg": "",
  "trace_id": "a1b2c3d4e5f6",
  "results": [
    {
      "filter": {"label": "示例", "begin_ds": "20260601", "end_ds": "20260601"},
      "summary": {
        "all_channel": {
          "ad_income": 400.00,
          "monetize_ad_income": 360.00,
          "ad_fund": 30.00,
          "natural_monetize_ad_income": 10.00,
          "ad_cost": 260.00,
          "ad_roi": 1.538
        },
        "inner_channel": {
          "ad_income": 320.00,
          "monetize_ad_income": 290.00,
          "ad_fund": 25.00,
          "natural_monetize_ad_income": 5.00,
          "ad_cost": 200.00,
          "ad_roi": 1.600
        },
        "outer_channel": {
          "ad_income": 80.00,
          "monetize_ad_income": 70.00,
          "ad_fund": 5.00,
          "natural_monetize_ad_income": 5.00,
          "ad_cost": 60.00,
          "ad_roi": 1.333
        },
        "total_user_reg_cnt": 1800,
        "advertise_user_reg_cnt": 1500,
        "natural_user_reg_cnt": 300,
        "daily_avg_active_users_cnt": 14800
      },
      "daily_list": [
        {
          "ds": "20260601",
          "all_channel": {
            "ad_income": 400.00,
            "monetize_ad_income": 360.00,
            "ad_fund": 30.00,
            "natural_monetize_ad_income": 10.00,
            "ad_cost": 260.00,
            "ad_roi": 1.538
          },
          "inner_channel": {
            "ad_income": 320.00,
            "monetize_ad_income": 290.00,
            "ad_fund": 25.00,
            "natural_monetize_ad_income": 5.00,
            "ad_cost": 200.00,
            "ad_roi": 1.600
          },
          "outer_channel": {
            "ad_income": 80.00,
            "monetize_ad_income": 70.00,
            "ad_fund": 5.00,
            "natural_monetize_ad_income": 5.00,
            "ad_cost": 60.00,
            "ad_roi": 1.333
          },
          "total_user_reg_cnt": 1800,
          "advertise_user_reg_cnt": 1500,
          "natural_user_reg_cnt": 300,
          "active_users_cnt": 14800
        }
      ]
    }
  ]
}
```

---

## 三、注册日期口径（monetize_trace_data）

以**注册日期**为维度，追踪某批注册用户90天内的买量、变现、ROI 表现。

支持通过 filters 传入多个时间段，各时间段可独立配置渠道、版位、创意等筛选参数，互不干扰。

### 调用地址

```
GET https://api.weixin.qq.com/publisher/stat?action=monetize_trace_data&access_token=ACCESS_TOKEN&appid=APPID&filters={FILTERS_JSON_STRING}
```

### 请求参数

| **参数** | **类型** | **必填** | **说明** |
| --- | --- | --- | --- |
| appid | string | 是 | 小游戏 appid |
| filters | array | 是 | 时间段列表，每项指定一个注册日期区间及其筛选参数，至多 10 个；end_ds 与 begin_ds 间隔不超过 90 天 |

#### TraceFilter

单个时间段及其筛选参数。

| **字段** | **类型** | **必填** | **枚举** | **说明** |
| --- | --- | --- | --- | --- |
| label | string | 否 |   | 自定义标签，原样回显到对应结果中，不传则为空 |
| begin_ds | string | 是 |   | 开始注册日，YYYYMMDD |
| end_ds | string | 是 |   | 结束注册日，YYYYMMDD，与 begin_ds 差距不超过 90 天 |
| channel | string | 否 | 枚举值 | 注册渠道，单值。可填大类（ad/natural）、具体细分渠道枚举或 TOTAL（等价不传）。仅 channel=ad 或其下细分时，placement_group/creative_type/creative_size 才有意义 |
| placement_group | array | 否 | 枚举值 | 广告版位，**仅 channel=ad 时有意义**。传入具体枚举值（可多个）时，返回对应版位的逐项明细。 |
| creative_type | array | 否 | 枚举值 | 广告创意，**仅 channel=ad 时有意义**。取值规则同 placement_group：具体创意枚举（可多个）/EACH/TOTAL |
| creative_size | array | 否 | 枚举值 | 激励创意尺寸选择器，仅对 creative_type=MD_CREATIVE_TYPE_REWARDED_CANVAS 生效，其他创意类型忽略。
可传具体尺寸枚举（可多个）/EACH/TOTAL；EACH/TOTAL 不可与具体值混传。 |
| adpos | array | 否 | 枚举值 | 变现广告位。数组元素取值：
● 具体广告位枚举（可多个）=筛选这些广告位并返回逐项明细；
● EACH=展开全部广告位逐项明细；TOTAL=全部广告位（等价于不传）。
● EACH/TOTAL 与具体值不能同数组出现 |

### 返回结构

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| ret | number | 否 | 错误码，0表示成功，非0表示失败，具体含义见错误码说明 |
| err_msg | string | 否 | 错误信息 |
| trace_id | string | 否 | 本次请求的唯一标识，用于问题排查。出现异常时提供该值便于定位日志 |
| results | array | 否 | 每项对应一组 filters 的结果且顺序一致 |

#### TraceDataResult

单个时间段的注册追踪结果。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| filter | object(TraceFilter) | 否 | 对应请求中的该 filter，原样回显，用于结果与请求对齐 |
| dimension_groups | array | 否 | 按请求中的投放维度（版位/创意/尺寸）划分的逐项明细，每项一个维度组合。
 •三个维度参数全不传（或全为 TOTAL）时，返回一项纯聚合（维度字段均为 TOTAL）；
 •传 EACH 或具体值时返回对应逐项明细 |

#### DimensionGroup

单个维度组合的逐项明细，是 dimension_groups 数组中的一项。其中 placement_group/creative_type/creative_size/adpos 字段标明该项对应的维度取值

| **字段** | **类型** | **可空** | **枚举** | **说明** |
| --- | --- | --- | --- | --- |
| placement_group | string | 否 | 枚举值 | 广告版位值；该维度请求传 TOTAL 或不传时填 TOTAL |
| creative_type | string | 否 | 枚举值 | 广告创意类型；该维度请求传 TOTAL 或不传时填 TOTAL |
| creative_size | string | 否 | 枚举值 | 激励创意尺寸；仅 creative_type=MD_CREATIVE_TYPE_REWARDED_CANVAS
且按尺寸展开时有具体枚举值；该维度请求传 TOTAL 或不传时填 TOTAL |
| adpos | string | 否 | 枚举值 | 变现广告位值；该维度请求传 TOTAL 或不传时填 TOTAL |
| reg_list | array | 否 |   | 该维度组合下按注册日排列的数据 |

#### RegItem

单个注册日的聚合数据。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| reg_ds | string | 否 | 注册日，YYYYMMDD |
| ad_cost | number | 否 | 注册买量消耗，元 |
| reg_uv | number | 否 | 注册人数 |
| cpa | number | 否 | 注册成本 = ad_cost / reg_uv，元 |
| first_day | object(FirstDay) | 是 | 注册当日首日切片数据 |
| monetize_trace | array | 是 | 注册后 N 日变现追踪（day_delta 0~89） |
| roi_trace | array | 是 | 注册后 N 日 ROI 追踪（day_delta 0~89） |
| roi_fit | object(RoiFit) | 是 | 预估 ROI |

#### FirstDay

注册当日首日切片数据。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| monetize_income | number | 否 | 首日广告变现收入，元 |
| monetize_income_uv | number | 否 | 首日广告变现人数 |
| ecpm | number | 否 | eCPM，元 |
| ad_arpu | number | 否 | 广告 ARPU，元 |
| ad_permeability | number | 否 | 广告渗透率，0.65 表示 65% |
| ipu | number | 否 | 人均观看广告次数（IPU） |
| avg_duration | number | 否 | 人均在线时长，秒 |
| avg_start_times | number | 否 | 人均启动次数 |
| iap_income | number | 否 | 首日内购收入，元 |
| iap_income_uv | number | 否 | 首日内购付费人数 |
| iap_permeability | number | 否 | 内购付费渗透率 |
| share_uv | number | 否 | 分享成功人数 |
| share_clk_uv | number | 否 | 分享带来的活跃人数 |

#### MonetizeTraceItem

注册后第 N 日变现追踪的单日数据。monetize_income 为当天（非累计）值。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| day_delta | number | 否 | 注册后第 N 天，0=注册当天 |
| user_retention_cnt | number | 否 | 留存人数 |
| user_retention_ratio | number | 否 | 留存率 |
| avg_duration | number | 否 | 人均在线时长，秒 |
| avg_start_times | number | 否 | 人均启动次数 |
| monetize_income | number | 否 | 当天（非累计）广告变现收入，元 |
| monetize_income_uv | number | 是 | 广告变现人数 |
| ecpm | number | 否 | eCPM，元 |
| ad_arpu | number | 否 | 广告 ARPU，元 |
| ad_permeability | number | 否 | 广告渗透率 |
| ipu | number | 否 | 人均观看广告次数（IPU） |
| iap_income | number | 否 | 内购收入，元 |
| iap_income_uv | number | 是 | 内购付费人数 |
| iap_permeability | number | 是 | 内购付费渗透率 |
| share_uv | number | 是 | 分享成功人数，仅 day_delta=0 有值 |
| share_clk_uv | number | 是 | 分享带来的活跃人数，仅 day_delta=0 有值 |

#### RoiTraceItem

注册后第 N 日 ROI 追踪的单日数据。除 day_delta 外，金额字段均为**截至第 N 天的累计**值。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| day_delta | number | 否 | 注册后第 N 天 |
| monetize_income | number | 否 | 截至第 N 天累计广告变现收入，元 |
| iap_income | number | 否 | 截至第 N 天累计内购收入，元 |
| ad_fund_reg | number | 否 | 截至第 N 天累计注册广告金，元。仅买量渠道有值：目前支持腾讯广告、视频号-直播间广告（含其聚合口径），自然渠道下为 0 |
| all_income | number | 否 | 截至第 N 天累计综合收入，元 |
| roi_monetize | number | 否 | 累计 ROI（仅分成）= monetize_income / ad_cost |
| roi_all | number | 否 | 累计 ROI（含广告金）= all_income / ad_cost |
| roi_ratio_monetize | number | 否 | ROI 倍率（仅分成）= roi_monetize / 首日 roi_monetize |
| roi_ratio_all | number | 否 | ROI 倍率（含广告金）= roi_all / 首日 roi_all |

#### RoiFit

预估 ROI。

| **字段** | **类型** | **可空** | **说明** |
| --- | --- | --- | --- |
| predicted_all_income_roi_14 | number | 否 | 14 日预估 ROI（含广告金） |
| predicted_all_income_roi_30 | number | 否 | 30 日预估 ROI（含广告金） |
| predicted_all_income_roi_60 | number | 否 | 60 日预估 ROI（含广告金） |
| predicted_all_income_roi_90 | number | 否 | 90 日预估 ROI（含广告金） |
| predicted_monetize_income_roi_14 | number | 否 | 14 日预估 ROI（仅分成） |
| predicted_monetize_income_roi_30 | number | 否 | 30 日预估 ROI（仅分成） |
| predicted_monetize_income_roi_60 | number | 否 | 60 日预估 ROI（仅分成） |
| predicted_monetize_income_roi_90 | number | 否 | 90 日预估 ROI（仅分成） |

### 请求示例

```bash
curl -sS -G 'https://api.weixin.qq.com/publisher/stat' \
  --data-urlencode 'action=monetize_trace_data' \
  --data-urlencode 'access_token=ACCESS_TOKEN' \
  --data-urlencode 'appid=APPID' \
  --data-urlencode 'filters=[{"label":"示例","begin_ds":"20260701","end_ds":"20260701"}]'
```

### 返回示例

返回 JSON

```json
{
  "ret": 0,
  "err_msg": "",
  "trace_id": "f6e5d4c3b2a1",
  "results": [
    {
      "filter": {"label": "示例", "begin_ds": "20260701", "end_ds": "20260701","channel": ""},
      "dimension_groups": [
        {
          "placement_group": "TOTAL",
          "creative_type": "TOTAL",
          "creative_size": "TOTAL",
          "adpos": "TOTAL",
          "reg_list": [
            {
              "reg_ds": "20260701",
              "ad_cost": 500.00,
              "reg_uv": 3000,
              "cpa": 0.167,
              "first_day": {
                "monetize_income": 120.00,
                "monetize_income_uv": 1820,
                "ecpm": 8.48,
                "ad_arpu": 0.04,
                "ad_permeability": 0.61,
                "ipu": 2.08,
                "avg_duration": 318.0,
                "avg_start_times": 3.2,
                "iap_income": 30.00,
                "iap_income_uv": 50,
                "iap_permeability": 0.017,
                "share_uv": 200,
                "share_clk_uv": 150
              },
              "monetize_trace": [
                {
                  "day_delta": 0,
                  "user_retention_cnt": 3000,
                  "user_retention_ratio": 1.0,
                  "avg_duration": 318.0,
                  "avg_start_times": 3.2,
                  "monetize_income": 120.00,
                  "monetize_income_uv": 1820,
                  "ecpm": 8.48,
                  "ad_arpu": 0.04,
                  "ad_permeability": 0.61,
                  "ipu": 2.08,
                  "iap_income": 30.00,
                  "iap_income_uv": 50,
                  "iap_permeability": 0.017,
                  "share_uv": 200,
                  "share_clk_uv": 150
                }
              ],
              "roi_trace": [
                {
                  "day_delta": 0,
                  "monetize_income": 120.00,
                  "iap_income": 30.00,
                  "ad_fund_reg": 12.00,
                  "all_income": 162.00,
                  "roi_monetize": 0.24,
                  "roi_all": 0.324,
                  "roi_ratio_monetize": 1.0,
                  "roi_ratio_all": 1.0
                }
              ],
              "roi_fit": {
                "predicted_all_income_roi_14": 0.85,
                "predicted_all_income_roi_30": 1.20,
                "predicted_all_income_roi_60": 1.45,
                "predicted_all_income_roi_90": 1.60,
                "predicted_monetize_income_roi_14": 0.72,
                "predicted_monetize_income_roi_30": 1.05,
                "predicted_monetize_income_roi_60": 1.28,
                "predicted_monetize_income_roi_90": 1.42
              }
            }
          ]
        }
      ]
    }
  ]
}
```

### 筛选参数适用范围（接口二）

#### 筛选参数原理

##### 注册渠道维度(channel)

描述"用户从哪个渠道注册"，**单值**。可填大类（ad/natural）、具体细分渠道或 TOTAL（等价不传）。传大类=该大类下全部细分的聚合，传细分=只看该细分。

**roi_fit 约束**：

- 预估 ROI 支持广告大类 ad、腾讯广告 MD_REG_CHANNEL_TENCENT_AD、视频号-直播间广告 MD_REG_CHANNEL_FINDER_LIVE_AD，以及 TOTAL / 不传渠道；
- 自然大类及其细分渠道不返回 roi_fit；
- 当 adpos 为具体广告位或 EACH 时，不返回 roi_fit。

**广告金约束**：

- 广告金数据（roi_trace 的 ad_fund_reg）目前仅支持**腾讯广告**（MD_REG_CHANNEL_TENCENT_AD）与**视频号-直播间广告**（MD_REG_CHANNEL_FINDER_LIVE_AD）两个买量渠道；
- channel=ad（大类）/ TOTAL / 不传 时正常返回（为上述两个渠道的聚合）；
- channel=natural（大类）或其下细分渠道时，仅广告金 ad_fund_reg 返回 0；all_income/roi_all/roi_ratio_all 仍正常返回，但不含广告金成分，此时与仅分成口径一致。

##### 买量投放维度(placement_group、creative_type、creative_size)

描述"你如何买量获取用户"，仅在 channel=ad / MD_REG_CHANNEL_TENCENT_AD / MD_REG_CHANNEL_FINDER_LIVE_AD （广告渠道，含其下广告细分） 时有意义。这三个参数取 EACH 或具体值时返回 dimension_groups 逐项明细，取 TOTAL 或不传时返回一项纯聚合（维度字段均为 TOTAL）。

##### 变现维度(adpos)

描述"用户在游戏内通过哪个广告位变现"，与注册渠道无关，对全渠道均有效。传入 adpos 按广告位筛选（具体值或 EACH）后：

1. 注册人数、买量消耗、注册成本（ad_cost、reg_uv、cpa ）仍会返回，但它们是该注册日的**整体买量数据**，不按 adpos 筛选或拆分。因此不能将其理解为某个广告位带来的注册人数、该广告位的买量消耗或该广告位 CPA；
2. 广告金项（ad_fund_reg/all_income/roi_all/roi_ratio_all）：roi_trace 的广告金为**注册广告金**（广告金激励收入的一部分），按注册维度发放，与变现广告位无关，无法对应到具体广告位，因此按广告位筛选时缺省；
3. 预估 ROI（roi_fit）不返回，因为它不支持按变现广告位拆分。

当 adpos=TOTAL 或不传（不按广告位筛选）时，上述字段正常返回。

first_day 和 monetize_trace 中的留存、时长、内购等字段按 adpos 筛选后有数据，但反映的是"曾在该广告位产生变现行为的用户"的特征，请注意区分相关性与因果性。

#### 速查表

| **筛选参数** | **ad_cost / reg_uv / cpa** | **first_day** | **monetize_trace** | **roi_trace** | **roi_fit** |
| --- | --- | --- | --- | --- | --- |
| channel=ad或其下细分渠道/total/不传 | ✅ | ✅ | ✅ | ✅ | ✅ |
| channel=natural / 其下细分渠道 | ✅ | ✅ | ✅ | ✅（注5） | ❌（注4） |
| placement_group / creative_type / creative_size | ✅ | ✅ | ✅ | ✅ | ✅ |
| adpos | ✅（注1） | ✅（注2） | ✅（注2） | 部分（注3） | ❌ |

注1:（同变现维度1.）ad_cost、reg_uv、cpa 是该注册日的整体买量数据，不随 adpos 筛选或拆分；不能将它们理解为广告位维度的成本、注册人数或 CPA。

注2:first_day 和 monetize_trace 中的留存、时长、内购等字段按 adpos 筛选后有数据，但这些数据反映的是"曾在该广告位产生变现行为的用户"的特征，请注意区分相关性与因果性。

注3:adpos 按广告位筛选时，roi_trace 仅返回收入项（monetize_income/iap_income/roi_monetize/roi_ratio_monetize，按该广告位过滤）；其中 roi_monetize = 该广告位累计变现收入 / 完整买量成本，即该广告位对整体买量回收的收入贡献比例。

注4:channel=natural（大类）或natural下细分渠道时，roi_fit 缺省——预估 ROI 仅面向买量，不预测自然量。

注5:广告金（ad_fund_reg）目前仅支持腾讯广告与视频号-直播间广告两个买量渠道；channel=natural（大类）或其下细分渠道时 ad_fund_reg 返回 0。

#### 特别说明

- placement_group/creative_type/creative_size 取值：具体枚举值（可多个）=筛选这些值并返回逐项明细；EACH=展开该维度全部值的逐项明细（等价于把全部枚举值都列出）;TOTAL 或不传=纯聚合，该项三个维度字段均为 TOTAL，代表所有维度合计。多个维度同时传具体值或 EACH 时，dimension_groups 返回这些维度的交叉组合。
- creative_size 是一个特殊维度，只在 creative_type=MD_CREATIVE_TYPE_REWARDED_CANVAS 时有意义，不与 creative_type 交叉。
- ad_cost/reg_uv/cpa 在自然渠道下有值，但业务意义不大。

---

## 四、其他

### 枚举值

#### Channel

注册渠道，**单值**。可填大类（ad/natural）、具体细分渠道枚举、或 TOTAL。细分渠道从属于对应大类（如「腾讯广告」属 ad），传大类=该大类下全部细分的聚合，传细分=只看该细分。

##### 大类与特殊值

| **值** | **说明** |
| --- | --- |
| ad | 广告渠道（其下全部广告细分的聚合） |
| natural | 自然渠道（其下全部自然细分的聚合） |
| TOTAL | 全渠道（等价于不传） |

##### 细分渠道（广告大类 ad 下）

| **值** | **说明** |
| --- | --- |
| MD_REG_CHANNEL_TENCENT_AD | 腾讯广告 |
| MD_REG_CHANNEL_FINDER_LIVE_AD | 视频号-直播间广告 |

##### 细分渠道（自然大类 natural 下）

| **值** | **说明** |
| --- | --- |
| MD_REG_CHANNEL_GAME_CENTER | 微信游戏中心 |
| MD_REG_CHANNEL_OTHER_WEAPP | 其他小程序 |
| MD_REG_CHANNEL_CHAT | 会话 |
| MD_REG_CHANNEL_SEARCH | 搜索 |
| MD_REG_CHANNEL_TASKBAR_RECENT | 任务栏-最近使用 |
| MD_REG_CHANNEL_RECENT_WEAPP_LIST | 最近使用小程序列表 |
| MD_REG_CHANNEL_TASKBAR_MY_WEAPP | 任务栏-我的小程序 |
| MD_REG_CHANNEL_DISCOVER_MY_WEAPP | 发现入口-我的小程序 |
| MD_REG_CHANNEL_DISCOVER | 发现页 |
| MD_REG_CHANNEL_CHAT_TOP | 聊天顶部 |
| MD_REG_CHANNEL_EXTERNAL_APP | 外部应用 |
| MD_REG_CHANNEL_THIRD_PARTY_APP | 第三方 APP |
| MD_REG_CHANNEL_APP_SHARE | APP 分享 |
| MD_REG_CHANNEL_MOMENT | 朋友圈 |
| MD_REG_CHANNEL_FINDER | 视频号 |
| MD_REG_CHANNEL_FINDER_LIVE | 视频号-直播间 |

#### PlacementGroup

- 广告版位，仅在 channel=ad/ MD_REG_CHANNEL_TENCENT_AD / MD_REG_CHANNEL_FINDER_LIVE_AD （广告渠道，含其下广告细分） 时有意义。
- 数组元素取具体版位枚举或特殊值 EACH/TOTAL，且EACH/TOTAL 不可与具体版位枚举值同时出现在同一数组中，也不可同时传入EACH和TOTAL，（否则参数格式错误）。

合法值

| **值** | **说明** |
| --- | --- |
| MD_PLACEMENT_GROUP_WX_MOMENT | 微信朋友圈 |
| MD_PLACEMENT_GROUP_WX_FINDER | 微信视频号 |
| MD_PLACEMENT_GROUP_SEARCH | 搜索 |
| MD_PLACEMENT_GROUP_YLH | 优量汇 |
| MD_PLACEMENT_GROUP_WX_BIZ_WEAPP | 微信公众号与小程序 |
| MD_PLACEMENT_GROUP_PCAD | 腾讯平台与内容媒体 |
| MD_PLACEMENT_GROUP_PC_DEVICE | 腾讯广告电脑端 |
| MD_PLACEMENT_GROUP_TV_DEVICE | 腾讯广告电视端 |
| MD_PLACEMENT_GROUP_FINDER_FREETRADE | 腾讯视频号互选广告 |
| MD_PLACEMENT_GROUP_OTHER | 其他 |
| EACH | 特殊值：展开全部版位的逐项明细 |
| TOTAL | 特殊值：纯聚合，不按版位拆（等价于不传） |

#### CreativeType

规则同 PlacementGroup。

合法值

| **值** | **说明** |
| --- | --- |
| MD_CREATIVE_TYPE_IMG | 图片 |
| MD_CREATIVE_TYPE_VIDEO | 视频 |
| MD_CREATIVE_TYPE_SEARCH | 搜索 |
| MD_CREATIVE_TYPE_BOX | 格子 |
| MD_CREATIVE_TYPE_REWARDED_CANVAS | 激励 |
| MD_CREATIVE_TYPE_OTHER | 其他 |
| EACH | 特殊值：展开全部创意的逐项明细 |
| TOTAL | 特殊值：纯聚合，不按创意拆（等价于不传） |

#### CreativeSize

激励创意尺寸，仅对 MD_CREATIVE_TYPE_REWARDED_CANVAS 生效，其他创意类型忽略。数组元素为下列具体尺寸枚举或特殊值 EACH/TOTAL；EACH/TOTAL 不可与具体尺寸枚举混传，也不可同时传入。

合法值

| **值** | **说明** |
| --- | --- |
| MD_CREATIVE_SIZE_REWARDED_CANVAS_DIRECT_PLAY | 激励直玩 |
| MD_CREATIVE_SIZE_REWARDED_CANVAS_TRIAL_PLAY | 激励试玩 |
| EACH | 特殊值：展开全部尺寸的逐项明细 |
| TOTAL | 特殊值：纯聚合，不按尺寸拆（等价于不传） |

#### Adpos

- 变现广告位 ID，与注册渠道无关，对全渠道生效。
- 数组元素取具体广告位枚举或特殊值 EACH/TOTAL，且EACH/TOTAL 不可与具体版位枚举值同时出现在同一数组中，也不可同时传入EACH和TOTAL，（否则参数格式错误）。

合法值

| **值** | **说明** |
| --- | --- |
| 1030436212907001 | 激励广告 |
| 3030046789020061 | 插屏广告 |
| 4071202390577885 | 原生模板广告 |
| 8040321819858439 | Banner 广告 |
| 5060180989186180 | 封面广告 |
| 4101952574125419 | 激励广告(PC) |
| 9101846442965090 | 插屏广告(PC)  |
| 6151744442060270 | 原生模版广告(PC)  |
| EACH | 特殊值：展开全部广告位的逐项明细 |
| TOTAL | 特殊值：全部广告位（等价于不传） |


---

## 五、错误码

| **ret** | **含义** | **解决方案** |
| --- | --- | --- |
| 0 | 成功 | - |
| 40001 | 必填参数缺失 | 检查请求参数 |
| 40002 | 参数格式错误 | 检查参数格式 |
| 40003 | 参数业务约束冲突 | 按本文的参数组合约束调整请求 |
| 40004 | filters 数量超限 | 减少时间段数量 |
| 40101 | appid 无权限（未加白） | 向运营团队申请加白 |
| 40102 | 频率超限 | 退避后重试 |
| 50001 | 数据查询失败 | 一段时间后重试 |
| 50002 | 内部错误 | 一段时间后重试或联系开发者 |

**部分时间段失败**：当一次请求中某个时间段（filter）的数据查询失败时，ret 仍为 0，失败的时间段在 results 中缺省，err_msg 记录失败详情；全部失败时返回对应 5xxxx 错误码。

**无数据**：查询日期范围内无数据时，ret 为 0，对应时间段的 dimension_groups/daily_list 返回空数组，汇总指标返回 0，不报错。