# Open API 接口文档

***

## 1. 通用约定

### 1.1 概述

Ptengine Open API 提供 RESTful 接口，用于程序化查询热图分析数据。您可以将本文档提供给 AI Agent，AI Agent 将根据自然语言需求自动构造查询请求，直接调用接口获取数据。

**接口基础地址：**

```
https://xbackend.ptengine.com/
```

### 1.2 认证方式

所有 API 请求需通过 `x-api-key` 请求头传递 API Key。

```
x-api-key: pt-your-api-key-here
```

**获取 API Key 步骤：**

> **权限要求**：仅 Admin 和 Owner 角色可以创建和管理 API Key。

1. 登录 Ptengine 产品
2. 进入 Experience 模块
3. 点击右上角设置图标（⚙），选择"外部应用集成"
4. 切换到"API 密钥"标签页
5. 点击"创建 API 密钥"，输入名称并选择权限范围（数据上传/数据查询）
6. 复制并妥善保存密钥（密钥仅在创建时展示一次）

### 1.3 请求频率限制

根据套餐等级不同，限流值不同：

| 套餐         | RPM（每分钟） | RPD（每天） |
| ---------- | -------- | ------- |
| Free       | 3        | 100     |
| Free Trial | 10       | 1,000   |
| Growth     | 30       | 3,000   |

频率限制信息通过响应头返回：

```
X-RateLimit-Limit-Minute: 30
X-RateLimit-Remaining-Minute: 28
X-RateLimit-Limit-Day: 3000
X-RateLimit-Remaining-Day: 2997
X-RateLimit-Tier: GROWTH
```

### 1.4 响应格式

所有端点统一返回以下 JSON 包装：

* 成功（HTTP 200）：`{ "code": 200, "message": "OK", "data": ... }`
* 失败（HTTP 4xx）：`{ "code": 4xxx, "message": "..." }`

完整错误码见 [附录](#错误码)。

***

## 2. Insight

本章包含 Heatmap、Event、Data Center、Conversion 四个查询端点。

### 2.1 共用规则

Heatmap、Event、Data Center、Conversion 这 4 个端点的请求里都有 `conversionNames` 和 `filters` 两个字段。`conversionNames` 里的目标名去哪查；`filters` 怎么写、里面的可选值去哪查 —— 都按本节来。先看完再去看对应端点的章节，就能直接上手。

#### 转化目标

查询数据时如果想看转化（比如"购买完成了多少次"、"注册转化率多少"），得先告诉系统要看哪个转化目标。这个接口返回你在 Ptengine 里配置过的所有目标名，拿到后填进查询请求即可。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/goals \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "conversions": [
            { "id": "1753350579776", "name": "ptmind 注册" },
            { "id": "1753350579999", "name": "购买完成" }
        ]
    }
}
```

拿到 `name` 后，把它写到查询接口（`/event/query`、`/datacenter/query`、`/conversion/query`、`/heatmap/query`）的 `conversionNames` 字段里就能查这个目标的数据。比如 `"conversionNames": ["购买完成"]`。

#### Filter

在请求体的 `filters` 字段里加条件，圈定要查的数据范围。比如只看 Mobile 端、只看日本地区、只看某广告活动来源。

```json
{ "name": "country", "op": "include", "value": ["Japan"] }
```

字段说明：

| 字段      | 含义                                    |
| ------- | ------------------------------------- |
| `name`  | 要过滤的字段名（按字段类型见下面分类）                   |
| `op`    | `include`（包含）或 `exclude`（排除），不支持其它运算符 |
| `value` | 要过滤的值，必须是数组（哪怕只有一个值也写成 `["Japan"]`）   |

> 自定义属性 filter（按事件属性过滤）需要额外的 `eventName` / `eventVariant` 字段，详见下面"自定义属性 filter（进阶）"。

按字段类型分两类：

**固定字段**

下面 4 个字段的取值是固定的，照抄即可：

| name         | 说明   | 可选值                                                                                            |
| ------------ | ---- | ---------------------------------------------------------------------------------------------- |
| `deviceType` | 设备类型 | `PC`、`Mobile`、`Tablet`                                                                         |
| `sourceType` | 来源类型 | `Direct`（直接访问）、`Search`（搜索引擎）、`Social`（社交网络）、`Referral`（外部链接）、`Campaign`（广告）、`AISearch`（AI 搜索） |
| `visitType`  | 访问类型 | `New visits`（新访问）、`Returning visits`（回访访问）                                                     |
| `exitType`   | 退出类型 | `Bounce visits`（跳出会话）、`Non-bounce visits`（非跳出会话）                                               |

**动态字段**

取值随数据变化，调下面的[filter 可选值](#filter-values)接口实时查询。

| 类别 | name               | 说明         | value 示例                                                     |
| -- | ------------------ | ---------- | ------------------------------------------------------------ |
| 设备 | `os`               | 操作系统       | `["Windows", "Mac OS X"]`                                    |
| 设备 | `osVersion`        | 操作系统版本     | `["Windows 10", "Mac OS X 10.15.7", "iOS 17.0"]`             |
| 设备 | `browser`          | 浏览器        | `["Chrome", "Mobile Safari", "Edge"]`                        |
| 设备 | `browserVersion`   | 浏览器版本      | `["Chrome 124.0.0", "Edge 146.0.0", "Mobile Safari 13.0.3"]` |
| 设备 | `screenResolution` | 分辨率        | `["1920x1080", "1440x900"]`                                  |
| 设备 | `deviceBrand`      | 设备品牌       | `["Apple", "Samsung"]`                                       |
| 地理 | `country`          | 国家 / 地区    | `["Japan", "China", "United States"]`                        |
| 地理 | `region`           | 省 / 州      | `["Tokyo", "Beijing", "Hong Kong"]`                          |
| 来源 | `searchEngine`     | 搜索引擎       | `["google"]`                                                 |
| 来源 | `socialNetwork`    | 社交网络       | `["facebook"]`                                               |
| 来源 | `socialUrl`        | 社交 URL     | `["https://www.facebook.com/"]`                              |
| 来源 | `aiName`           | AI 名称      | `["ChatGPT", "Perplexity"]`                                  |
| 来源 | `referralSource`   | 外部链接网站     | `["www.muji.com"]`                                           |
| 来源 | `referralUrl`      | 外部链接 URL   | `["https://www.muji.com/"]`                                  |
| 广告 | `campaignUrl`      | 广告 URL     | `["https://www.google.com/"]`                                |
| 广告 | `utmCampaign`      | 广告名称       | `["summer_sale"]`                                            |
| 广告 | `utmSource`        | 广告来源       | `["google", "facebook"]`                                     |
| 广告 | `utmMedium`        | 广告媒介       | `["cpc", "email"]`                                           |
| 广告 | `utmTerm`          | 广告关键词      | `["heatmap tool"]`                                           |
| 广告 | `utmContent`       | 广告内容       | `["banner_a"]`                                               |
| 页面 | `combinedPages`    | 合参页面       | `["https://ptengine.jp/app/login"]`                          |
| 页面 | `originalPages`    | 原始页面       | `["https://ptengine.jp/app/select_project?from=login"]`      |
| 事件 | `eventName`        | 事件名        | `["checkout_completed", "product_viewed"]`                   |
| 事件 | `dimension`        | 自定义维度（跨事件） | 需配合 `eventVariant` 使用                                        |
| 事件 | `eventDimension`   | 自定义维度（事件名） | 需配合 `eventName` 和 `eventVariant` 使用                          |
| 转化 | `conversionName`   | 转化名称       | `["购买完成"]`                                                   |

> value 示例仅供参考，实际可用值请调 [filter 可选值](#filter-values) 接口查询。

**自定义属性 filter（进阶）**

只在你的事件带了自定义属性（比如 `purchase` 事件带 `price` 属性）、想按属性值过滤时才用。两种形态：

* **绑定具体事件**：`{ "name": "eventDimension", "eventName": "purchase", "eventVariant": "price", "op": "include", "value": ["100"] }` —— 仅查 `purchase` 事件下 `price=100` 的会话
* **跨事件查找**：`{ "name": "dimension", "eventVariant": "price", "op": "include", "value": ["100"] }` —— 任何事件下 `price=100` 都命中

**filter 可选值**

返回某个 filter 字段的可选值列表（如所有有数据的国家、所有 OS 等）。返回的值可**直接用作**任意 query 端点 filter 的 `value` 字段。

**请求参数说明**

| 参数             | 是否必填 | 类型     | 说明                                                                                                                      |
| -------------- | ---- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `profileId`    | 是    | string | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9` |
| `name`         | 是    | string | 要查的 filter 字段名，见上面 [动态字段](#动态字段) 表                                                                                      |
| `startDate`    | 否    | string | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`。不传则默认最近 30 天                                                                        |
| `endDate`      | 否    | string | 结束日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`。不传则默认最近 30 天                                                                        |
| `search`       | 否    | string | 模糊搜索关键字                                                                                                                 |
| `eventName`    | 条件必填 | string | 仅 `name="eventDimension"` 时使用（见示例 5 第 2 步）                                                                              |
| `eventVariant` | 条件必填 | string | 仅 `name="eventDimension"` 时使用（见示例 5 第 2 步）                                                                              |

**示例 1：查询常规字段（如 country / os / browser 等）**

请求示例：

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "country",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

响应示例：

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "country",
        "values": ["Japan", "China", "United States", "Singapore"]
    }
}
```

**示例 2：模糊搜索（`search`）**

只想看名字含某个关键字的值，传 `search` 即可。比如查国家名包含 "Ja" 的（会命中 Japan、Jamaica 等）：

请求示例：

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "country",
    "search": "Ja",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

响应示例：

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "country",
        "values": ["Japan", "Jamaica"]
    }
}
```

**示例 3：查询所有事件名（`name="eventName"`）**

返回 profile 下所有有数据的事件名列表。

请求示例：

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "eventName",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

响应示例：

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventName",
        "values": ["purchase", "add_to_cart", "gallery_item_impression"]
    }
}
```

**示例 4：查询事件自定义属性列表**

返回 profile 下所有事件自定义属性名。

请求示例：

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "dimension",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

响应示例：

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "dimension",
        "values": ["price", "currency", "qty", "category"]
    }
}
```

**示例 5：查询某事件下属性的取值（`eventDimension`，两步走）**

