Open API ドキュメント

1. 共通事項

1.1 概要

Ptengine Open API は RESTful インターフェースを提供し、ヒートマップ分析データをプログラム的にクエリできます。本ドキュメントを AI Agent に提供すると、AI Agent が自然言語の要件に基づいてクエリリクエストを自動構築し、インターフェースを直接呼び出してデータを取得します。

インターフェースベース URL：

https://xbackend.ptengine.com/

1.2 認証方式

すべての API リクエストは x-api-key リクエストヘッダーで API Key を渡す必要があります。

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

API Key の取得手順：

権限要件：API Key の作成と管理は Admin および Owner ロールのみが可能です。

Ptengine にログイン
Experience モジュールに移動
右上の設定アイコン（⚙）をクリックし、「外部アプリ連携」を選択
「API キー」タブに切り替え
「API キーを作成」をクリックし、名前を入力して権限範囲（データアップロード/データクエリ）を選択
キーをコピーして安全に保管してください（キーは作成時にのみ表示されます）

1.3 リクエスト頻度制限

プランにより制限値が異なります：

プラン

RPM（毎分）

RPD（毎日）

Free

100

Free Trial

1,000

Growth

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": "JP"
}

リクエストパラメータ

パラメータ

必須

型

説明

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

OSバージョン

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

カスタムディメンションフィルター

カスタムディメンションは2つのステップで使用します：

ステップ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"]
    }
]

カスタムディメンション（イベント名）フィルター

カスタムディメンションは3つのステップで使用します：

ステップ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": "JP"
  }'

レスポンス例：

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

説明： 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": "JP"
  }'

レスポンス例：

{
    "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` — ブロック指標

ページ内の各ブロック（セクション）の指標データとスクリーンショットURLを返します。ページが製品内でスキャンされ、ブロックが設定されている必要があります。

デバイスタイプ： 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": "JP"
  }'

レスポンス例：

{
    "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": "JP"
  }'

レスポンス例：

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

1PVあたりのクリック数。ユーザーのページに対するインタラクション度を評価できます

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

ブロックスクリーンショットURL

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 製品内でページのスキャン設定を完了する必要があります：

Ptengine ヒートマップで対象ページを開く
ブロック/エレメント検出機能を有効にする
設定を保存する

ページが設定されていない場合、インターフェースはエラーコード 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": "JP"
  }'

例 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": "JP"
  }'

例 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": "JP"
  }'

例 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": "JP"
  }'

例 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": "JP"
  }'

2.7 補足事項

時間関連のフィールド（ページの timeOnPage、ブロックの avgDuration など）は単位付きの可読文字列で返されます（例："5s"、"1m 30s"）。
比率タイプの値は小数（例：bounceRate: 0.45 は 45% を表します）です。
conversionNames はあいまい一致をサポートしており、部分的な名前でも対応するコンバージョン目標にマッチできます。
API が使用するデータソースは Ptengine 製品のインターフェースと同一であり、クエリ結果は一致するはずです。
リクエストされた URL が該当プロファイルで未収集の場合、API は 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": "JP"
}

パラメータ

必須

説明

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

フォーム回答UU/表示ユーザー数

rate

goalReachedUsers

ゴールに到達したユーザーの数

value

goalReachRate

表示したユーザーのうち、ゴールに到達したユーザーの割合

rate

goalStatus

人数の割合、属性の合計、または平均値で目標達成状況を表示

value

avgVisitDuration

表示ユーザーの平均滞在時間

time

avgPagesPerVisit

表示ユーザーの1訪問あたりの平均ページビュー数

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": "表示UU", "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": "JP"
}

パラメータ

必須

