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

---

2. 热图数据查询

2.1 查询热图数据

POST /open-api/v1/heatmap/query

统一查询端点。通过 queryType 参数选择查询类型。

请求体

{
    "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", "clickRate"],
    "conversionNames": [],
    "filters": [],
    "lang": "ZH"
}

请求参数说明

参数	是否必填	类型	说明
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	设备类型筛选，详见 2.4 节
rangeType	否	string	URL 匹配模式。MERGE_URL（默认）合并参数查询，忽略 URL 参数差异；URL 原始 URL 精确查询
metrics	否	string[]	不传返回所有指标，传了只返回指定指标。可用指标见 2.3 节
conversionNames	否	string[]	转化目标名称列表（模糊匹配），例如：["购买完成", "注册"]
filters	否	object[]	筛选条件，每项包含 name（筛选类型）、op（include/exclude）、value（值数组）。详见下方筛选类型表
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（日）

筛选条件（filters）

每个筛选条件的格式：{ "name": "筛选类型", "op": "include 或 exclude", "value": ["值1", "值2"] }

支持的筛选类型：

固定值（无需调用 filter-values 接口查询）：

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-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"]
conversionName	转化名称	["ptmind"]
eventName	事件名称	["checkout_completed", "product_viewed"]
customDimension	自定义维度	需配合 eventVariant 使用，见下方说明
eventVariable	自定义维度（事件名）	需配合 eventName 和 eventVariant 使用，见下方说明

示例： 查询来自搜索引擎的 PC 用户数据

"filters": [
    { "name": "deviceType", "op": "include", "value": ["PC"] },
    { "name": "sourceType", "op": "include", "value": ["Search"] }
]

---

查询筛选可用值

如不确定某个动态筛选类型有哪些可用值，可通过以下接口查询：

POST /open-api/v1/heatmap/filter-values

请求体：

{
    "profileId": "566d12f9",
    "name": "os",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "search": ""
}

参数	是否必填	说明
profileId	是	网站 ID
name	是	筛选类型（如 country、browser、sourceType 等）
startDate	否	开始日期，格式：YYYY-MM-DD 或 YYYY/MM/DD，不传默认最近 30 天
endDate	否	结束日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
search	否	模糊搜索关键词

示例：

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

返回：

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "os",
        "values": ["Linux", "Mac OS X", "Windows", "iOS"]
    }
}

---

自定义维度筛选

自定义维度需要通过两步操作来使用：

第1步：查询自定义维度列表

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

返回：

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "customDimension",
        "values": ["price", "sku", "currencycode"]
    }
}

第2步：查询某个维度的可用值

curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "customDimension",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "eventVariant": "price"
  }'

返回：

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "customDimension",
        "eventVariant": "price",
        "values": ["18900", "21900"]
    }
}

在查询中使用筛选：

"filters": [
    {
        "name": "customDimension",
        "eventVariant": "price",
        "op": "include",
        "value": ["18900", "21900"]
    }
]

---

自定义维度（事件名）筛选

自定义维度需要通过三步操作来使用：

第1步：查询事件自定义维度列表

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

返回：

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventVariable",
        "values": [
            { "eventName": "product_viewed", "eventVariant": "price" },
            { "eventName": "product_viewed", "eventVariant": "currencycode" }
        ]
    }
}

第2步：查询某个维度的可用值

curl -X POST https://xbackend.ptengine.com/open-api/v1/heatmap/filter-values \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "name": "eventVariable",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "eventName": "product_viewed",
    "eventVariant": "price"
  }'

返回：

{
    "code": 200,
    "message": "OK",
    "data": {
        "filterName": "eventVariable",
        "eventName": "product_viewed",
        "eventVariant": "price",
        "values": ["18900", "21900"]
    }
}

第3步：在查询中使用筛选

"filters": [
    {
        "name": "eventVariable",
        "eventName": "product_viewed",
        "eventVariant": "price",
        "op": "include",
        "value": ["18900"]
    }
]

---

2.2 查询类型

2.2.1 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。

---

2.2.2 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": []
            }
        ]
    }
}

---

2.2.3 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": []
            }
        ]
    }
}

---

2.2.4 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": []
            }
        ]
    }
}

---

2.3 可用指标

2.3.1 页面指标（用于 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 传入转化目标的名称。

---

2.3.2 区块指标（用于 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

---

2.3.3 元素指标（用于 element_metrics）

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

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

---

2.4 设备类型规则

查询类型	支持的 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

---

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

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

1. 在 Ptengine 热图中打开目标页面

2. 开启区块/元素检测功能

3. 保存配置

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

---

2.6 完整请求示例

示例 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：查询移动端区块分析

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

---

2.7 补充说明