`eventDimension` 必须分两步查：先用 `name="eventDimension"` 拿到"事件 + 属性"成对清单，再带上选中的 `eventName` + `eventVariant` 查具体取值。

**第 1 步 —— 拿事件 + 属性清单：**

请求示例：

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "eventDimension",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

响应示例：

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventDimension",
        "values": [
            { "eventName": "purchase", "eventVariant": "price" },
            { "eventName": "purchase", "eventVariant": "currency" },
            { "eventName": "add_to_cart", "eventVariant": "qty" }
        ]
    }
}
```

**第 2 步 —— 用选中的 eventName + eventVariant 查取值：**

请求示例：

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "eventDimension",
    "eventName": "purchase",
    "eventVariant": "price",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

响应示例：

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventDimension",
        "eventName": "purchase",
        "eventVariant": "price",
        "values": ["100", "200", "500"]
    }
}
```

***

### 2.2 Heatmap

热图分析 —— 页面 / 区块 / 元素的点击与浏览。

#### 请求参数说明

| 参数                | 是否必填 | 类型        | 说明                                                                                                                                                                                                                                                  |
| ----------------- | ---- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queryType`       | 是    | string    | 查询类型，可选值：`page_metrics`（页面指标）、`page_insight`（页面详情指标）、`block_metrics`（区块指标）、`element_metrics`（元素指标）                                                                                                                                                  |
| `profileId`       | 是    | string    | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9`                                                                                                                             |
| `url`             | 是    | string    | 目标页面 URL                                                                                                                                                                                                                                            |
| `startDate`       | 是    | string    | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                                                                                                                                                 |
| `endDate`         | 是    | string    | 结束日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                                                                                                                                                 |
| `deviceType`      | 是    | string    | 设备类型筛选，见 [设备类型规则](#设备类型规则)                                                                                                                                                                                                                          |
| `rangeType`       | 否    | string    | URL 匹配模式。`MERGE_URL`（默认）合并参数查询，忽略 URL 参数差异；`URL` 原始 URL 精确查询                                                                                                                                                                                        |
| `metrics`         | 否    | string\[] | 不传返回所有指标，传了只返回指定指标。可用指标见 [可用指标](#可用指标)                                                                                                                                                                                                              |
| `conversionNames` | 否    | string\[] | 转化名称列表，见 §2.1 [转化目标](#转化目标)                                                                                                                                                                                                                         |
| `filters`         | 否    | object\[] | 筛选条件，见 §2.1 [Filter](#filter)                                                                                                                                                                                                                       |
| `lang`            | 否    | string    | 返回标签的语言：`EN`（默认）、`ZH`（中文）、`JP`（日文）。传入非合法值时降级为 `EN`                                                                                                                                                                                                  |
| `funName`         | 条件必填 | string    | 仅 `page_insight` 类型时必填。可选值：`terminalType`（设备类型）、`sourceType`（流量来源）、`visitType`（新访/旧访）、`aiName`（流量获取渠道）、`utmCampaign`（UTM Campaign）、`utmSource`（UTM Source）、`utmMedium`（UTM Medium）、`utmTerm`（UTM Term）、`utmContent`（UTM Content）、`week`（周）、`day`（日） |

#### 查询类型

**`page_metrics` — 页面基础指标**

返回指定页面的流量、行为互动、转化等指标数据。

**设备类型：** 支持 `ALL`（全设备）、`PC`、`MOBILE`、`TABLET`

**指标参数：** `metrics`（不传返回所有指标，传了只返回指定指标）

**转化查询：** 所有查询类型都支持转化。在 `metrics` 中加入 `completions`（转化数）和 `conversionRate`（转化率）—— 两者可单独传或同时传，再通过 `conversionNames` 传入转化名称即可。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "page_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["pv", "uv", "visits", "bounceRate", "conversionRate"],
    "conversionNames": ["购买完成"],
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "metrics": {
            "pv": {
                "value": "15,234",
                "label": "浏览量（PV）",
                "description": "页面被浏览的次数。"
            },
            "uv": {
                "value": "8,721",
                "label": "访问者（UV）",
                "description": "该页面被浏览的访问者数量。"
            },
            "visits": {
                "value": "10,532",
                "label": "访问次数",
                "description": "页面被浏览的访问次数。"
            },
            "bounceRate": {
                "value": "45.23%",
                "label": "跳出率",
                "description": "访问者从该页面进入后未进入其他页面而离开的百分比。"
            },
            "conversionRate": {
                "value": "2.22%",
                "label": "转化率",
                "description": "访问过此页面并完成转化的占比，转化率越高说明此页面对转化行为的影响越好。"
            }
        },
        "conversions": [
            {
                "conversionName": "购买完成",
                "conversionRate": {
                    "value": "1.71%",
                    "label": "转化率",
                    "description": "访问过此页面并完成转化的占比，转化率越高说明此页面对转化行为的影响越好。"
                }
            }
        ]
    },
    "meta": {
        "queryType": "page_metrics",
        "profileId": "566d12f9",
        "url": "https://ptengine.jp",
        "dateRange": { "start": "2025-06-01", "end": "2025-06-30" },
        "deviceType": "ALL",
        "lang": "ZH"
    }
}
```

> **说明：** `conversions` 中只返回 `metrics` 里请求的转化指标。上例 `metrics` 中只有 `conversionRate`，所以 conversions 里只有转化率，没有完成数。如需同时返回转化数，在 `metrics` 中加入 `completions`。

**`page_insight` — 页面详情指标（按维度分组）**

返回按指定维度分组的页面指标数据。

**设备类型：** 支持 `ALL`、`PC`、`MOBILE`、`TABLET`

**必填参数：** `funName`（`metrics` 不传返回所有指标）

**funName 可选值：**

| funName        | 说明                                   |
| -------------- | ------------------------------------ |
| `terminalType` | 按设备类型分组（PC/Smart phone/Tablet）       |
| `sourceType`   | 按流量来源分组（Direct/Search/Social 等）      |
| `visitType`    | 按访问类型分组（New visits/Returning visits） |
| `aiName`       | 按 AI 名称分组                            |
| `utmCampaign`  | 按 UTM Campaign 分组                    |
| `utmSource`    | 按 UTM Source 分组                      |
| `utmMedium`    | 按 UTM Medium 分组                      |
| `utmTerm`      | 按 UTM Term 分组                        |
| `utmContent`   | 按 UTM Content 分组                     |
| `week`         | 按周分组                                 |
| `day`          | 按天分组                                 |

**请求示例（按设备类型分组）：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "page_insight",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["pv", "uv", "bounceRate"],
    "funName": "terminalType",
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "insights": [
            {
                "name": "PC",
                "metrics": {
                    "pv": { "value": "8,500", "label": "浏览量（PV）", "description": "页面被浏览的次数。" },
                    "uv": { "value": "5,200", "label": "访问者（UV）", "description": "该页面被浏览的访问者数量。" },
                    "bounceRate": {
                        "value": "38.00%",
                        "label": "跳出率",
                        "description": "访问者从该页面进入后未进入其他页面而离开的百分比。"
                    }
                },
                "conversions": []
            },
            {
                "name": "Mobile",
                "metrics": {
                    "pv": { "value": "5,800", "label": "浏览量（PV）", "description": "页面被浏览的次数。" },
                    "uv": { "value": "3,100", "label": "访问者（UV）", "description": "该页面被浏览的访问者数量。" },
                    "bounceRate": {
                        "value": "55.00%",
                        "label": "跳出率",
                        "description": "访问者从该页面进入后未进入其他页面而离开的百分比。"
                    }
                },
                "conversions": []
            },
            {
                "name": "Tablet",
                "metrics": {
                    "pv": { "value": "934", "label": "浏览量（PV）", "description": "页面被浏览的次数。" },
                    "uv": { "value": "421", "label": "访问者（UV）", "description": "该页面被浏览的访问者数量。" },
                    "bounceRate": {
                        "value": "42.15%",
                        "label": "跳出率",
                        "description": "访问者从该页面进入后未进入其他页面而离开的百分比。"
                    }
                },
                "conversions": []
            }
        ]
    }
}
```

**`block_metrics` — 区块指标**

返回页面中每个区块（版块）的指标数据和截图地址。要求页面已在产品中完成扫描并配置区块。

**设备类型：** 必须指定 `PC`、`MOBILE` 或 `TABLET`，**不支持 `ALL`**

**metrics 参数：** 可选。不传则返回全部指标，传了则只返回指定指标。`blockName` 和 `screenshotUrl` 始终返回。

**可用指标：** `impression`、`impressionRate`、`avgDuration`、`dropoff`、`dropoffRate`、`completions`、`conversionRate`

**stayTimeFilter：** 可选，区块停留时间过滤（秒），默认 5 秒。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "block_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "PC",
    "rangeType": "MERGE_URL",
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "blocks": [
            {
                "blockName": "首屏横幅",
                "screenshotUrl": "https://cdn.example.com/screenshot/block1.png",
                "metrics": {
                    "impression": {
                        "value": "12,000",
                        "label": "曝光",
                        "description": "用户开始在屏幕上看到当前区块的PV数。"
                    },
                    "impressionRate": {
                        "value": "95.00%",
                        "label": "曝光率",
                        "description": "用户开始在屏幕上看到当前区块的PV占比。"
                    },
                    "avgDuration": {
                        "value": "5s",
                        "label": "平均停留时间",
                        "description": "看到此区块的人，在此区块停下后的平均停留时间。"
                    },
                    "dropoff": {
                        "value": "800",
                        "label": "流失",
                        "description": "从当前区块离开，并且没有点击去其他页面或完成转化的PV数。"
                    },
                    "dropoffRate": { "value": "6.70%", "label": "流失率", "description": "从当前区块离开的PV占比。" }
                },
                "conversions": []
            }
        ]
    }
}
```

**`element_metrics` — 元素指标**

返回页面中每个被追踪元素的指标数据。要求页面已在产品中完成扫描并配置元素。

**设备类型：** 必须指定 `PC`、`MOBILE` 或 `TABLET`，**不支持 `ALL`**

**metrics 参数：** 可选。不传则返回全部指标，传了则只返回指定指标。`elementName` 始终返回。

**可用指标：** `impression`、`impressionRate`、`click`、`clickRate`、`completions`、`conversionRate`

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "element_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "PC",
    "rangeType": "MERGE_URL",
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "elements": [
            {
                "elementName": "注册按钮",
                "metrics": {
                    "impression": { "value": "10,500", "label": "曝光", "description": "用户看到当前元素的PV数。" },
                    "impressionRate": {
                        "value": "88.00%",
                        "label": "曝光率",
                        "description": "用户看到当前元素的PV占比。"
                    },
                    "click": { "value": "1,500", "label": "点击", "description": "点击当前元素的次数。" },
                    "clickRate": { "value": "14.30%", "label": "点击率", "description": "点击次数÷曝光次数。" }
                },
                "conversions": []
            }
        ]
    }
}
```