説明

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": "表示UU", "description": "..." },
                "views": { "value": 300, "label": "表示回数", "description": "..." },
                "clickedUsers": { "value": 50, "label": "クリックUU", "description": "..." },
                "clickRate": { "value": "41.67%", "label": "クリック率", "description": "..." },
                "goals": [
                    {
                        "name": "購入完了",
                        "reachedUsers": { "value": 5, "label": "ゴール達成UU", "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": "JP"
}

パラメータ

必須

説明

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": "表示UU", "description": "..." },
                "bounceRate": { "value": "38.00%", "label": "直帰率", "description": "..." }
            },
            {
                "name": "モバイル",
                "subName": "リピーター",
                "viewedUsers": { "value": 20, "label": "表示UU", "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": "JP"
}

パラメータ

必須

説明

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

表示UU

clickedUsers

クリックUU

closedUsers

閉じたUU

formSubmittedUsers

フォーム送信UU

goalReached

ゴール達成（goalId が必要）

avgVisitDuration

表示ユーザーの平均滞在時間

avgPagesPerVisit

表示ユーザーの1訪問あたりの平均ページビュー数

bounceRate

表示ユーザーの直帰率

レスポンス例：

{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "春季キャンペーンポップアップ",
        "items": [
            {
                "name": "Control",
                "viewedUsers": { "value": 50, "label": "表示UU", "description": "..." },
                "goalReachedUsers": { "value": 5, "label": "ゴール達成UU", "description": "..." },
                "goalReachRate": { "value": "10.00%", "label": "ゴール達成率", "description": "..." },
                "uplift": { "value": "Baseline", "label": "リフト", "description": "..." },
                "probabilityToBeBest": { "value": null, "label": "勝率", "description": "..." }
            },
            {
                "name": "Pattern 1",
                "viewedUsers": { "value": 50, "label": "表示UU", "description": "..." },
                "goalReachedUsers": { "value": 8, "label": "ゴール達成UU", "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": "JP"
}

パラメータ

必須

説明

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": "表示UU", "description": "..." },
                        "uplift": { "value": "Baseline", "label": "リフト", "description": "..." }
                    },
                    {
                        "name": "Control",
                        "viewedUsers": { "value": 20, "label": "表示UU", "description": "..." },
                        "uplift": { "value": "Baseline", "label": "リフト", "description": "..." }
                    },
                    {
                        "name": "Pattern 1",
                        "viewedUsers": { "value": 20, "label": "表示UU", "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 の各行はフォーム送信1件に対応し、値のないフィールドは空文字列になります

3.9 利用可能な指標

基本指標（すべてのタイプで対応）

フィールド

フォーマット

説明

viewedUsers

数値

表示UU

views

数値

表示回数

avgVisitDuration

時間（MM:SS/HH:MM:SS）

平均訪問時間

avgPagesPerVisit

小数（"2.50"）

平均閲覧ページ数

bounceRate

パーセンテージ（"42.86%"）

直帰率

ポップアップ系指標（POPUP / STICKY_BAR / REDIRECT / ADVANCED でポップアップがある場合のみ）

フィールド

フォーマット

説明

clickedUsers

数値

クリックUU

clickRate

パーセンテージ

クリック率

closedUsers

数値

閉じたUU

closeRate

パーセンテージ

閉じた率

フォーム系指標（フォームが設定された体験のみ）

フィールド

フォーマット

説明

formSubmittedUsers

数値

フォーム送信UU

formSubmitRate

パーセンテージ

フォーム送信率

ゴールデータ

フィールド

説明

goals[].name

ゴール名

goals[].reachedUsers

達成UU

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 つ + 時間ディメンション（day / hour / week / month）は最大 1 つ——製品の /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=JP

サポートされる指標・ディメンション・演算子（多言語ラベル付き）を返します。

4.4 利用可能な指標

フィールド

説明

dataType

eventCount

イベント発生回数

INTEGER

sessions

イベントが発生したセッション数

INTEGER

4.5 利用可能なディメンション（`dimensions[]` グループ化用）

フィールド名は /heatmap/query のフィルター項目と同じ命名です。

カテゴリ

フィールド

説明

event

eventName

イベント名

visit

visitType

New visits / Returning visits

visit

exitType

Bounce visits / Non-bounce visits

page

originalPages

入口ページ（完全URL）

page

combinedPages

入口ページ（クエリ文字列を除く）

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検索エンジン

utmCampaign / utmSource / utmMedium / utmTerm / utmContent

UTM フィールド

terminal

deviceType

PC / Mobile / Tablet

terminal

deviceBrand

デバイスブランド

terminal

os / osVersion / browser / browserVersion

OS / ブラウザ + バージョン

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 / クエリ無し）

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

OS / ブラウザ + バージョン

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 つ + 時間ディメンション（day / hour / week / month）は最大 1 つ。いずれかを超えると 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

対象のExperienceが見つかりません（id がこのプロファイル配下に存在しません）

4290

429

リクエスト頻度超過（毎分）

4291

429

リクエスト頻度超過（毎日）

5000

500

サーバー内部エラー

message はリクエストの lang（body または query）に応じて EN/ZH/JP で返されます。lang が未指定または非対応の場合は英語にフォールバックします。

エラーレスポンスフォーマット：

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

前へ計測用の拡張APIについて次へユーザープロパティアップロードAPI

最終更新 10 日前

hashtag1. 共通事項

hashtag1.1 概要

hashtag1.2 認証方式

hashtag1.3 リクエスト頻度制限

hashtag2. ヒートマップデータクエリ

hashtag2.1 ヒートマップデータのクエリ

hashtagリクエストボディ

hashtagリクエストパラメータ

hashtagフィルター条件（filters）

hashtagフィルター利用可能値のクエリ

hashtagカスタムディメンションフィルター

hashtagカスタムディメンション（イベント名）フィルター

hashtag2.2 クエリタイプ

hashtag2.2.1 page_metrics — ページ基本指標

hashtag2.2.2 page_insight — ページ詳細指標（ディメンション別グループ化）

hashtag2.2.3 block_metrics — ブロック指標

hashtag2.2.4 element_metrics — エレメント指標

hashtag2.3 利用可能な指標

hashtag2.3.1 ページ指標（page_metrics と page_insight で使用）

hashtagトラフィック

hashtagエンゲージメント

hashtagコンバージョン

hashtag2.3.2 ブロック指標（block_metrics で使用）

hashtag2.3.3 エレメント指標（element_metrics で使用）

hashtag2.4 デバイスタイプルール

hashtag2.5 ブロック・エレメントクエリの前提条件

hashtag2.6 リクエスト例

hashtag例 1：ページトラフィック概要のクエリ

hashtag例 2：デバイスタイプ別ページ詳細指標のクエリ

hashtag例 3：モバイル端末ブロック分析のクエリ

hashtag例 4：指定コンバージョン目標データのクエリ

hashtag例 5：PC端末エレメントクリック分析のクエリ

hashtag2.7 補足事項

hashtag3. Experience データクエリ

hashtag3.1 体験リストの取得

hashtag3.2 ユーザープロパティリストの取得

hashtag3.3 体験概要指標

hashtag3.4 基本指標

hashtag3.5 詳細分析

hashtag3.6 A/Bテストの結果

hashtag3.7 A/Bテストの結果 — 詳細分析

hashtag3.8 フォーム送信

hashtag3.9 利用可能な指標

hashtag基本指標（すべてのタイプで対応）

hashtagポップアップ系指標（POPUP / STICKY_BAR / REDIRECT / ADVANCED でポップアップがある場合のみ）

hashtagフォーム系指標（フォームが設定された体験のみ）

hashtagゴールデータ

hashtag4. イベントデータクエリ

hashtag4.1 イベントデータのクエリ

hashtag4.2 その他のサンプル

hashtaga) 最小構成 — イベント名ごとのカウント

hashtagb) 時系列 — 日次集計

hashtagc) コンバージョン目標でフィルター（名前のあいまい一致）

hashtagd) カスタムイベントプロパティ — グループ + フィルター

hashtage) 流入分析 — UTM + ソースタイプ

hashtagf) 新規訪問者 + PC + 日本／中国