• 时间类字段（如页面 timeOnPage、区块 avgDuration）以可读字符串返回，带单位（例如 "5s"、"1m 30s"）。

• 比率类型的值为小数（例如 bounceRate: 0.45 表示 45%）。

• conversionNames 支持模糊匹配，传入部分名称也可以匹配到对应的转化目标。

• API 使用的数据源与 Ptengine 产品界面一致，查询结果应保持一致。

• 请求的 URL 在该档案下从未被采集时，接口返回 200，但所有指标值为 0，不返回错误。

---

3. Experience 数据查询

3.1 获取体验列表

POST /open-api/v1/experience/list

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

请求体：

{
    "profileId": "566d12f9"
}

参数	必填	说明
profileId	是	网站 ID

返回示例：

{
    "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 获取用户属性列表

POST /open-api/v1/experience/user-properties

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

请求体：

{
    "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 体验概览指标

POST /open-api/v1/experience/report/overview

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

请求体：

{
    "profileId": "566d12f9",
    "experiences": [
        { "id": "6c3bad4b-...", "name": "春季促销弹窗" },
        { "id": "5bb77b97-...", "name": "注册引导" }
    ],
    "metrics": ["viewedUsers", "clickRate", "bounceRate"],
    "lang": "ZH"
}

参数	必填	说明
profileId	是	网站 ID
experiences	是	体验列表（id + name，来自 list 接口）
metrics	否	要返回的指标字段。不传返回全部默认指标。支持的字段见下方指标表
lang	否	返回语言：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

返回示例：

{
    "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 关键指标

POST /open-api/v1/experience/report/metrics

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

请求体：

{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "lang": "ZH"
}

参数	必填	说明
profileId	是	网站 ID
id	是	体验 ID
startDate	是	开始日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
endDate	是	结束日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
lang	否	返回语言

返回示例：

{
    "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 细分详情

POST /open-api/v1/experience/report/insight

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

请求体：

{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "dimension": "terminalType",
    "subDimension": "visitType",
    "lang": "ZH"
}

参数	必填	说明
profileId	是	网站 ID
id	是	体验 ID
startDate	是	开始日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
endDate	是	结束日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
dimension	是	主维度，详见下方维度表
subDimension	否	二级维度
property	条件必填	dimension 为 userProperty 时必填，从 user-properties 接口获取
lang	否	返回语言

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": { "name": "plan_name", "source": ["code"], "type": "STRING" }
}

返回示例：

{
    "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 测试的结果

POST /open-api/v1/experience/report/abtest/metrics

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

请求体：

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

参数	必填	说明
profileId	是	网站 ID
id	是	体验 ID
startDate	是	开始日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
endDate	是	结束日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
compareBy	是	版本对比基准指标，详见下方
goalId	条件必填	compareBy 为 goalReached 时必填（从 list 接口的 goals 获取）
showDeletedVersions	否	是否包含已删除版本，默认 false
lang	否	返回语言

compareBy 可选值：

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

返回示例：

{
    "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 测试的结果 — 细分详情

POST /open-api/v1/experience/report/abtest/insight

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

请求体：

{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31",
    "compareBy": "goalReached",
    "goalId": "6a8bedde-...",
    "dimension": "terminalType",
    "lang": "ZH"
}

参数	必填	说明
profileId	是	网站 ID
id	是	体验 ID
startDate	是	开始日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
endDate	是	结束日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
compareBy	是	版本对比基准指标（同 3.6）
goalId	条件必填	compareBy 为 goalReached 时必填
dimension	是	主维度（同 3.5）
subDimension	否	二级维度
property	条件必填	dimension 为 userProperty 时必填
showDeletedVersions	否	是否包含已删除版本，默认 false
lang	否	返回语言

返回示例：

{
    "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 表单提交

POST /open-api/v1/experience/report/form

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

请求体：

{
    "profileId": "566d12f9",
    "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
    "versionId": "a2696719-6375-456b-8dbc-7e3d273beb6d",
    "startDate": "2026-03-01",
    "endDate": "2026-03-31"
}

参数	必填	说明
profileId	是	网站 ID
id	是	体验 ID
versionId	是	版本 ID（从 list 接口的 versions 获取）
startDate	是	开始日期，格式：YYYY-MM-DD 或 YYYY/MM/DD
endDate	是	结束日期，格式：YYYY-MM-DD 或 YYYY/MM/DD

返回示例：

{
    "code": 200,
    "message": "OK",
    "data": {
        "columns": ["submittedAt", "Email", "Picture choice", "choice-test2"],
        "rows": [
            {
                "submittedAt": "2026/04/09 19:14:33",
                "Email": "[email protected]",
                "Picture choice": "Option 3",
                "choice-test2": ""
            },
            {
                "submittedAt": "2026/04/08 17:40:05",
                "Email": "[email protected]",
                "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 = 按用户数统计）

---

4. 事件数据查询

自定义事件分析。维度/指标对齐 Ptengine 产品中的 事件 > 分群（/event/segment） 页面。

4.1 查询事件数据

POST /open-api/v1/event/query

通过任意维度 + 指标 + 过滤条件 + 自定义事件属性过滤进行事件查询。

请求体：

字段	必填	类型	说明
profileId	是	string	档案（站点）ID
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）——与产品 /event/segment 页面一致。每项是字符串（标准维度名）或对象 { name: "eventVariable", eventVariant: "<属性名>" }（自定义事件属性）
metrics	否	string[]	指标字段名，默认 ["eventCount"]；可选值：eventCount、sessions
filters	否	object[]	过滤条件，形态与 /heatmap/query 完全一致：{ name, op, value, eventName?, eventVariant? }

算子： include / exclude（与 /heatmap/query 同）。value 必须是非空数组（例：["Japan"]、["Japan", "China"]）。

自定义事件属性：

• dimensions 里：{ name: "eventVariable", eventVariant: "<属性名>" }

• filters 里：{ name: "eventVariable", eventName: "<事件名>", eventVariant: "<属性名>", op, value } —— 与 /heatmap/query 的 eventVariable filter 形态一致。

• 用 eventVariable filter 时，还要再加一条 { name: "eventName", op: "include", value: ["<事件名>"] }（与产品 /event/segment 页面一致）。

响应里的列名就是属性名本身。

示例：

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "day", "country"],
    "metrics": ["eventCount", "sessions"],
    "filters": [
        { "name": "eventName",       "op": "include", "value": ["click_buy"] },
        { "name": "country",         "op": "include", "value": ["Japan", "China"] },
        { "name": "visitType",       "op": "include", "value": ["New visits"] },
        { "name": "deviceType",      "op": "include", "value": ["PC", "Mobile"] },
        { "name": "eventVariable",   "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": "click_buy", "day": "2026-04-15", "country": "Japan", "eventCount": 320, "sessions": 250 }
        ]
    }
}

4.2 更多示例

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

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName"]
}

b) 时间序列 — 按天统计

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "day"],
    "metrics": ["eventCount", "sessions"]
}

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

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "conversionName"],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName",      "op": "include", "value": ["click_buy"] },
        { "name": "conversionName", "op": "include", "value": ["ptmind"] }
    ]
}

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

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

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": [
        "eventName",
        { "name": "eventVariable", "eventVariant": "position" }
    ],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName",     "op": "include", "value": ["gallery_item_impression"] },
        { "name": "eventVariable", "eventName": "gallery_item_impression", "eventVariant": "position",
          "op": "include", "value": ["home"] }
    ]
}

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

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

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "sourceType", "utmSource"],
    "metrics": ["eventCount", "sessions"],
    "filters": [
        { "name": "eventName",  "op": "include", "value": ["click_buy"] },
        { "name": "sourceType", "op": "include", "value": ["Search", "Campaign"] }
    ]
}

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

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName", "country"],
    "metrics": ["eventCount"],
    "filters": [
        { "name": "eventName",  "op": "include", "value": ["click_buy"] },
        { "name": "visitType",  "op": "include", "value": ["New visits"] },
        { "name": "deviceType", "op": "include", "value": ["PC"] },
        { "name": "country",    "op": "include", "value": ["Japan", "China"] }
    ]
}