#### 可用指标

**页面指标（用于 `page_metrics` 和 `page_insight`）**

在 `metrics` 数组中使用以下字段名。

#### 流量获取

| 字段              | 说明                               | 类型    |
| --------------- | -------------------------------- | ----- |
| `visits`        | 页面被浏览的访问次数                       | value |
| `pv`            | 页面被浏览的次数                         | value |
| `uv`            | 该页面被浏览的访问者数量                     | value |
| `newVisitsRate` | 浏览过该页面的新访问百分比                    | rate  |
| `entrances`     | 页面被作为落地页的访问次数。您可以了解此页面是否主要用于承接流量 | value |

#### 行为互动

| 字段             | 说明                                                    | 类型      |
| -------------- | ----------------------------------------------------- | ------- |
| `fvRate`       | 用户进入页面后，没有滚动也没有转化或进入到后续页面的比例。首屏流失率过高代表页面的首屏没有吸引用户留下   | rate    |
| `timeOnPage`   | 页面的平均停留时间。您可以了解页面内容是否吸引访客停留更长时间                       | time    |
| `clicks`       | 页面总点击次数，无论是否有链接                                       | value   |
| `clickRate`    | 单个 PV 的点击次数。您可以用其评估用户对页面的互动程度                         | rate    |
| `ctaClicks`    | 页面内关键 CTA 的点击数。您可以在热图中将关键元素设置为 CTA                    | value   |
| `ctaClickRate` | 页面内关键 CTA 的点击率。CTA 点击率=CTA 点击数/PV。您可以在热图中将关键元素设置为 CTA | rate    |
| `bounceRate`   | 访问者从该页面进入后未进入其他页面而离开的百分比。您可以了解落地页是否吸引用户进一步访问更多页面      | rate    |
| `avgPageViews` | 访问者从该页面落地后的平均访问页面数。您可以了解从此页面落地的用户在网站中的浏览深度            | decimal |

#### 转化

| 字段               | 说明                                  | 类型    |
| ---------------- | ----------------------------------- | ----- |
| `completions`    | 访问过此页面并完成转化的访问数                     | value |
| `conversionRate` | 访问过此页面并完成转化的占比，转化率越高说明此页面对转化行为的影响越好 | rate  |

> **注意：** 查询转化数据时，必须同时通过 `conversionNames` 传入转化目标的名称。

**区块指标（用于 `block_metrics`）**

不传 `metrics` 参数时全部返回，传了则只返回指定的指标。`blockName` 和 `screenshotUrl` 始终返回。

| 字段               | 说明                                              | 类型    |
| ---------------- | ----------------------------------------------- | ----- |
| `blockName`      | 区块名称                                            | text  |
| `screenshotUrl`  | 区块截图地址                                          | text  |
| `impression`     | 用户开始在屏幕上看到当前区块的 PV 数                            | value |
| `impressionRate` | 用户开始在屏幕上看到当前区块的 PV 占比                           | rate  |
| `dropoff`        | 从当前区块离开，并且没有点击去其他页面或完成转化的 PV 数                  | value |
| `dropoffRate`    | 从当前区块离开，并且没有点击去其他页面或完成转化的 PV 占比                 | rate  |
| `avgDuration`    | 看到此区块的人，在此区块停下后的平均停留的时间。平均停留时间越长，通常代表用户对此区块更感兴趣 | time  |
| `completions`    | 在各内容区块停留特定时间，且完成转化的访问次数                         | value |
| `conversionRate` | 在各内容区块停留特定时间的访问中，完成转化的访问占比                      | rate  |

**元素指标（用于 `element_metrics`）**

不传 `metrics` 参数时全部返回，传了则只返回指定的指标。`elementName` 始终返回。

| 字段               | 说明                               | 类型    |
| ---------------- | -------------------------------- | ----- |
| `elementName`    | 元素名称                             | text  |
| `impression`     | 用户开始在屏幕上看到当前元素的 PV 数             | value |
| `impressionRate` | 用户开始在屏幕上看到当前元素的 PV 占比            | rate  |
| `click`          | 点击当前元素的点击次数                      | value |
| `clickRate`      | 点击次数 ÷ 曝光次数。点击率越高，说明该元素越容易吸引用户点击 | rate  |
| `completions`    | 点击各元素且完成转化的访问次数                  | value |
| `conversionRate` | 在点击各元素的访问中，完成转化的访问占比             | rate  |

#### 设备类型规则

| 查询类型              | 支持的 deviceType               | 说明              |
| ----------------- | ---------------------------- | --------------- |
| `page_metrics`    | `ALL`、`PC`、`MOBILE`、`TABLET` | `ALL` 返回全设备汇总数据 |
| `page_insight`    | `ALL`、`PC`、`MOBILE`、`TABLET` | `ALL` 返回全设备汇总数据 |
| `block_metrics`   | `PC`、`MOBILE`、`TABLET`       | **不支持** `ALL`   |
| `element_metrics` | `PC`、`MOBILE`、`TABLET`       | **不支持** `ALL`   |

#### 区块与元素查询前置条件

使用 `block_metrics` 或 `element_metrics` 查询前，必须先在 Ptengine 产品中对页面进行扫描配置：

1. 在 Ptengine 热图中打开目标页面
2. 开启区块/元素检测功能
3. 保存配置

如果页面尚未配置，接口将返回错误码 `4008`（区块未配置）或 `4016`（元素未配置）。

#### 请求示例

**示例 1：查询页面流量概览**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "page_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["visits", "pv", "uv", "bounceRate", "timeOnPage"],
    "lang": "ZH"
  }'
```

**示例 2：按设备类型查询页面详情指标**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "page_insight",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["pv", "uv", "bounceRate", "clickRate"],
    "funName": "terminalType",
    "lang": "ZH"
  }'
```

**示例 3：查询移动端区块分析（含 filter 筛选日本地区）**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "block_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "MOBILE",
    "rangeType": "MERGE_URL",
    "filters": [
      { "name": "country", "op": "include", "value": ["Japan"] }
    ],
    "lang": "ZH"
  }'
```

**示例 4：查询指定转化目标数据**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "page_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "ALL",
    "rangeType": "MERGE_URL",
    "metrics": ["pv", "completions", "conversionRate"],
    "conversionNames": ["购买完成"],
    "lang": "ZH"
  }'
```

**示例 5：查询 PC 端元素点击分析**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-a8Kd3mNx9Qr2Tf5Vb7Wj1Yp0Ls4Hn6Uc" \
  -d '{
    "queryType": "element_metrics",
    "profileId": "566d12f9",
    "url": "https://ptengine.jp",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "deviceType": "PC",
    "rangeType": "MERGE_URL",
    "lang": "ZH"
  }'
```

#### 补充说明

* 时间类字段（如页面 `timeOnPage`、区块 `avgDuration`）以可读字符串返回，带单位（例如 `"5s"`、`"1m 30s"`）。
* 比率类型的值为小数（例如 `bounceRate: 0.45` 表示 45%）。
* API 使用的数据源与 Ptengine 产品界面一致，查询结果应保持一致。
* 请求的 URL 在该档案下从未被采集时，接口返回 `200`，但所有指标值为 `0`，不返回错误。

***

### 2.3 Event

事件分析。按维度、指标、细分（即请求里的 `filters` 字段）进行事件查询。

#### 请求参数说明

| 参数           | 是否必填 | 类型                    | 说明                                                                                                                                                                                       |
| ------------ | ---- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId`  | 是    | string                | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9`                                                                  |
| `startDate`  | 是    | string                | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                                                                                      |
| `endDate`    | 是    | string                | 结束日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                                                                                      |
| `dimensions` | 是    | (string \| object)\[] | 分组维度数组，必须包含 `"eventName"`。最多 3 个非时间维度 + 至多 1 个时间维度（`day` / `hour` / `week` / `month`），与产品 **事件 > 分群** 页面一致。每项是字符串（标准维度名）或对象 `{ name: "eventDimension", eventVariant: "<属性名>" }`（自定义事件属性） |
| `metrics`    | 否    | string\[]             | 指标字段名，默认 `["eventCount"]`；可选值：`eventCount`、`sessions`                                                                                                                                    |
| `filters`    | 否    | object\[]             | 细分（filter）条件，见 §2.1 [Filter](#filter)                                                                                                                                                    |

**自定义事件属性**

你的事件如果带了自定义属性（比如 `purchase` 事件带 `price` 属性），可以用属性做分组或细分。

* **按属性分组** —— 在 `dimensions` 里加：

  ```json
  { "name": "eventDimension", "eventVariant": "price" }
  ```

  结果会按 `price` 值聚合。
* **按属性细分** —— 在 `filters` 里加：

  ```json
  { "name": "eventDimension", "eventName": "purchase", "eventVariant": "price", "op": "include", "value": ["100"] }
  ```

  只看 `purchase` 事件下 `price=100` 的会话。
* **细分时务必同时锁定事件** —— 用属性细分时，`filters` 里还要再加一条事件名细分，否则查询不知道锁哪个事件：

  ```json
  { "name": "eventName", "op": "include", "value": ["purchase"] }
  ```

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "day", "country"],
    "metrics": ["eventCount", "sessions"],
    "filters": [
      { "name": "eventName", "op": "include", "value": ["purchase"] },
      { "name": "country", "op": "include", "value": ["Japan", "China"] },
      { "name": "visitType", "op": "include", "value": ["New visits"] },
      { "name": "deviceType", "op": "include", "value": ["PC", "Mobile"] },
      {
        "name": "eventDimension",
        "eventName": "purchase",
        "eventVariant": "price",
        "op": "include",
        "value": ["100", "200"]
      }
    ]
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "columns": [
            { "name": "eventName", "type": "dimension", "dataType": "STRING" },
            { "name": "day", "type": "dimension", "dataType": "DATE" },
            { "name": "country", "type": "dimension", "dataType": "STRING" },
            { "name": "eventCount", "type": "metric", "dataType": "INTEGER" },
            { "name": "sessions", "type": "metric", "dataType": "INTEGER" }
        ],
        "rows": [
            { "eventName": "purchase", "day": "2026-04-15", "country": "Japan", "eventCount": 320, "sessions": 250 }
        ]
    }
}
```

