> For the complete documentation index, see [llms.txt](https://helps.ptengine.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://helps.ptengine.com/cn/developer/open-api.md). # 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 精确查询；`PAGE_GROUP` 页面组维度（需配 `pageGroupId`，从 [页面组列表](#page-groups) 获取） | | `historyHeatmap` | 否 | string | 历史热图快照 ID。指定后查询将基于该次保存的热图配置；不传则用最新配置。对 `block_metrics` / `element_metrics`：影响全部区块/元素指标；对 `page_metrics` / `page_insight`：仅影响 CTA 类指标（`ctaClicks` / `ctaClickRate`），PV/UV/访问/跳出等流量指标不受影响。ID 通过 [历史热图快照列表](#heatmap-snapshots) 接口获取 | | `pageGroupId` | 否 | string | 页面组 ID。`rangeType=PAGE_GROUP` 时必填；从 [页面组列表](#page-groups) 接口获取。此时 `url` 传页面组底图 URL（页面组列表返回的 `defaultUrl`） | | `engageConfig` | 否 | object | 按实验（A/B 测试）版本过滤热图流量。`{ engageId, versionId, isControlGroup? }`：`engageId` 与 `versionId` 从 `POST /v1/experience/list` 的 `id` / `versions[].id` 获取；`isControlGroup` 可不传。不传 `engageConfig` 则统计全量流量 | | `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": [] } ] } } ``` #### 进阶查询示例 以下示例展示 `historyHeatmap`、`PAGE_GROUP`、`engageConfig` 三个可选字段的用法（可与任意 `queryType` 组合）。 **示例 1 — 历史热图快照指标**（`historyHeatmap`，快照 ID 见 [历史热图快照列表](#heatmap-snapshots)） ```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", "historyHeatmap": "1779886104229", "metrics": ["impression", "clickRate"] }' ``` **示例 2 — 按页面组查询**（`rangeType=PAGE_GROUP` + `pageGroupId`，页面组见 [页面组列表](#page-groups)，`url` 传页面组 `defaultUrl`） ```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", "rangeType": "PAGE_GROUP", "pageGroupId": "1753350824020", "url": "https://www.example.com/products", "startDate": "2026-03-01", "endDate": "2026-03-31", "deviceType": "ALL", "metrics": ["pv", "uv", "visits"] }' ``` **示例 3 — 按实验版本查询**（`engageConfig`，`engageId` / `versionId` 见 `POST /open-api/v1/experience/list`） ```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", "engageConfig": { "engageId": "abc123", "versionId": "abc123_v1", "isControlGroup": false }, "metrics": ["pv", "uv", "conversionRate"], "conversionNames": ["购买完成"] }' ``` #### 可用指标 **页面指标（用于 `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`，不返回错误。 #### 历史热图快照列表 列出指定 `profileId + url` 下所有可用的历史热图快照（已成功保存的，含手动保存与自动定时保存）。返回的 `id` 可作为 heatmap query 请求中的 `historyHeatmap` 字段传入，用于查询某次冻结配置对应的指标。 **请求示例：** ```bash curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/snapshots \ -H "Content-Type: application/json" \ -H "x-api-key: pt-your-api-key" \ -d '{ "profileId": "566d12f9", "url": "https://ptengine.jp", "rangeType": "MERGE_URL" }' ``` **请求参数：** | 参数 | 是否必填 | 类型 | 说明 | | ------------- | ---- | ------ | ----------------------------------------------------------- | | `profileId` | 是 | string | 网站 ID，必须与 API Key 关联档案匹配 | | `url` | 条件必填 | string | 非 `PAGE_GROUP` 时必填（`PAGE_GROUP` 按 `pageGroupId` 查，无需 `url`） | | `rangeType` | 否 | string | `URL` / `MERGE_URL`（默认）/ `PAGE_GROUP` | | `pageGroupId` | 条件必填 | string | 仅 `rangeType=PAGE_GROUP` 时必填 | **响应示例：** ```json { "code": 200, "data": { "snapshots": [ { "id": "1779886104229", "name": "v1.2 发布前快照", "note": "AB 测试基线", "createTime": 1779886104229 } ] } } ``` **字段说明：** | 字段 | 含义 | | ------------ | --------------------------------------------- | | `id` | 快照 ID（传给 heatmap query `historyHeatmap` 字段使用） | | `name` | 快照名称 | | `note` | 备注 | | `createTime` | 创建时间（毫秒时间戳） | *** #### 页面组列表 列出指定 `profileId` 下的全部页面组（heatmap / insight 共用）。返回的 `id`（页面组 ID）在按页面组查询时使用：heatmap query 传 `rangeType=PAGE_GROUP` + `pageGroupId`，历史热图快照传 `rangeType=PAGE_GROUP` + `pageGroupId`。 **请求示例：** ```bash curl -X POST https://xbackend.ptengine.com/open-api/v1/page-groups \ -H "Content-Type: application/json" \ -H "x-api-key: pt-your-api-key" \ -d '{ "profileId": "566d12f9" }' ``` **请求参数：** | 参数 | 是否必填 | 类型 | 说明 | | ----------- | ---- | ------ | ------------------------ | | `profileId` | 是 | string | 网站 ID，必须与 API Key 关联档案匹配 | **响应示例：** ```json { "code": 200, "data": { "pageGroups": [ { "id": "1753350824020", "name": "商品详情页组", "defaultUrl": "https://www.example.com/products" } ] } } ``` **字段说明：** | 字段 | 含义 | | ------------ | --------------------------------------------- | | `id` | 页面组 ID（按 `PAGE_GROUP` 查询时作为 `pageGroupId` 传入） | | `name` | 页面组名称 | | `defaultUrl` | 页面组默认底图 URL（按 `PAGE_GROUP` 查热图时作为 `url` 传入） | *** ### 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）；未传或非法值时回退到英文。