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 里配置过的所有目标名，拿到后填进查询请求即可。

请求示例：

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"
  }'

响应示例：

{
    "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 端、只看日本地区、只看某广告活动来源。

{ "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 可选值接口实时查询。

类别	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（进阶）

只在你的事件带了自定义属性（比如 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 等）

请求示例：

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"
  }'

响应示例：

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

示例 2：模糊搜索（search）

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

请求示例：

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"
  }'

响应示例：

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

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

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

请求示例：

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"
  }'

响应示例：

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

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

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

请求示例：

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"
  }'

响应示例：

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

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

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

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

请求示例：

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"
  }'

响应示例：

{
    "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 查取值：

请求示例：

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"
  }'

响应示例：

{
    "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，从 页面组列表 获取）
historyHeatmap	否	string	历史热图快照 ID。指定后查询将基于该次保存的热图配置；不传则用最新配置。对 block_metrics / element_metrics：影响全部区块/元素指标；对 page_metrics / page_insight：仅影响 CTA 类指标（ctaClicks / ctaClickRate），PV/UV/访问/跳出等流量指标不受影响。ID 通过 历史热图快照列表 接口获取
pageGroupId	否	string	页面组 ID。rangeType=PAGE_GROUP 时必填；从 页面组列表 接口获取。此时 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
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 传入转化名称即可。

请求示例：

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"
  }'

响应示例：

{
    "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	按天分组

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

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"
  }'

响应示例：

{
    "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 秒。

请求示例：

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"
  }'

响应示例：

{
    "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

请求示例：

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"
  }'

响应示例：

{
    "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 见 历史热图快照列表）

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，页面组见 页面组列表，url 传页面组 defaultUrl）

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）

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：查询页面流量概览

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：按设备类型查询页面详情指标

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 筛选日本地区）

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：查询指定转化目标数据

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 端元素点击分析

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 字段传入，用于查询某次冻结配置对应的指标。

请求示例：

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 时必填

响应示例：

{
    "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。

请求示例：

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 关联档案匹配

响应示例：

{
    "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

自定义事件属性

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

• 按属性分组 —— 在 dimensions 里加：

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

  结果会按 price 值聚合。

• 按属性细分 —— 在 filters 里加：

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

  只看 purchase 事件下 price=100 的会话。

• 细分时务必同时锁定事件 —— 用属性细分时，filters 里还要再加一条事件名细分，否则查询不知道锁哪个事件：

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

请求示例：

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"]
      }
    ]
  }'

响应示例：

{
    "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) 最简 — 按事件名统计触发次数

请求示例：

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) 时间序列 — 按天统计

请求示例：

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) 按转化目标过滤（名称模糊匹配）

请求示例：

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) 自定义事件属性 — 分组 + 过滤

请求示例：

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 + 来源类型

请求示例：

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 + 日本/中国

请求示例：

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) 排除直接跳出会话

请求示例：

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 切换）。

请求示例：

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

响应示例（节选）：

{
    "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
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" — 指标总览

请求示例：

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"
  }'

响应示例：

{
    "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" — 流量来源

请求示例：

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"
  }'

响应示例：

{
    "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" — 地理分布

请求示例：

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"
  }'

响应示例：

{
    "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" — 设备分布

请求示例：

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"
  }'

响应示例：

{
    "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 —— 见 可用维度。

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

请求示例：

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"
  }'

响应示例：

{
    "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 时返回所有转化集合的指标。

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"
  }'

响应示例：

{
    "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 等）仅按命中的转化目标计算。

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"
  }'

响应示例：

{
    "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，可选值见 可用指标；granularity，可选值：hour / day / week / month。响应中 time 字段格式 YYYY-MM-DD（hour 粒度时为 YYYY-MM-DDTHH）。

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

请求示例：

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"] }]
  }'

响应示例：

{
    "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
lang	否	string	返回 label/description 的语言：EN（默认）、ZH、JP。当前仅 queryType = "metrics" 响应使用。传入非合法值降级为 EN

查询类型

metrics — 转化指标

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

请求示例：

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"] }]
  }'

响应示例：

{
    "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。

请求示例：

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"
  }'

响应示例：

{
    "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 — 按来源分布

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

请求示例：

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"
  }'

响应示例：

{
    "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）分组查看转化数据。

请求示例：

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"
  }'

响应示例：

{
    "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）分组查看转化数据。

请求示例：

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"
  }'

响应示例：

{
    "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 — 漏斗

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

请求示例：

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"
  }'

响应示例：

{
    "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）转化目标各自的指标，每行一个目标。

请求示例：

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"
  }'

响应示例：

{
    "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

请求示例：

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"
  }'

响应示例：

{
    "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 参数。

请求示例：

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"
  }'

响应示例：

{
    "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

请求示例：

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"
  }'

响应示例：

{
    "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

请求示例：

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"
  }'

响应示例：

{
    "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：

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

请求示例：

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"
  }'

响应示例：

{
    "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	展示过体验的访问跳出率

请求示例：

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"
  }'

响应示例：

{
    "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

请求示例：

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"
  }'

响应示例：

{
    "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

请求示例：

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"
  }'

响应示例：

{
    "code": 200,
    "message": "OK",
    "data": {
        "columns": ["submittedAt", "Email", "Picture choice", "choice-test2"],
        "rows": [
            {
                "submittedAt": "2026/04/09 19:14:33",
                "Email": "[e-mail]",
                "Picture choice": "Option 3",
                "choice-test2": ""
            },
            {
                "submittedAt": "2026/04/08 17:40:05",
                "Email": "[e-mail]",
                "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）；未传或非法值时回退到英文。