#### 更多示例

**a) 最简 — 按事件名统计触发次数**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName"]
  }'
```

**b) 时间序列 — 按天统计**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "day"],
    "metrics": ["eventCount", "sessions"]
  }'
```

**c) 按转化目标过滤（名称模糊匹配）**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "conversionName"],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName", "op": "include", "value": ["purchase"] },
        { "name": "conversionName", "op": "include", "value": ["ptmind"] }
    ]
  }'
```

> `conversionName` 匹配名称含 `"ptmind"` 的所有目标。如果没有任何匹配项，返回 `4012`。

**d) 自定义事件属性 — 分组 + 过滤**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", { "name": "eventDimension", "eventVariant": "position" }],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName", "op": "include", "value": ["gallery_item_impression"] },
        {
            "name": "eventDimension",
            "eventName": "gallery_item_impression",
            "eventVariant": "position",
            "op": "include",
            "value": ["home"]
        }
    ]
  }'
```

> 两个 filter 都必填，作用不同：独立的 `eventName` filter 把查询整体锁定到 `gallery_item_impression`（聚合范围）；`eventDimension` filter 进一步按 `position == "home"` 细分（segment）。

**e) 流量来源分布 — UTM + 来源类型**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "sourceType", "utmSource"],
    "metrics": ["eventCount", "sessions"],
    "filters": [
        { "name": "eventName", "op": "include", "value": ["purchase"] },
        { "name": "sourceType", "op": "include", "value": ["Search", "Campaign"] }
    ]
  }'
```

**f) 新访客 + PC + 日本/中国**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "country"],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName", "op": "include", "value": ["purchase"] },
        { "name": "visitType", "op": "include", "value": ["New visits"] },
        { "name": "deviceType", "op": "include", "value": ["PC"] },
        { "name": "country", "op": "include", "value": ["Japan", "China"] }
    ]
  }'
```

**g) 排除直接跳出会话**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/event/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName"],
    "metrics": ["eventCount", "sessions"],
    "filters": [{ "name": "exitType", "op": "exclude", "value": ["Bounce visits"] }]
  }'
```

#### 元数据

返回所有可用的 metrics 和 dimensions（含多语言文案，可选 lang 切换）。

**请求示例：**

```bash
curl -X GET "https://xbackend.ptengine.com/open-api/v1/event/fields?lang=ZH" \
  -H "x-api-key: pt-your-api-key"
```

**响应示例（节选）：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "metrics": [
            { "field": "eventCount", "label": "事件数", "description": "事件发生的次数。", "dataType": "INTEGER" },
            { "field": "sessions", "label": "访问数", "description": "事件发生的访问数。", "dataType": "INTEGER" }
        ],
        "dimensions": [
            { "field": "eventName", "label": "事件名称", "description": "事件名称。", "dataType": "STRING", "category": "event" },
            { "field": "country", "label": "国家", "description": "国家。", "dataType": "STRING", "category": "geography" }
        ]
    }
}
```

#### 可用指标

| 字段           | 说明       | dataType |
| ------------ | -------- | -------- |
| `eventCount` | 事件发生的次数  | INTEGER  |
| `sessions`   | 事件发生的访问数 | INTEGER  |

#### 可用维度（用于 `dimensions[]` 分组）

| 字段                 | 说明      |
| ------------------ | ------- |
| `eventName`        | 事件名称    |
| `visitType`        | 访问类型    |
| `exitType`         | 退出类型    |
| `combinedPages`    | 进入页面    |
| `conversionName`   | 转化名称    |
| `day`              | 日期      |
| `hour`             | 小时      |
| `week`             | 周       |
| `month`            | 月       |
| `sourceType`       | 来源类型    |
| `campaignUrl`      | 广告URL   |
| `referralSource`   | 外部链接网站  |
| `referralUrl`      | 外部链接URL |
| `searchEngine`     | 搜索引擎    |
| `socialNetwork`    | 社交网络    |
| `socialUrl`        | 社交URL   |
| `aiName`           | AI搜索    |
| `utmCampaign`      | 广告名称    |
| `utmSource`        | 广告来源    |
| `utmMedium`        | 广告媒介    |
| `utmContent`       | 广告内容    |
| `utmTerm`          | 广告关键词   |
| `deviceType`       | 设备类型    |
| `deviceBrand`      | 品牌      |
| `os`               | 操作系统    |
| `osVersion`        | 操作系统版本  |
| `browser`          | 浏览器     |
| `browserVersion`   | 浏览器版本   |
| `screenResolution` | 分辨率     |
| `country`          | 国家/地区   |
| `region`           | 省/州     |

#### 注意事项

* `dimensions` 必传，**且必须包含字符串 `"eventName"`**——事件查询必须按事件名分组。可以在它旁边再加其它维度 / `eventDimension` 对象。
* **维度数量限制**：最多 3 个非时间维度 + 至多 1 个时间维度（`day` / `hour` / `week` / `month`）。超过任一上限返回 4018。
* **何时必须传 `eventName` filter**：满足以下任一情况：

  * `dimensions` 含 `eventName` / 时间维度之外的字段（如 `country`、`sourceType`）
  * `dimensions` 含 `eventDimension` 对象
  * `filters` 含 `eventDimension` 项

  形态：`{ "name": "eventName", "op": "include", "value": ["<事件名>"] }`。缺失返回 4018。

***

### 2.4 Data Center

站点数据分析 —— 站点指标 / 流量来源 / 地理分布 / 设备、OS、浏览器分布 / 按维度查看明细。

#### 请求参数说明

| 参数               | 是否必填 | 类型        | 说明                                                                                                                                                                                                                 |
| ---------------- | ---- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `queryType`      | 是    | string    | 查询类型，可选值：`overview`（按主题的总览数据）、`dimension_table`（按维度的 Top-N 表格）、`metric_curve`（单个指标的时间序列）                                                                                                                           |
| `profileId`      | 是    | string    | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9`                                                                                            |
| `startDate`      | 是    | string    | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                                                                                                                |
| `endDate`        | 是    | string    | 结束日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                                                                                                                |
| `filters`        | 否    | object\[] | 筛选条件，见 §2.1 [Filter](#filter)                                                                                                                                                                                      |
| `conversionName` | 否    | string    | 按单个转化目标过滤指标。**未传时返回所有转化的指标**。仅 `dimension_table`（除 `combinedPages` / `originalPages` / `pageGroup` 外的 dimension）与 `metric_curve`（`metric` ∈ `conversions` / `conversionRate` / `conversionValue`）下生效；其他场景传入返回 4018 |
| `lang`           | 否    | string    | 返回标签的语言：`EN`（默认）、`ZH`（中文）、`JP`（日文）。仅影响 `overview` 的 `topic = "metrics"` 响应、以及 `dimension_table` 的 metric 列 `label` / `description`。传入非合法值降级为 `EN`                                                                  |

#### 查询类型

**`overview` — 按主题的总览数据**

按主题返回总览数据。

**必填：** `topic`，可选值：`metrics` / `sources` / `location` / `device`。

> 想看更细的明细（具体搜索引擎 / 引荐 URL / 广告活动名、或 OS / 浏览器分布等）请用 `queryType: "dimension_table"` 配合相应 `dimension`。

**`topic = "metrics"` — 指标总览**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "overview",
    "topic": "metrics",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "filters": [{ "name": "country", "op": "include", "value": ["Japan"] }],
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "topic": "metrics",
        "metrics": {
            "visits": {
                "value": "12,500",
                "label": "访问次数",
                "description": "网站被访问的次数。访客每次访问网站都会记录1次访问。"
            },
            "users": {
                "value": "8,900",
                "label": "访问者(UV)",
                "description": "在此期间访问网站的访客数。多次访问网站的访客将作为 1 名访客计算。"
            },
            "pageView": {
                "value": "32,000",
                "label": "浏览量(PV)",
                "description": "页面被浏览的次数。"
            },
            "newVisitsRate": {
                "value": "65.00%",
                "label": "新访次数百分比",
                "description": "在全部访问中，首次访问网站的百分比。"
            },
            "returnVisitsRate": {
                "value": "35.00%",
                "label": "回访次数百分比",
                "description": "在全部访问中，曾经访问过该网站的访问量百分比。"
            },
            "avgPageView": {
                "value": "2.56",
                "label": "人均浏览页数",
                "description": "访客浏览页面的平均页数。您可以了解访客访问网站的深度。"
            },
            "avgVisits": {
                "value": "1.40",
                "label": "人均访问次数",
                "description": "访客访问网站的平均次数。您可以了解大多数访客是否会再次访问网站。"
            },
            "avgVisitDuration": {
                "value": "3m 7s",
                "label": "平均停留时间",
                "description": "网站的平均访问时间。您可以了解网站内容是否吸引访客停留更长时间。"
            },
            "avgLoadTime": {
                "value": "4s",
                "label": "页面平均加载时间",
                "description": "页面加载的平均时间。加载时间越长，访客流失的可能性就越大。"
            },
            "bounceRate": {
                "value": "42.00%",
                "label": "跳出率",
                "description": "仅浏览了一个页面就离开的访问百分比。您可以了解落地页是否吸引用户进一步访问更多页面。"
            }
        }
    }
}
```

**`topic = "sources"` — 流量来源**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "overview",
    "topic": "sources",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "topic": "sources",
        "totalVisits": 12500,
        "rows": [
            { "sourceType": "Direct", "visits": 5200 },
            { "sourceType": "Search", "visits": 3100 },
            { "sourceType": "Social", "visits": 1800 },
            { "sourceType": "Referral", "visits": 1500 },
            { "sourceType": "Campaign", "visits": 700 },
            { "sourceType": "AISearch", "visits": 200 }
        ]
    }
}
```

**`topic = "location"` — 地理分布**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "overview",
    "topic": "location",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "topic": "location",
        "rows": [
            { "country": "Japan", "state": "Tokyo", "visits": 4200 },
            { "country": "Japan", "state": "Osaka", "visits": 1800 },
            { "country": "China", "state": "Shanghai", "visits": 1500 },
            { "country": "United States", "state": "California", "visits": 900 }
        ]
    }
}
```