g) 排除直接跳出会话

{
    "profileId": "566d12f9",
    "startDate": "2026-04-01",
    "endDate": "2026-04-30",
    "dimensions": ["eventName"],
    "metrics": ["eventCount", "sessions"],
    "filters": [
        { "name": "exitType", "op": "exclude", "value": ["Bounce visits"] }
    ]
}

4.3 获取可用字段

GET /open-api/v1/event/fields?lang=ZH

返回支持的指标、维度、算子（含多语言文案）。

4.4 可用指标

字段	说明	dataType
eventCount	事件触发次数	INTEGER
sessions	触发该事件的访问数	INTEGER

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

字段名与 /heatmap/query 的 filter 字段同一套命名。

类别	字段	说明
event	eventName	事件名
visit	visitType	New visits / Returning visits
visit	exitType	Bounce visits / Non-bounce visits
page	originalPages	进入页（完整 URL）
page	combinedPages	进入页（去 query）
conversion	conversionName	转化目标名
time	day	日期 YYYY-MM-DD
time	hour	小时（0–23）
time	week	ISO 周
time	month	年月 YYYY-MM
source	sourceType	Direct / Search / Social / Referral / Campaign / AISearch
source	campaignUrl	广告着陆 URL
source	referralSource / referralUrl	推荐来源域名 / 完整 URL
source	searchEngine	搜索引擎
source	socialNetwork / socialUrl	社交网络 / URL
source	aiName	AI 搜索引擎
ad	utmCampaign / utmSource / utmMedium / utmTerm / utmContent	UTM 字段
terminal	deviceType	PC / Mobile / Tablet
terminal	deviceBrand	设备品牌
terminal	os / osVersion / browser / browserVersion	系统 / 浏览器 + 版本
terminal	screenResolution	屏幕分辨率
geography	country / region	国家 / 省州