hashtagg) 直帰セッションを除外

hashtag4.3 利用可能なフィールド一覧の取得

hashtag4.4 利用可能な指標

hashtag4.5 利用可能なディメンション（dimensions[] グループ化用）

hashtag4.6 利用可能なフィルターフィールド（filters[] 用）

hashtag4.7 カスタムイベントプロパティ

hashtag4.8 補足事項

hashtag付録

hashtagA. エラーコード

1. 共通事項

1.1 概要

1.2 認証方式

1.3 リクエスト頻度制限

2. ヒートマップデータクエリ

2.1 ヒートマップデータのクエリ

リクエストボディ

リクエストパラメータ

フィルター条件（filters）

フィルター利用可能値のクエリ

カスタムディメンションフィルター

カスタムディメンション（イベント名）フィルター

2.2 クエリタイプ

2.2.1 `page_metrics` — ページ基本指標

2.2.2 `page_insight` — ページ詳細指標（ディメンション別グループ化）

2.2.3 `block_metrics` — ブロック指標

2.2.4 `element_metrics` — エレメント指標

2.3 利用可能な指標

2.3.1 ページ指標（`page_metrics` と `page_insight` で使用）

トラフィック

エンゲージメント

コンバージョン

2.3.2 ブロック指標（`block_metrics` で使用）

2.3.3 エレメント指標（`element_metrics` で使用）

2.4 デバイスタイプルール

2.5 ブロック・エレメントクエリの前提条件

2.6 リクエスト例

例 1：ページトラフィック概要のクエリ

例 2：デバイスタイプ別ページ詳細指標のクエリ

例 3：モバイル端末ブロック分析のクエリ

例 4：指定コンバージョン目標データのクエリ

例 5：PC端末エレメントクリック分析のクエリ

2.7 補足事項

3. Experience データクエリ

3.1 体験リストの取得

3.2 ユーザープロパティリストの取得

3.3 体験概要指標

3.4 基本指標

3.5 詳細分析

3.6 A/Bテストの結果

3.7 A/Bテストの結果 — 詳細分析

3.8 フォーム送信

3.9 利用可能な指標

基本指標（すべてのタイプで対応）

ポップアップ系指標（POPUP / STICKY_BAR / REDIRECT / ADVANCED でポップアップがある場合のみ）

フォーム系指標（フォームが設定された体験のみ）

ゴールデータ

4. イベントデータクエリ

4.1 イベントデータのクエリ

4.2 その他のサンプル

a) 最小構成 — イベント名ごとのカウント

b) 時系列 — 日次集計

c) コンバージョン目標でフィルター（名前のあいまい一致）

d) カスタムイベントプロパティ — グループ + フィルター

e) 流入分析 — UTM + ソースタイプ

f) 新規訪問者 + PC + 日本／中国

g) 直帰セッションを除外

4.3 利用可能なフィールド一覧の取得

4.4 利用可能な指標

4.5 利用可能なディメンション（`dimensions[]` グループ化用）

4.6 利用可能なフィルターフィールド（`filters[]` 用）

4.7 カスタムイベントプロパティ

4.8 補足事項

付録

A. エラーコード