**`topic = "device"` — 设备分布**

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "overview",
    "topic": "device",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "topic": "device",
        "rows": [
            {
                "deviceType": "PC",
                "visits": 7800,
                "osVersion": [
                    { "name": "Windows 10", "visits": 5200 },
                    { "name": "Windows 11", "visits": 1800 }
                ],
                "resolution": [
                    { "name": "1920x1080", "visits": 3200 },
                    { "name": "1366x768", "visits": 2100 }
                ],
                "browserVersion": [
                    { "name": "Chrome 120", "visits": 4500 },
                    { "name": "Safari 17", "visits": 800 }
                ]
            },
            {
                "deviceType": "Mobile",
                "visits": 3600,
                "osVersion": [
                    { "name": "iOS 17", "visits": 2100 },
                    { "name": "Android 14", "visits": 1500 }
                ],
                "brand": [
                    { "name": "Apple", "visits": 2100 },
                    { "name": "Samsung", "visits": 900 }
                ],
                "browserVersion": [
                    { "name": "Safari 17", "visits": 2100 },
                    { "name": "Chrome Mobile 120", "visits": 1300 }
                ]
            },
            {
                "deviceType": "Tablet",
                "visits": 1100,
                "osVersion": [{ "name": "iPadOS 17", "visits": 900 }],
                "brand": [{ "name": "Apple", "visits": 900 }],
                "browserVersion": [{ "name": "Safari 17", "visits": 900 }]
            }
        ]
    }
}
```

**`dimension_table` — 按维度的 Top-N 表格**

返回按某个维度分组的 Top-N 表格。

**必填：** `dimension` —— 见 [可用维度](#dc-dimensions)。

**可选：** `sortBy` (string) / `sortOrder` (`asc`/`desc`) / `limit`（1-1000，默认 1000）。响应固定上限 1000 行。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "dimension_table",
    "dimension": "country",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "sortBy": "visits",
    "sortOrder": "desc",
    "limit": 100,
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "columns": [
            { "name": "country", "type": "dimension", "dataType": "STRING" },
            { "name": "visits", "type": "metric", "dataType": "INTEGER", "label": "访问次数", "description": "网站被访问的次数。访客每次访问网站都会记录1次访问。" },
            { "name": "avgVisitDuration", "type": "metric", "dataType": "TIME", "label": "平均停留时间", "description": "网站的平均访问时间。您可以了解网站内容是否吸引访客停留更长时间。" },
            { "name": "pageView", "type": "metric", "dataType": "INTEGER", "label": "浏览量(PV)", "description": "页面被浏览的次数。" },
            { "name": "newVisitsRate", "type": "metric", "dataType": "RATE", "label": "新访次数百分比", "description": "在全部访问中，首次访问网站的百分比。" },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE", "label": "转化率", "description": "完成特定转换的访问百分比。转化率 = 转化数 / 总访问数。转换率越高，说明这类访问的性能越好。" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER", "label": "转化数", "description": "完成特定转化的访问次数。" },
            { "name": "bounceRate", "type": "metric", "dataType": "RATE", "label": "跳出率", "description": "仅浏览了一个页面就离开的访问百分比。您可以了解落地页是否吸引用户进一步访问更多页面。" }
        ],
        "rows": [
            {
                "country": "China",
                "visits": "619",
                "avgVisitDuration": "00:02:49",
                "pageView": "1,145",
                "newVisitsRate": "52.18%",
                "conversionRate": "96.28%",
                "conversions": "596",
                "bounceRate": "74.64%"
            },
            {
                "country": "Japan",
                "visits": "530",
                "avgVisitDuration": "00:00:08",
                "pageView": "553",
                "newVisitsRate": "99.81%",
                "conversionRate": "94.91%",
                "conversions": "503",
                "bounceRate": "96.04%"
            }
        ]
    }
}
```

> `columns` 里 `metric` 类型列附带 `label` / `description`（语言由 `lang` 字段决定，默认 `EN`）。 Metric 值已按产品 UI 列格式化为字符串：INTEGER 千分位（`"1,145"`）、RATE 百分比（`"52.18%"`）、`avgVisitDuration` HH:MM:SS（`"00:02:49"`）、`avgLoadTime` 亚秒精度（`"2.45s"`）。客户端需要原始数值时按字符串解析。

**示例：页面列表**

按"进入页面"列出 Top-N，不传 `conversionName` 时返回所有转化集合的指标。

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "dimension_table",
    "dimension": "entryCombinedPages",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "sortBy": "entrances",
    "sortOrder": "desc",
    "limit": 50,
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "columns": [
            { "name": "url", "type": "dimension", "dataType": "STRING" },
            { "name": "title", "type": "dimension", "dataType": "STRING" },
            { "name": "entrances", "type": "metric", "dataType": "INTEGER", "label": "进入次数", "description": "页面被作为落地页的访问次数。" },
            { "name": "newVisitsRate", "type": "metric", "dataType": "RATE", "label": "新访次数百分比", "description": "在全部访问中，首次访问网站的百分比。" },
            { "name": "avgPageVisits", "type": "metric", "dataType": "NUMBER", "label": "平均访问PV", "description": "访客从该页面落地后的平均访问页面数。" },
            { "name": "avgVisitDuration", "type": "metric", "dataType": "TIME", "label": "平均停留时间", "description": "网站的平均访问时间。您可以了解网站内容是否吸引访客停留更长时间。" },
            { "name": "bounceRate", "type": "metric", "dataType": "RATE", "label": "跳出率", "description": "仅浏览了一个页面就离开的访问百分比。您可以了解落地页是否吸引用户进一步访问更多页面。" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER", "label": "转化数", "description": "完成特定转化的访问次数。" },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE", "label": "转化率", "description": "完成特定转换的访问百分比。转化率 = 转化数 / 总访问数。转换率越高，说明这类访问的性能越好。" }
        ],
        "rows": [
            { "url": "https://ptengine.jp", "title": "Ptengineウェブ運営All-in-Oneプラットフォーム | ウェブの改善や改善業務はこれひとつで完結", "entrances": "253", "newVisitsRate": "71.15%", "avgPageVisits": "1.29", "avgVisitDuration": "00:01:55", "bounceRate": "84.58%", "conversions": "253", "conversionRate": "100.00%" },
            { "url": "https://ptengine.jp/app/login", "title": "ログイン | Ptengine", "entrances": "186", "newVisitsRate": "31.18%", "avgPageVisits": "1.62", "avgVisitDuration": "00:01:24", "bounceRate": "44.62%", "conversions": "172", "conversionRate": "92.47%" }
        ]
    }
}
```

> 页面类维度（`combinedPages` / `originalPages` / `entryCombinedPages` / `entryOriginalPages`）响应列固定为 `url` + `title`；`pageGroup` 维度 row 值是组名字符串。
>
> **关于 `conversionName` 的适用范围**：
>
> * `entryCombinedPages` / `entryOriginalPages`（进入页面）**支持**：传入后 `conversions` 与 `conversionRate` 两列只统计指定转化目标（与产品 UI 入口页表格右上角"选择转化目标"下拉一致），其他指标不受影响。
> * `combinedPages` / `originalPages` / `pageGroup`（页面 / 页面组）**不支持**：该维度的指标不计算转化目标，传入 `conversionName` 将返回 `4018`。

**示例：按单个转化目标过滤指标**

传 `conversionName` 后，指标（`conversions` / `conversionRate` 等）仅按命中的转化目标计算。

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "dimension_table",
    "dimension": "entryCombinedPages",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "conversionName": "ptmind",
    "sortBy": "conversions",
    "sortOrder": "desc",
    "limit": 20,
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "columns": [
            { "name": "url", "type": "dimension", "dataType": "STRING" },
            { "name": "title", "type": "dimension", "dataType": "STRING" },
            { "name": "entrances", "type": "metric", "dataType": "INTEGER", "label": "进入次数", "description": "页面被作为落地页的访问次数。" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER", "label": "转化数", "description": "完成特定转化的访问次数。" },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE", "label": "转化率", "description": "完成特定转换的访问百分比。转化率 = 转化数 / 总访问数。转换率越高，说明这类访问的性能越好。" }
        ],
        "rows": [
            { "url": "https://ptengine.jp/app/signup", "title": "登録 | Ptengine", "entrances": "1,042", "conversions": "312", "conversionRate": "29.94%" },
            { "url": "https://ptengine.jp", "title": "Ptengineウェブ運営All-in-Oneプラットフォーム | ウェブの改善や改善業務はこれひとつで完結", "entrances": "815", "conversions": "187", "conversionRate": "22.94%" }
        ]
    }
}
```

**`metric_curve` — 单个指标的时间序列**

返回单个指标的时间序列。