4.6 可用过滤字段（用于 filters[]）

字段名和值与 /heatmap/query 完全一致。与上面分组维度的差异：

• 不包含时间字段（已有 startDate/endDate）

• conversionName 走名称模糊匹配（服务端转化为目标 ID 后查询）

• 多 eventVariable（自定义事件属性）

固定枚举值字段（必须从下面列表里选）：

字段	允许值
visitType	New visits、Returning visits
exitType	Bounce visits、Non-bounce visits
deviceType	PC、Mobile、Tablet
sourceType	Direct、Search、Social、Referral、Campaign、AISearch

完整过滤字段表：

类别	字段	说明
visit	visitType / exitType	见枚举表
visit	originalPages / combinedPages	进入页（完整 URL / 去 query）
source	sourceType	见枚举表
source	campaignUrl	广告着陆 URL
source	referralSource / referralUrl	推荐来源域名 / 完整 URL
source	searchEngine	搜索引擎
source	socialNetwork / socialUrl	社交网络 / URL
source	aiName	AI 搜索引擎
terminal	deviceType / deviceBrand	见枚举表 / 设备品牌
terminal	os / osVersion / browser / browserVersion	系统 / 浏览器 + 版本
terminal	screenResolution	分辨率
geography	country / region	国家 / 省州
conversion	conversionName	转化目标名（模糊匹配，例如 ["ptmind"] 匹配所有名称含 "ptmind" 的目标）
campaign	utmCampaign / utmSource / utmMedium / utmTerm / utmContent	UTM 字段
event	eventName	事件名
custom	eventVariable	{ name: "eventVariable", eventName: "<事件名>", eventVariant: "<属性名>" } —— 与 /heatmap/query filter 形态完全一致

4.7 自定义事件属性

Ptengine SDK 在上报事件时可以附带自定义事件属性。Open API 在 dimensions 和 filters 里形态略有不同：

• dimensions 里：{ "name": "eventVariable", "eventVariant": "<属性名>" }

• filters 里：{ "name": "eventVariable", "eventName": "<事件名>", "eventVariant": "<属性名>", "op": "include"|"exclude", "value": [...] } —— 与 /heatmap/query 的 eventVariable filter 形态一致。

• 用 eventVariable filter 时，再加一条 { "name": "eventName", "op": "include", "value": ["<事件名>"] }，缺失返回 4018。

响应里的列名就是属性名本身（如 "price"）。

{
    "dimensions": [
        "eventName",
        { "name": "eventVariable", "eventVariant": "price" }
    ],
    "filters": [
        { "name": "eventName",     "op": "include", "value": ["purchase"] },
        { "name": "eventVariable", "eventName": "purchase", "eventVariant": "category", "op": "include", "value": ["shoes"] }
    ]
}

4.8 注意事项

• visitType / exitType / deviceType / sourceType 只接受 §4.6 列出的固定枚举值，按表里写的原样传。

• dimensions 必传，且必须包含字符串 "eventName"（与产品 /event/segment 页面行为一致，事件查询必须按事件名分组）。可以在它旁边再加其它维度 / eventVariable 对象。

• 维度数量限制：最多 3 个非时间维度 + 至多 1 个时间维度（day / hour / week / month）。超过任一上限返回 4018。与产品 /event/segment 页一致。

• 何时必须传 eventName filter：满足以下任一情况：

  • dimensions 含 eventName / 时间维度之外的字段（如 country、sourceType）

  • dimensions 含 eventVariable 对象

  • filters 含 eventVariable 项

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

• columns 顺序由后端返回顺序决定，不一定与请求顺序一致。

---

附录

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：维度或指标不在允许列表）
4019	400	过滤算子无效（/event/query：必须是 include 或 exclude）
4040	404	未找到对应的体验（id 在该 profile 下不存在）
4290	429	请求频率超限（每分钟）
4291	429	请求频率超限（每天）
5000	500	服务器内部错误

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

错误响应格式：

{
    "code": 4007,
    "message": "block_metrics requires specific deviceType (PC/MOBILE/TABLET), ALL is not supported"
}