**必填：** `metric`，可选值见 [可用指标](#dc-metrics)；`granularity`，可选值：`hour` / `day` / `week` / `month`。响应中 `time` 字段格式 `YYYY-MM-DD`（`hour` 粒度时为 `YYYY-MM-DDTHH`）。

> **`hour` 粒度限制**：`startDate` 和 `endDate` 必须为同一天，否则返回 `4002`。`day` / `week` / `month` 无此限制。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/datacenter/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "metric_curve",
    "metric": "visits",
    "granularity": "day",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "filters": [{ "name": "deviceType", "op": "include", "value": ["PC"] }]
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "metric": "visits",
        "granularity": "day",
        "points": [
            { "time": "2026-04-01", "value": "420" },
            { "time": "2026-04-02", "value": "510" }
        ]
    }
}
```

#### 可用指标

| 指标                 | 类型      | 说明       |
| ------------------ | ------- | -------- |
| `visits`           | INTEGER | 访问次数     |
| `users`            | INTEGER | 访问者(UV)  |
| `pageView`         | INTEGER | 浏览量(PV)  |
| `newVisitsRate`    | RATE    | 新访次数百分比  |
| `returnVisitsRate` | RATE    | 回访次数百分比  |
| `avgVisits`        | RATE    | 人均访问次数   |
| `avgPageView`      | RATE    | 人均浏览页数   |
| `avgVisitDuration` | TIME    | 平均停留时间   |
| `bounceRate`       | RATE    | 跳出率      |
| `avgLoadTime`      | TIME    | 页面平均加载时间 |
| `conversions`      | INTEGER | 转化数      |
| `conversionRate`   | RATE    | 转化率      |
| `conversionValue`  | NUMBER  | 转化价值     |

#### 可用维度（用于 `queryType: "dimension_table"`）

| 维度                   | 说明       |
| -------------------- | -------- |
| `country`            | 国家/地区    |
| `state`              | 省/州      |
| `os`                 | 操作系统     |
| `osVersion`          | 操作系统版本   |
| `browser`            | 浏览器      |
| `browserVersion`     | 浏览器版本    |
| `resolution`         | 分辨率      |
| `brand`              | 品牌       |
| `sourceType`         | 来源类型     |
| `campaign`           | 广告活动     |
| `campaignUrl`        | 广告活动 URL |
| `referral`           | 外部链接     |
| `referralUrl`        | 外部链接 URL |
| `search`             | 搜索引擎     |
| `socialMedia`        | 社交网络     |
| `socialUrl`          | 社交网络 URL |
| `aiName`             | AI 搜索来源  |
| `adSource`           | UTM 来源   |
| `adName`             | UTM 广告名称 |
| `adMedium`           | UTM 媒介   |
| `adTerm`             | UTM 关键词  |
| `adContent`          | UTM 内容   |
| `combinedPages`      | 合参页面     |
| `originalPages`      | 原始页面     |
| `pageGroup`          | 页面组      |
| `entryCombinedPages` | 入口合参页面   |
| `entryOriginalPages` | 入口原始页面   |

***

### 2.5 Conversion

转化目标分析 —— 完成数 / 转化价值 / 来源分布 / 漏斗分析。

#### 请求参数说明

| 参数               | 是否必填 | 类型        | 说明                                                                                                                                                                                    |
| ---------------- | ---- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queryType`      | 是    | string    | 查询类型，可选值：`metrics`（转化指标）、`metric_curve`（时间趋势）、`sources_breakdown`（按来源分布）、`ad_name_breakdown`（按广告名分布）、`ad_source_breakdown`（按广告来源分布）、`funnel`（漏斗）、`regular`（正向目标列表）、`negative`（负向目标列表） |
| `profileId`      | 是    | string    | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9`                                                               |
| `startDate`      | 是    | string    | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                                                                                   |
| `endDate`        | 是    | string    | 结束日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                                                                                   |
| `conversionName` | 条件必填 | string    | 目标名（必须正好命中 1 个目标，否则 4012）。**仅 `funnel` 必填**；其他 queryType **不需要传**（即使传了也会被忽略）                                                                                                          |
| `metric`         | 条件必填 | string    | `metric_curve` 类型必填 —— `completions`（完成数）/ `conversionRate`（转化率）/ `conversionValue`（转化价值）                                                                                             |
| `granularity`    | 条件必填 | string    | `metric_curve` 类型必填 —— `hour` / `day` / `week` / `month`                                                                                                                              |
| `filters`        | 否    | object\[] | 筛选条件（细分），见 §2.1 [Filter](#filter)                                                                                                                                                     |
| `lang`           | 否    | string    | 返回 label/description 的语言：`EN`（默认）、`ZH`、`JP`。当前仅 `queryType = "metrics"` 响应使用。传入非合法值降级为 `EN`                                                                                           |

#### 查询类型

**`metrics` — 转化指标**

返回 5 个指标：**转化数 / 转化率 / 转化价值 / 收益 / 损失**。每个指标包装为 `{ value, label }`，`label` 按 `lang` 字段切换语言。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "metrics",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "lang": "ZH",
    "filters": [{ "name": "country", "op": "include", "value": ["Japan"] }]
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "queryType": "metrics",
        "metrics": {
            "conversions":     { "value": "214",     "label": "转化数" },
            "conversionRate":  { "value": "45.73%",  "label": "转化率" },
            "conversionValue": { "value": "-21,100", "label": "转化价值" },
            "revenue":         { "value": "0",       "label": "收益" },
            "loss":            { "value": "-21,100", "label": "损失" }
        }
    }
}
```

**字段说明：**

| 字段                | 计算                          |
| ----------------- | --------------------------- |
| `conversions`     | 完成正向转化的访问次数（所有目标合计）         |
| `conversionRate`  | `conversions / 总访问次数`       |
| `conversionValue` | `revenue + loss`（含负值）       |
| `revenue`         | 正向转化目标（cvValue ≥ 0）的总收益     |
| `loss`            | 负向转化目标（cvValue < 0）的总损失（负数） |

**`metric_curve` — 时间趋势**

返回单个转化指标的时间序列。

**必填：** `metric` —— `completions`（完成数）/ `conversionRate`（转化率）/ `conversionValue`（转化价值）；`granularity` —— `hour` / `day` / `week` / `month`。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "metric_curve",
    "metric": "completions",
    "granularity": "day",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "queryType": "metric_curve",
        "metric": "completions",
        "granularity": "day",
        "points": [
            { "time": "2026-04-01", "value": "24" },
            { "time": "2026-04-02", "value": "35" }
        ]
    }
}
```

**`sources_breakdown` — 按来源分布**

按流量来源分组查看转化数据。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "sources_breakdown",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "queryType": "sources_breakdown",
        "columns": [
            { "name": "sourceType", "type": "dimension", "dataType": "STRING" },
            { "name": "sourceName", "type": "dimension", "dataType": "STRING" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER" }
        ],
        "rows": [
            { "sourceType": "Direct", "sourceName": "no refer", "conversions": 1259 },
            { "sourceType": "Search", "sourceName": "google", "conversions": 13 },
            { "sourceType": "Referral", "sourceName": "https://example.com/", "conversions": 12 }
        ]
    }
}
```

**`ad_name_breakdown` — 按广告名分布**

按广告名（UTM Campaign）分组查看转化数据。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "ad_name_breakdown",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "queryType": "ad_name_breakdown",
        "columns": [
            { "name": "adName", "type": "dimension", "dataType": "STRING" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER" }
        ],
        "rows": [
            { "adName": "spring_sale_2026", "conversions": 320 },
            { "adName": "brand_awareness_q1", "conversions": 158 },
            { "adName": "retargeting_jp", "conversions": 92 }
        ]
    }
}
```

**`ad_source_breakdown` — 按广告来源分布**

按广告来源（UTM Source）分组查看转化数据。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "ad_source_breakdown",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "queryType": "ad_source_breakdown",
        "columns": [
            { "name": "adSource", "type": "dimension", "dataType": "STRING" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER" }
        ],
        "rows": [
            { "adSource": "google", "conversions": 420 },
            { "adSource": "facebook", "conversions": 180 },
            { "adSource": "newsletter", "conversions": 65 }
        ]
    }
}
```

**`funnel` — 漏斗**

返回漏斗每步的进入数、流失数、向下一步的转化率。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "funnel",
    "conversionName": "ptmind 注册",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "queryType": "funnel",
        "conversionName": "ptmind 注册",
        "conversionId": "1753350579776",
        "summary": {
            "totalConversions": 700,
            "totalConversionRate": "70.00%"
        },
        "steps": [
            {
                "stepId": 1, "entries": 1000, "external": 1000, "dropoff": 200,
                "conversionToNextRate": "80.00%",
                "entryPaths":   [{ "url": "https://example.com/landing", "visits": 600 }],
                "dropoffPaths": [{ "url": "Exit", "visits": 5 }, { "url": "https://example.com/other", "visits": 195 }]
            },
            {
                "stepId": 2, "entries": 800, "external": 0, "dropoff": 100,
                "conversionToNextRate": "87.50%",
                "entryPaths": [],
                "dropoffPaths": [{ "url": "https://example.com/other", "visits": 100 }]
            },
            {
                "stepId": 3, "entries": 700, "external": 0, "dropoff": 0,
                "conversionToNextRate": null,
                "entryPaths": [], "dropoffPaths": []
            }
        ]
    }
}
```

**字段说明：**

| 字段                            | 含义                                      |
| ----------------------------- | --------------------------------------- |
| `entries`                     | 本步骤进入数（`external + convert`）            |
| `external`                    | 本步骤的外部进入数（不经过上一步直接进入本步骤）                |
| `dropoff`                     | 本步骤流出数 = `entries − 下一步 convert`（末步为 0） |
| `conversionToNextRate`        | 向下一步的转化率（末步为 `null`）                    |
| `entryPaths`                  | 本步骤外部进入的入口页面 URL 列表，按访问次数降序             |
| `dropoffPaths`                | 本步骤流出页面 URL 列表，按访问次数降序；无法追踪的流出归入 `Exit` |
| `summary.totalConversions`    | 漏斗最终达成数（末步 `entries`）                   |
| `summary.totalConversionRate` | 总转化率 = 末步 `entries` / 各步 `external` 之和  |

**`regular` — 正向转化目标列表**

返回所有"正向"（价值 ≥ 0）转化目标各自的指标，每行一个目标。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/conversion/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "queryType": "regular",
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "data": {
        "queryType": "regular",
        "columns": [
            { "name": "conversionName", "type": "dimension", "dataType": "STRING" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER" },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE" },
            { "name": "revenue", "type": "metric", "dataType": "NUMBER" }
        ],
        "rows": [
            { "conversionName": "ptmind 注册", "conversions": "850", "conversionRate": "6.20%", "revenue": "0" },
            { "conversionName": "下载白皮书",  "conversions": "130", "conversionRate": "1.00%", "revenue": "0" }
        ]
    }
}
```

**`negative` — 负向转化目标列表**

结构同 `regular`，返回所有"负向"（价值 < 0，即流失类）转化目标，每行额外带 `loss` 字段（绝对损失值）。

#### 注意事项

* `conversionName` 仅 `funnel` 必填；其他 queryType 不需要传（即使传了也会被忽略）。
* `funnel` 的 `conversionName` 必须正好命中**一个**目标。命中多个（如 `"ptmind"` 同时匹配 `"ptmind 注册"` 和 `"ptmind 购买"`）时返回 4012 + 列出所有命中名，请使用更精确的名称。
* 用 `POST /v1/conversion/goals` 先查所有目标列表再构造请求。

***

## 3. Experience

### 3.1 获取体验列表

获取当前档案下所有体验的基本信息，包括目标和版本列表。后续接口的 `id`、`goalId`、`versionId` 均来自此接口的返回值。

#### 请求参数说明

| 参数          | 是否必填 | 类型     | 说明                                                                                                                      |
| ----------- | ---- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `profileId` | 是    | string | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9` |

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/list \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        {
            "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
            "name": "春季促销弹窗",
            "status": "RUNNING",
            "type": "POPUP",
            "goals": [{ "id": "6a8bedde-...", "name": "购买完成" }],
            "versions": [
                { "id": "a2696719-...", "name": "Control" },
                { "id": "b3c8f210-...", "name": "Pattern 1" }
            ]
        }
    ]
}
```

| 返回字段       | 说明                                                             |
| ---------- | -------------------------------------------------------------- |
| `id`       | 体验 ID，用于报告接口的 `id` 参数                                          |
| `name`     | 体验名称                                                           |
| `status`   | 状态：`DRAFT` / `RUNNING` / `PAUSE` / `SCHEDULED`                 |
| `type`     | 类型：`POPUP` / `STICKY_BAR` / `INLINE` / `ADVANCED` / `REDIRECT` |
| `goals`    | 目标列表，用于 A/B 测试接口的 `goalId` 参数                                  |
| `versions` | 版本列表，用于表单接口的 `versionId` 参数                                    |

***

### 3.2 获取用户属性列表

获取可用的用户属性列表。当维度细分接口 `dimension` 为 `userProperty` 时，需要从此接口获取 `property` 参数。

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/user-properties \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        { "name": "plan_name", "displayName": "套餐名", "source": ["code"], "type": "STRING" },
        { "name": "signup_date", "displayName": "注册日期", "source": ["default"], "type": "DATE" }
    ]
}
```

***

### 3.3 体验概览指标

批量查询多个体验的指标数据。

#### 请求参数说明

| 参数            | 是否必填 | 类型        | 说明                                                                                                                      |
| ------------- | ---- | --------- | ----------------------------------------------------------------------------------------------------------------------- |
| `profileId`   | 是    | string    | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9` |
| `experiences` | 是    | object\[] | 体验列表（`id` + `name`，来自 list 接口）                                                                                          |
| `metrics`     | 否    | string\[] | 要返回的指标字段。不传返回全部默认指标。支持的字段见下方指标表                                                                                         |
| `lang`        | 否    | string    | 返回语言：`EN`（默认）、`ZH`、`JP`                                                                                                 |

**`metrics` 支持的字段：**

| 字段                   | 说明                      | 类型      |
| -------------------- | ----------------------- | ------- |
| `viewedUsers`        | 体验被展示的用户数               | value   |
| `views`              | 体验被展示的次数                | value   |
| `clickedUsers`       | 点击体验中按钮或链接的用户数          | value   |
| `clickRate`          | 点击体验中按钮或链接的用户比率         | rate    |
| `closedUsers`        | 关闭弹窗或悬浮条的用户数            | value   |
| `closeRate`          | 关闭弹窗或悬浮条的用户比率           | rate    |
| `formSubmittedUsers` | 体验中表单提交的用户数             | value   |
| `formSubmitRate`     | 体验中表单提交的用户比率            | rate    |
| `goalReachedUsers`   | 展示体验后达成目标的用户数           | value   |
| `goalReachRate`      | 查看体验后达成目标的用户比率          | rate    |
| `goalStatus`         | 按人数占比、属性加和或平均值，展示目标达成情况 | value   |
| `avgVisitDuration`   | 展示过体验的用户的平均访问时长         | time    |
| `avgPagesPerVisit`   | 展示过体验的用户每个访问的平均浏览页面数    | decimal |
| `bounceRate`         | 展示过体验的访问跳出率             | rate    |
| `lastUpdatedTime`    | 体验最后被更新的时间              | text    |
| `lastUpdatedMember`  | 体验最后被更新的成员              | text    |
| `createdTime`        | 创建体验的时间                 | text    |
| `createdMember`      | 创建体验的成员                 | text    |
| `runningPeriod`      | 体验被运行的时间期间              | text    |
| `tags`               | 每个体验的自定义属性标签            | text    |

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/overview \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "experiences": [
      { "id": "6c3bad4b-...", "name": "春季促销弹窗" },
      { "id": "5bb77b97-...", "name": "注册引导" }
    ],
    "metrics": ["viewedUsers", "clickRate", "bounceRate"],
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        {
            "name": "春季促销弹窗",
            "viewedUsers": { "value": 100, "label": "展示用户数", "description": "体验被展示的用户数。" },
            "clickRate": { "value": "5.00%", "label": "点击率", "description": "点击体验中按钮或链接的用户比率。" },
            "bounceRate": { "value": "42.86%", "label": "跳出率", "description": "展示过体验的访问跳出率。" }
        }
    ]
}
```

> 所有指标返回 `{ value, label, description }` 结构，`label` 和 `description` 根据 `lang` 返回对应语言。

***

### 3.4 关键指标

查询单个体验的总体指标。

#### 请求参数说明

| 参数          | 是否必填 | 类型     | 说明                                                                                                                      |
| ----------- | ---- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `profileId` | 是    | string | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9` |
| `id`        | 是    | string | 体验 ID（来自 list 接口）                                                                                                       |
| `startDate` | 是    | string | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |
| `endDate`   | 是    | string | 结束日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |
| `lang`      | 否    | string | 返回 label/description 的语言：`EN`（默认）、`ZH`、`JP`                                                                             |

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/metrics \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "春季促销弹窗",
        "items": [
            {
                "viewedUsers": { "value": 100, "label": "展示用户数", "description": "..." },
                "views": { "value": 300, "label": "展示次数", "description": "..." },
                "clickedUsers": { "value": 50, "label": "点击用户数", "description": "..." },
                "clickRate": { "value": "41.67%", "label": "点击率", "description": "..." },
                "goals": [
                    {
                        "name": "购买完成",
                        "reachedUsers": { "value": 5, "label": "目标达成用户数", "description": "..." },
                        "reachRate": { "value": "5.00%", "label": "目标达成率", "description": "..." },
                        "value": { "value": null, "label": "目标达成情况", "description": "..." }
                    }
                ],
                "avgVisitDuration": { "value": "06:33", "label": "平均访问时长", "description": "..." },
                "avgPagesPerVisit": { "value": "2.50", "label": "平均访问页面数", "description": "..." },
                "bounceRate": { "value": "42.86%", "label": "跳出率", "description": "..." }
            }
        ]
    }
}
```

> **注意**：返回的指标会根据体验类型自动过滤。例如 INLINE 类型不会返回 `clickedUsers` / `closedUsers`，没有表单的体验不会返回 `formSubmittedUsers`。

***

### 3.5 细分详情

按维度分组查询单个体验的指标数据。

#### 请求参数说明

| 参数             | 是否必填 | 类型     | 说明                                                                                                                      |
| -------------- | ---- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `profileId`    | 是    | string | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9` |
| `id`           | 是    | string | 体验 ID（来自 list 接口）                                                                                                       |
| `startDate`    | 是    | string | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |
| `endDate`      | 是    | string | 结束日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |
| `dimension`    | 是    | string | 主维度，详见下方维度表                                                                                                             |
| `subDimension` | 否    | string | 二级维度                                                                                                                    |
| `property`     | 条件必填 | object | `dimension` 为 `userProperty` 时必填，从 user-properties 接口获取                                                                 |
| `lang`         | 否    | string | 返回 label/description 的语言：`EN`（默认）、`ZH`、`JP`                                                                             |

**`dimension` 可选值：**

| dimension      | 说明     | 支持 subDimension   |
| -------------- | ------ | ----------------- |
| `visitPage`    | 页面     | ❌                 |
| `terminalType` | 设备类型   | ✅                 |
| `sourceType`   | 流量来源   | ✅                 |
| `utmCampaign`  | 广告名称   | ✅                 |
| `utmSource`    | 广告来源   | ✅                 |
| `utmMedium`    | 广告媒介   | ✅                 |
| `utmTerm`      | 广告关键词  | ✅                 |
| `utmContent`   | 广告内容   | ✅                 |
| `sourceUrl`    | 来源 URL | ✅                 |
| `sourceHost`   | 来源域名   | ✅                 |
| `aiName`       | AI 名称  | ✅                 |
| `visitType`    | 新访/回访  | ✅                 |
| `country`      | 国家/地区  | ✅（不能和 region 组合）  |
| `region`       | 地区     | ✅（不能和 country 组合） |
| `userProperty` | 用户属性   | ❌（需传 property）    |

**userProperty 示例：** `dimension` 为 `userProperty` 时，必须额外传 `property`：

```json
{ "property": { "name": "plan_name", "source": ["code"], "type": "STRING" } }
```

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/insight \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "dimension": "terminalType",
    "subDimension": "visitType",
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "春季促销弹窗",
        "items": [
            {
                "name": "PC",
                "subName": "新访",
                "viewedUsers": { "value": 80, "label": "展示用户数", "description": "..." },
                "bounceRate": { "value": "38.00%", "label": "跳出率", "description": "..." }
            },
            {
                "name": "手机",
                "subName": "回访",
                "viewedUsers": { "value": 20, "label": "展示用户数", "description": "..." },
                "bounceRate": { "value": "55.00%", "label": "跳出率", "description": "..." }
            }
        ]
    }
}
```

***

### 3.6 A/B 测试的结果

查询 A/B 测试各版本的指标对比数据，包含 uplift 和胜率。

#### 请求参数说明

| 参数                    | 是否必填 | 类型      | 说明                                                                                                                      |
| --------------------- | ---- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `profileId`           | 是    | string  | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9` |
| `id`                  | 是    | string  | 体验 ID（来自 list 接口）                                                                                                       |
| `startDate`           | 是    | string  | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |
| `endDate`             | 是    | string  | 结束日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |
| `compareBy`           | 是    | string  | 版本对比基准指标，详见下方                                                                                                           |
| `goalId`              | 条件必填 | string  | `compareBy` 为 `goalReached` 时必填（从 list 接口的 goals 获取）                                                                    |
| `showDeletedVersions` | 否    | boolean | 是否包含已删除版本，默认 false                                                                                                      |
| `lang`                | 否    | string  | 返回 label/description 的语言：`EN`（默认）、`ZH`、`JP`                                                                             |

**`compareBy` 可选值：**

| compareBy            | 说明                   |
| -------------------- | -------------------- |
| `viewedUsers`        | 体验被展示的用户数            |
| `clickedUsers`       | 点击体验中按钮或链接的用户数       |
| `closedUsers`        | 关闭弹窗或悬浮条的用户数         |
| `formSubmittedUsers` | 体验中表单提交的用户数          |
| `goalReached`        | 目标达成（需配合 `goalId`）   |
| `avgVisitDuration`   | 展示过体验的用户的平均访问时长      |
| `avgPagesPerVisit`   | 展示过体验的用户每个访问的平均浏览页面数 |
| `bounceRate`         | 展示过体验的访问跳出率          |

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/abtest/metrics \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "compareBy": "goalReached",
    "goalId": "6a8bedde-084d-4828-b874-43568cd2f27f",
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "春季促销弹窗",
        "items": [
            {
                "name": "Control",
                "viewedUsers": { "value": 50, "label": "展示用户数", "description": "..." },
                "goalReachedUsers": { "value": 5, "label": "目标达成用户数", "description": "..." },
                "goalReachRate": { "value": "10.00%", "label": "目标达成率", "description": "..." },
                "uplift": { "value": "Baseline", "label": "提升", "description": "..." },
                "probabilityToBeBest": { "value": null, "label": "优胜率", "description": "..." }
            },
            {
                "name": "Pattern 1",
                "viewedUsers": { "value": 50, "label": "展示用户数", "description": "..." },
                "goalReachedUsers": { "value": 8, "label": "目标达成用户数", "description": "..." },
                "goalReachRate": { "value": "16.00%", "label": "目标达成率", "description": "..." },
                "uplift": { "value": "+60.00%", "label": "提升", "description": "..." },
                "probabilityToBeBest": { "value": "85.30%", "label": "优胜率", "description": "..." }
            }
        ]
    }
}
```

> * 返回值只包含 `compareBy` 对应的指标 + `uplift` + `probabilityToBeBest`
> * 基准版本的 `uplift` 值为 `"Baseline"`，其他版本为百分比（如 `"+50.00%"` 或 `"-10.00%"`）

***

### 3.7 A/B 测试的结果 — 细分详情

A/B 测试各版本按维度分组的指标对比。

#### 请求参数说明

| 参数                    | 是否必填 | 类型      | 说明                                                                                                                      |
| --------------------- | ---- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `profileId`           | 是    | string  | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9` |
| `id`                  | 是    | string  | 体验 ID（来自 list 接口）                                                                                                       |
| `startDate`           | 是    | string  | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |
| `endDate`             | 是    | string  | 结束日期,格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |
| `compareBy`           | 是    | string  | 版本对比基准指标（同 3.6）                                                                                                         |
| `goalId`              | 条件必填 | string  | `compareBy` 为 `goalReached` 时必填                                                                                         |
| `dimension`           | 是    | string  | 主维度（同 3.5）                                                                                                              |
| `subDimension`        | 否    | string  | 二级维度                                                                                                                    |
| `property`            | 条件必填 | object  | `dimension` 为 `userProperty` 时必填                                                                                        |
| `showDeletedVersions` | 否    | boolean | 是否包含已删除版本，默认 false                                                                                                      |
| `lang`                | 否    | string  | 返回 label/description 的语言：`EN`（默认）、`ZH`、`JP`                                                                             |

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/abtest/insight \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "compareBy": "goalReached",
    "goalId": "6a8bedde-...",
    "dimension": "terminalType",
    "lang": "ZH"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "春季促销弹窗",
        "items": [
            {
                "name": "PC",
                "versions": [
                    {
                        "name": "全部版本",
                        "viewedUsers": { "value": 40, "label": "展示用户数", "description": "..." },
                        "uplift": { "value": "Baseline", "label": "提升", "description": "..." }
                    },
                    {
                        "name": "Control",
                        "viewedUsers": { "value": 20, "label": "展示用户数", "description": "..." },
                        "uplift": { "value": "Baseline", "label": "提升", "description": "..." }
                    },
                    {
                        "name": "Pattern 1",
                        "viewedUsers": { "value": 20, "label": "展示用户数", "description": "..." },
                        "uplift": { "value": "+30.00%", "label": "提升", "description": "..." }
                    }
                ]
            }
        ]
    }
}
```

***

### 3.8 表单提交

查询指定版本的表单提交明细数据。

#### 请求参数说明

| 参数          | 是否必填 | 类型     | 说明                                                                                                                      |
| ----------- | ---- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `profileId` | 是    | string | 网站 ID（8 位字符串），必须与 API Key 关联的档案匹配。可从 Ptengine 产品 URL 中获取，如 `https://www.ptengine.jp/app/{profileId}/home` 中的 `566d12f9` |
| `id`        | 是    | string | 体验 ID（来自 list 接口）                                                                                                       |
| `versionId` | 是    | string | 版本 ID（来自 list 接口的 versions）                                                                                             |
| `startDate` | 是    | string | 开始日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |
| `endDate`   | 是    | string | 结束日期，格式：`YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                     |

**请求示例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/form \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "versionId": "a2696719-6375-456b-8dbc-7e3d273beb6d",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
  }'
```

**响应示例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "columns": ["submittedAt", "Email", "Picture choice", "choice-test2"],
        "rows": [
            {
                "submittedAt": "2026/04/09 19:14:33",
                "Email": "test@example.com",
                "Picture choice": "Option 3",
                "choice-test2": ""
            },
            {
                "submittedAt": "2026/04/08 17:40:05",
                "Email": "user@example.com",
                "Picture choice": "",
                "choice-test2": "Option 1,Option 2"
            }
        ]
    }
}
```

> * `columns` 为动态表头，根据表单实际字段自动生成
> * `rows` 每条为一次表单提交，没有值的字段为空字符串

***

### 3.9 可用指标

#### 基础指标（所有类型均支持）

| 字段                 | 格式                     | 说明      |
| ------------------ | ---------------------- | ------- |
| `viewedUsers`      | 数值                     | 展示用户数   |
| `views`            | 数值                     | 展示次数    |
| `avgVisitDuration` | 时长（`MM:SS`/`HH:MM:SS`） | 平均访问时长  |
| `avgPagesPerVisit` | 小数（`"2.50"`）           | 平均访问页面数 |
| `bounceRate`       | 百分比（`"42.86%"`）        | 跳出率     |

#### 弹窗类指标（仅 POPUP / STICKY\_BAR / REDIRECT / ADVANCED 有弹窗时）

| 字段             | 格式  | 说明    |
| -------------- | --- | ----- |
| `clickedUsers` | 数值  | 点击用户数 |
| `clickRate`    | 百分比 | 点击率   |
| `closedUsers`  | 数值  | 关闭用户数 |
| `closeRate`    | 百分比 | 关闭率   |

#### 表单类指标（仅配置了表单的体验）

| 字段                   | 格式  | 说明      |
| -------------------- | --- | ------- |
| `formSubmittedUsers` | 数值  | 表单提交用户数 |
| `formSubmitRate`     | 百分比 | 表单提交率   |

#### 目标数据

| 字段                     | 说明                  |
| ---------------------- | ------------------- |
| `goals[].name`         | 目标名称                |
| `goals[].reachedUsers` | 达成用户数               |
| `goals[].reachRate`    | 达成率                 |
| `goals[].value`        | 达成价值（null = 按用户数统计） |

***

## 附录

### A. 错误码

| 错误码    | HTTP 状态码 | 说明                                                                                                                     |
| ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| `4010` | 401      | 请求头缺少 `x-api-key`                                                                                                      |
| `4011` | 401      | API Key 无效                                                                                                             |
| `4030` | 403      | `profileId` 与 API Key 关联的档案不匹配                                                                                         |
| `4031` | 403      | API Key 缺少查询权限，需要 scope: `query`                                                                                       |
| `4001` | 400      | 无效的 `queryType`                                                                                                        |
| `4002` | 400      | 日期格式错误，需为 `YYYY-MM-DD` 或 `YYYY/MM/DD`                                                                                  |
| `4003` | 400      | 查询日期超出套餐数据存储期限                                                                                                         |
| `4006` | 400      | `page_insight` 类型必须传 `funName`                                                                                         |
| `4007` | 400      | `block_metrics` 需要指定设备类型（PC/MOBILE/TABLET），不支持 ALL                                                                     |
| `4008` | 400      | 页面区块未配置，请先在产品中扫描页面                                                                                                     |
| `4009` | 400      | `element_metrics` 需要指定设备类型（PC/MOBILE/TABLET），不支持 ALL                                                                   |
| `4012` | 400      | 未找到匹配的转化目标                                                                                                             |
| `4013` | 400      | 缺少必填字段（响应消息会指出具体字段名）                                                                                                   |
| `4014` | 400      | `deviceType` 无效，必须是 `ALL`、`PC`、`MOBILE`、`TABLET` 之一                                                                    |
| `4015` | 400      | `dimension` / `subDimension` 无效（响应消息会指出具体原因）                                                                           |
| `4016` | 400      | 页面元素未配置，请先在产品中扫描页面                                                                                                     |
| `4017` | 400      | `compareBy` 无效（响应消息会列出允许值）                                                                                             |
| `4018` | 400      | 字段非法（`/event/query` / `/insight/query` / `/conversion/query`：维度 / 指标 / queryType / topic / granularity 不在允许列表，或维度数量超限） |
| `4019` | 400      | 过滤算子或值非法（必须是 `include`/`exclude`；`value` 必须是非空数组；sortOrder/limit 越界）                                                   |
| `4040` | 404      | 未找到对应的体验（`id` 在该 profile 下不存在）                                                                                         |
| `4290` | 429      | 请求频率超限（每分钟）                                                                                                            |
| `4291` | 429      | 请求频率超限（每天）                                                                                                             |
| `5000` | 500      | 服务器内部错误                                                                                                                |

`message` 会根据请求的 `lang`（body 或 query）返回对应语言（EN/ZH/JP）；未传或非法值时回退到英文。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://helps.ptengine.com/cn/developer/open-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.