# Open API ドキュメント

***

## 1. 共通事項

### 1.1 概要

Ptengine Open API は、ヒートマップおよび分析データへのプログラムアクセスを提供する RESTful エンドポイントです。本ドキュメントを AI エージェントに渡すと、エージェントは自然言語のリクエストから API 呼び出しを自動構築できます。

**ベース URL:**

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

### 1.2 認証方法

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

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

**API キーの取得手順：**

> **権限要件**: Admin および Owner ロールのみ API キーを作成・管理できます。

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": "..." }`

エラーコード一覧は [付録 — エラーコード](#error-codes) を参照してください。

***

## 2. Insight

本章では Heatmap、Event、Data Center、Conversion の 4 つのクエリエンドポイントを扱います。

### 2.1 共通ルール

4 つのエンドポイント（Heatmap、Event、Data Center、Conversion）のリクエストには共通の `conversionNames` と `filters` フィールドがあります。コンバージョン目標名の取得方法、`filters` の書き方と値の取得方法をここでまとめます。先にこの章を読んでから各エンドポイント章へ進むと、すぐに使い始められます。

#### コンバージョン目標

コンバージョンデータを参照する場合（「購入完了は何回」「登録のコンバージョン率は」など）、まずどのコンバージョン目標を見るかを指定する必要があります。このエンドポイントは Ptengine で設定済みのすべての目標名を返します — 取得した名前をクエリリクエストにそのまま記入してください。

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "conversions": [
            { "id": "1753350579776", "name": "ptmind 登録" },
            { "id": "1753350579999", "name": "購入完了" }
        ]
    }
}
```

`name` を取得したら、任意のクエリエンドポイント（`/event/query`、`/datacenter/query`、`/conversion/query`、`/heatmap/query`）の `conversionNames` フィールドに記入します。例：`"conversionNames": ["購入完了"]`。

#### Filter

リクエストボディの `filters` フィールドに条件を追加して、データの絞り込みを行います。例：Mobile のみ、日本地域のみ、特定の広告キャンペーンのみ。

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

フィールド：

| フィールド   | 意味                                             |
| ------- | ---------------------------------------------- |
| `name`  | 絞り込みフィールド名（カテゴリは下記表を参照）                        |
| `op`    | `include`（含む）または `exclude`（除外）。他の演算子はサポートされません |
| `value` | 絞り込みの値。配列必須（単一値でも `["Japan"]` のように記述）          |

> カスタムプロパティ filter（イベントプロパティで絞り込む場合）には追加の `eventName` / `eventVariant` が必要 — 下記「カスタムプロパティ filter（応用）」参照。

フィールドはタイプ別に 2 カテゴリに分かれます：

**固定値フィールド**

下記 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-values](#filter-values) エンドポイントで実時取得してください。

| カテゴリ | name               | 意味                 | value 例                                                      |
| ---- | ------------------ | ------------------ | ------------------------------------------------------------ |
| 端末   | `os`               | 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`        | 流入元（UTM）           | `["google", "facebook"]`                                     |
| 広告   | `utmMedium`        | メディア（UTM）          | `["cpc", "email"]`                                           |
| 広告   | `utmTerm`          | キーワード（UTM）         | `["heatmap tool"]`                                           |
| 広告   | `utmContent`       | コンテンツ（UTM）         | `["banner_a"]`                                               |
| ページ  | `combinedPages`    | 入口ページ（合成）          | `["https://ptengine.jp/app/login"]`                          |
| ページ  | `originalPages`    | 元ページ（フル URL）       | `["https://ptengine.jp/app/select_project?from=login"]`      |
| イベント | `eventName`        | イベント名              | `["checkout_completed", "product_viewed"]`                   |
| イベント | `dimension`        | カスタムディメンション（横断）    | `eventVariant` と併用                                           |
| イベント | `eventDimension`   | カスタムディメンション（イベント名） | `eventName` と `eventVariant` を併用                             |
| 転換   | `conversionName`   | コンバージョン名           | `["購入完了"]`                                                   |

> value 例は参考用です。実際の利用可能値は [filter-values](#filter-values) で取得してください。

**カスタムプロパティ filter（応用）**

イベントにカスタムプロパティ（例：`purchase` イベントに `price` プロパティ）が付与されており、プロパティ値で絞り込みたい場合のみ使用します。2 種類の形態：

* **特定イベントに紐づけ**：`{ "name": "eventDimension", "eventName": "purchase", "eventVariant": "price", "op": "include", "value": ["100"] }` — `purchase` イベントで `price=100` のセッションのみ
* **イベント横断**：`{ "name": "dimension", "eventVariant": "price", "op": "include", "value": ["100"] }` — 任意のイベントで `price=100` を持つもの

**filter-values**

指定された filter フィールドの利用可能な値リストを返します（例：データのある国一覧、OS 一覧など）。返値は任意のクエリエンドポイントの filter `value` フィールドに**そのまま**使用できます。

**リクエストパラメータ**

| パラメータ          | 必須     | 型      | 説明                                                                                                                        |
| -------------- | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `profileId`    | 必須     | string | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。Ptengine の URL `https://www.ptengine.jp/app/{profileId}/home` の `566d12f9` 部分など |
| `name`         | 必須     | string | 取得対象の filter フィールド名。上記 [動的値フィールド](#dynamic-fields) 参照                                                                     |
| `startDate`    | 任意     | string | 開始日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`。未指定の場合は直近 30 日                                                                       |
| `endDate`      | 任意     | string | 終了日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`。未指定の場合は直近 30 日                                                                       |
| `search`       | 任意     | string | あいまい検索キーワード                                                                                                               |
| `eventName`    | 条件付き必須 | string | `name="eventDimension"` のときのみ（例 5 のステップ 2 参照）                                                                             |
| `eventVariant` | 条件付き必須 | string | `name="eventDimension"` のときのみ（例 5 のステップ 2 参照）                                                                             |

**例 1：通常のフィールド（country / os / browser など）**

リクエスト：

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

レスポンス：

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

**例 2：あいまい検索（`search`）**

キーワードで値リストを絞り込む場合 `search` を渡します。例：国名に "Ja" を含むもの（Japan、Jamaica などが該当）：

リクエスト：

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

レスポンス：

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

**例 3：全イベント名を取得（`name="eventName"`）**

プロファイル配下のデータがあるすべてのイベント名を返します。

リクエスト：

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

レスポンス：

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

**例 4：すべてのカスタムイベントプロパティ名を取得**

プロファイル配下のすべてのカスタムイベントプロパティ名を返します。

リクエスト：

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

レスポンス：

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

**例 5：特定イベントのプロパティ値を取得（`eventDimension`、2 ステップ）**

`eventDimension` は 2 ステップ必要：まず `name="eventDimension"` で「イベント + プロパティ」のペアリストを取得し、選択した `eventName` + `eventVariant` を渡して実際の値を取得します。

**ステップ 1 — (イベント, プロパティ) ペアリストを取得：**

リクエスト：

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

レスポンス：

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

**ステップ 2 — 選択した eventName + eventVariant で値を取得：**

リクエスト：

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

レスポンス：

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

***

### 2.2 Heatmap

ヒートマップ分析 — ページ／ブロック／要素のクリックと閲覧。

#### リクエストパラメータ

| パラメータ             | 必須     | 型         | 説明                                                                                                                                                                                     |
| ----------------- | ------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `queryType`       | 必須     | string    | クエリタイプ：`page_metrics`（ページ基本指標）、`page_insight`（ページ詳細指標）、`block_metrics`（ブロック指標）、`element_metrics`（要素指標）                                                                                 |
| `profileId`       | 必須     | string    | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。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    | 端末タイプの絞り込み。 [端末タイプルール](#device-type-rules) 参照                                                                                                                                          |
| `rangeType`       | 任意     | string    | URL マッチモード。`MERGE_URL`（既定）はクエリパラメータを統合、`URL` は完全一致                                                                                                                                     |
| `metrics`         | 任意     | string\[] | 未指定の場合はすべての指標を返却、指定した場合はそれのみ。利用可能な指標は [利用可能な指標](#available-metrics) 参照                                                                                                                 |
| `conversionNames` | 任意     | string\[] | コンバージョン名リスト。§2.1 [コンバージョン目標](#conversion-goals) 参照                                                                                                                                     |
| `filters`         | 任意     | object\[] | 絞り込み条件。§2.1 [Filter](#filter) 参照                                                                                                                                                       |
| `lang`            | 任意     | string    | ラベルの言語：`EN`（既定）、`ZH`、`JP`。不正値は `EN` にフォールバック                                                                                                                                           |
| `funName`         | 条件付き必須 | string    | `queryType=page_insight` のとき必須。許容値：`terminalType`（端末）、`sourceType`（流入元）、`visitType`（新規／再訪問）、`aiName`（AI 流入元）、`utmCampaign`、`utmSource`、`utmMedium`、`utmTerm`、`utmContent`、`week`、`day` |

#### クエリタイプ

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

指定ページのトラフィック、行動、コンバージョンの指標を返します。

**端末タイプ：** `ALL`、`PC`、`MOBILE`、`TABLET`

**`metrics` パラメータ：** 未指定の場合は全指標、指定した場合のみそれら。

**コンバージョンクエリ：** すべてのクエリタイプがコンバージョンに対応。`metrics` に `completions`（コンバージョン数）と／または `conversionRate`（コンバージョン率）を追加し、`conversionNames` にコンバージョン名を渡します。

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "metrics": {
            "pv": { "value": "15,234", "label": "ページビュー（PV）", "description": "ページが閲覧された回数。" },
            "uv": { "value": "8,721", "label": "ユニークビジター（UV）", "description": "ページを閲覧したユニークビジター数。" },
            "visits": { "value": "10,532", "label": "訪問数", "description": "ページが閲覧された訪問数。" },
            "bounceRate": { "value": "45.23%", "label": "直帰率", "description": "このページから入って他のページに移動せず離脱した訪問者の割合。" },
            "conversionRate": { "value": "2.22%", "label": "コンバージョン率", "description": "このページを閲覧した上でコンバージョンを達成した訪問の割合。" }
        },
        "conversions": [
            {
                "conversionName": "購入完了",
                "conversionRate": { "value": "1.71%", "label": "コンバージョン率", "description": "このページを閲覧した上でコンバージョンを達成した訪問の割合。" }
            }
        ]
    },
    "meta": {
        "queryType": "page_metrics",
        "profileId": "566d12f9",
        "url": "https://ptengine.jp",
        "dateRange": { "start": "2025-06-01", "end": "2025-06-30" },
        "deviceType": "ALL",
        "lang": "JP"
    }
}
```

> **注：** `conversions` には `metrics` で指定したコンバージョン指標のみ返却されます。上の例では `metrics` に `conversionRate` のみあるので、`conversions` には conversionRate のみ含まれます。完了数も同時に返すには `metrics` に `completions` を追加してください。

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

指定されたディメンションでグループ化されたページ指標を返します。

**端末タイプ：** `ALL`、`PC`、`MOBILE`、`TABLET`

**必須：** `funName`（`metrics` 未指定なら全指標）

**`funName` 許容値：**

| funName        | 意味                                  |
| -------------- | ----------------------------------- |
| `terminalType` | 端末タイプ別（PC/Smart phone/Tablet）       |
| `sourceType`   | 流入元種類別（Direct/Search/Social/...）    |
| `visitType`    | 訪問タイプ別（New visits/Returning visits） |
| `aiName`       | AI 名別                               |
| `utmCampaign`  | UTM Campaign 別                      |
| `utmSource`    | UTM Source 別                        |
| `utmMedium`    | UTM Medium 別                        |
| `utmTerm`      | UTM Term 別                          |
| `utmContent`   | UTM Content 別                       |
| `week`         | 週別                                  |
| `day`          | 日別                                  |

**リクエスト例（端末タイプ別）：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "insights": [
            {
                "name": "PC",
                "metrics": {
                    "pv": { "value": "8,500", "label": "ページビュー（PV）", "description": "ページが閲覧された回数。" },
                    "uv": { "value": "5,200", "label": "ユニークビジター（UV）", "description": "ページを閲覧したユニークビジター数。" },
                    "bounceRate": { "value": "38.00%", "label": "直帰率", "description": "このページから入って他のページに移動せず離脱した訪問者の割合。" }
                },
                "conversions": []
            },
            {
                "name": "Mobile",
                "metrics": {
                    "pv": { "value": "5,800", "label": "ページビュー（PV）", "description": "ページが閲覧された回数。" },
                    "uv": { "value": "3,100", "label": "ユニークビジター（UV）", "description": "ページを閲覧したユニークビジター数。" },
                    "bounceRate": { "value": "55.00%", "label": "直帰率", "description": "このページから入って他のページに移動せず離脱した訪問者の割合。" }
                },
                "conversions": []
            },
            {
                "name": "Tablet",
                "metrics": {
                    "pv": { "value": "934", "label": "ページビュー（PV）", "description": "ページが閲覧された回数。" },
                    "uv": { "value": "421", "label": "ユニークビジター（UV）", "description": "ページを閲覧したユニークビジター数。" },
                    "bounceRate": { "value": "42.15%", "label": "直帰率", "description": "このページから入って他のページに移動せず離脱した訪問者の割合。" }
                },
                "conversions": []
            }
        ]
    }
}
```

**`block_metrics` — ブロック指標**

ページ内の各ブロックの指標とスクリーンショット URL を返します。事前に Ptengine 上でページスキャンとブロック設定が必要です。

**端末タイプ：** `PC`、`MOBILE`、`TABLET` を指定。**`ALL` は不可**

**`metrics` パラメータ：** 任意。未指定なら全指標、指定したらそれらのみ。`blockName` と `screenshotUrl` は常に返却。

**利用可能な指標：** `impression`、`impressionRate`、`avgDuration`、`dropoff`、`dropoffRate`、`completions`、`conversionRate`

**stayTimeFilter：** 任意、ブロック滞在時間フィルター（秒）、既定 5 秒。

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "blocks": [
            {
                "blockName": "ヒーローバナー",
                "screenshotUrl": "https://cdn.example.com/screenshot/block1.png",
                "metrics": {
                    "impression": { "value": "12,000", "label": "インプレッション", "description": "ユーザーが現在のブロックを画面に見始めた PV 数。" },
                    "impressionRate": { "value": "95.00%", "label": "インプレッション率", "description": "ユーザーが現在のブロックを見始めた PV の割合。" },
                    "avgDuration": { "value": "5s", "label": "平均滞在時間", "description": "ブロックを見たユーザーの平均滞在時間。" },
                    "dropoff": { "value": "800", "label": "離脱", "description": "現在のブロックから離脱し、他ページへのクリックもコンバージョンもなかった PV 数。" },
                    "dropoffRate": { "value": "6.70%", "label": "離脱率", "description": "現在のブロックから離脱した PV の割合。" }
                },
                "conversions": []
            }
        ]
    }
}
```

**`element_metrics` — 要素指標**

ページ内の各トラッキング対象要素の指標を返します。事前に Ptengine 上でページスキャンと要素設定が必要です。

**端末タイプ：** `PC`、`MOBILE`、`TABLET` を指定。**`ALL` は不可**

**`metrics` パラメータ：** 任意。未指定なら全指標、指定したらそれらのみ。`elementName` は常に返却。

**利用可能な指標：** `impression`、`impressionRate`、`click`、`clickRate`、`completions`、`conversionRate`

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "elements": [
            {
                "elementName": "登録ボタン",
                "metrics": {
                    "impression": { "value": "10,500", "label": "インプレッション", "description": "ユーザーが現在の要素を見た PV 数。" },
                    "impressionRate": { "value": "88.00%", "label": "インプレッション率", "description": "ユーザーが現在の要素を見た PV の割合。" },
                    "click": { "value": "1,500", "label": "クリック", "description": "現在の要素のクリック数。" },
                    "clickRate": { "value": "14.30%", "label": "クリック率", "description": "クリック数 ÷ インプレッション数。" }
                },
                "conversions": []
            }
        ]
    }
}
```

#### 利用可能な指標

**ページ指標（`page_metrics` と `page_insight` 用）**

`metrics` 配列に下記のフィールド名を使用します。

#### トラフィック獲得

| フィールド           | 説明                 | タイプ   |
| --------------- | ------------------ | ----- |
| `visits`        | ページが閲覧された訪問数       | value |
| `pv`            | ページが閲覧された回数        | value |
| `uv`            | ページを閲覧したユニークビジター数  | value |
| `newVisitsRate` | ページを閲覧した新規訪問の割合    | rate  |
| `entrances`     | このページが入口ページとなった訪問数 | value |

#### 行動

| フィールド          | 説明                                                              | タイプ     |
| -------------- | --------------------------------------------------------------- | ------- |
| `fvRate`       | ページ到達後にスクロール／コンバージョン／遷移をしなかった訪問者の割合。値が高いとファーストビューが魅力的でないことを示します | rate    |
| `timeOnPage`   | ページの平均滞在時間                                                      | time    |
| `clicks`       | ページの総クリック数（リンクの有無問わず）                                           | value   |
| `clickRate`    | PV あたりのクリック数                                                    | rate    |
| `ctaClicks`    | ページ内主要 CTA のクリック数                                               | value   |
| `ctaClickRate` | CTA クリック率 = CTA クリック数 / PV                                      | rate    |
| `bounceRate`   | このページから入って他のページに移動せず離脱した訪問者の割合                                  | rate    |
| `avgPageViews` | このページに入った訪問者の平均ページ閲覧数                                           | decimal |

#### コンバージョン

| フィールド            | 説明                                          | タイプ   |
| ---------------- | ------------------------------------------- | ----- |
| `completions`    | このページを閲覧した上でコンバージョンを達成した訪問数                 | value |
| `conversionRate` | このページを閲覧した訪問のうちコンバージョン達成の割合。高いほどこのページの貢献度が大 | rate  |

> **注：** コンバージョンクエリでは `conversionNames` にコンバージョン名も渡してください。

**ブロック指標（`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  |

**要素指標（`element_metrics` 用）**

`metrics` 未指定なら全指標、指定したら指定のもののみ。`elementName` は常に返却。

| フィールド            | 説明                           | タイプ   |
| ---------------- | ---------------------------- | ----- |
| `elementName`    | 要素名                          | text  |
| `impression`     | ユーザーが現在の要素を見た PV 数           | value |
| `impressionRate` | ユーザーが現在の要素を見た PV の割合         | rate  |
| `click`          | 現在の要素のクリック数                  | value |
| `clickRate`      | クリック数 ÷ インプレッション数。高いほど要素が魅力的 | rate  |
| `completions`    | 要素をクリックし、コンバージョンを達成した訪問数     | value |
| `conversionRate` | 要素をクリックした訪問のうちコンバージョン達成の割合   | rate  |

#### 端末タイプルール

| queryType         | サポート 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. 設定を保存

ページ未設定の場合、API は `4008`（ブロック未設定）または `4016`（要素未設定）を返します。

#### リクエスト例

**例 1：ページトラフィック概要**

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

**例 2：端末タイプ別ページ詳細指標**

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

**例 3：モバイルブロック分析（日本地域 filter 付き）**

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

**例 4：特定コンバージョン目標のデータ**

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

**例 5：PC 要素クリック分析**

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

#### 補足

* 時間系フィールド（ページ `timeOnPage`、ブロック `avgDuration` など）は単位付き文字列で返却（例：`"5s"`、`"1m 30s"`）。
* レート系フィールドは小数値（例：`bounceRate: 0.45` は 45%）。
* API のデータソースは Ptengine 製品 UI と同一。結果も一致するはずです。
* 要求した URL がプロファイル下で未収集の場合、API は `200` を返しますが指標値はすべて `0` です。エラーは返しません。

***

### 2.3 Event

イベント分析。ディメンション、指標、セグメント（リクエストの `filters` フィールド）でイベントを検索します。

#### リクエストパラメータ

| パラメータ        | 必須 | 型                     | 説明                                                                                                                                                                                                                                 |
| ------------ | -- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `profileId`  | 必須 | string                | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。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: "<propName>" }`（カスタムイベントプロパティ） |
| `metrics`    | 任意 | string\[]             | 指標フィールド名。既定 `["eventCount"]`。許容：`eventCount`、`sessions`                                                                                                                                                                            |
| `filters`    | 任意 | object\[]             | セグメント（filter）条件。§2.1 [Filter](#filter) 参照                                                                                                                                                                                          |

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

イベントにカスタムプロパティ（例：`purchase` イベントに `price` プロパティ）がある場合、プロパティでグループ化やセグメントできます。

* **プロパティ別グループ化** — `dimensions` に追加：

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

  結果は `price` 値で集計されます。
* **プロパティでセグメント** — `filters` に追加：

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

  `purchase` イベントで `price=100` のセッションのみ。
* **セグメント時は必ずイベントをロック** — プロパティでセグメントする際、`filters` に追加で eventName セグメントを入れる必要があります。これがないとクエリはどのイベントに紐づけるか判別できません：

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

**リクエスト例：**

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

**レスポンス例：**

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

#### その他の例

**a) 最小 — イベント名別カウント**

**リクエスト例：**

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

**b) 時系列 — 日別**

**リクエスト例：**

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

**c) コンバージョン目標で絞り込み（名称あいまい一致）**

**リクエスト例：**

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

> `conversionName` は名前に `"ptmind"` を含むすべての目標に一致します。一致なしなら `4012` を返却。

**d) カスタムイベントプロパティ — グループ化 + 絞り込み**

**リクエスト例：**

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

> 両方の filter が必要で役割は異なります：独立した `eventName` filter がクエリ全体を `gallery_item_impression` にロック（集計範囲）、`eventDimension` filter がさらに `position == "home"` でセグメント。

**e) 流入元の分布 — UTM + ソースタイプ**

**リクエスト例：**

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

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

**リクエスト例：**

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

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

**リクエスト例：**

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

#### メタデータ

利用可能な metrics と dimensions を返します（多言語ラベル付き、`lang` で切替可能）。

**リクエスト例：**

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

**レスポンス例（抜粋）：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "metrics": [
            { "field": "eventCount", "label": "イベント数", "description": "イベントが発生した回数。", "dataType": "INTEGER" },
            { "field": "sessions", "label": "セッション数", "description": "イベントが発生したセッション数。", "dataType": "INTEGER" }
        ],
        "dimensions": [
            { "field": "eventName", "label": "イベント名", "description": "イベントの名前。", "dataType": "STRING", "category": "event" },
            { "field": "country", "label": "国", "description": "国。", "dataType": "STRING", "category": "geography" }
        ]
    }
}
```

#### 利用可能な指標

| フィールド        | 説明              | dataType |
| ------------ | --------------- | -------- |
| `eventCount` | イベントが発生した回数     | INTEGER  |
| `sessions`   | イベントが発生したセッション数 | INTEGER  |

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

| フィールド              | 説明         |
| ------------------ | ---------- |
| `eventName`        | イベント名      |
| `visitType`        | 訪問タイプ      |
| `exitType`         | 離脱タイプ      |
| `combinedPages`    | 入口ページ      |
| `conversionName`   | コンバージョン名   |
| `day`              | 日付         |
| `hour`             | 時間         |
| `week`             | 週          |
| `month`            | 月          |
| `sourceType`       | ソースタイプ     |
| `campaignUrl`      | キャンペーン URL |
| `referralSource`   | ホスト名       |
| `referralUrl`      | 参照元 URL    |
| `searchEngine`     | 検索エンジン     |
| `socialNetwork`    | ソーシャル      |
| `socialUrl`        | ソーシャル URL  |
| `aiName`           | AI 検索      |
| `utmCampaign`      | キャンペーン名    |
| `utmSource`        | 流入元        |
| `utmMedium`        | メディア       |
| `utmContent`       | コンテンツ      |
| `utmTerm`          | キーワード      |
| `deviceType`       | 端末タイプ      |
| `deviceBrand`      | ブランド       |
| `os`               | OS         |
| `osVersion`        | OS バージョン   |
| `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 キーが紐づくプロファイルと一致する必要があります。Ptengine の URL `https://www.ptengine.jp/app/{profileId}/home` の `566d12f9` 部分など                                                                                                                           |
| `startDate`      | 必須 | string    | 開始日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                                                                                                                                                |
| `endDate`        | 必須 | string    | 終了日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                                                                                                                                                |
| `filters`        | 任意 | object\[] | 絞り込み条件。§2.1 [Filter](#filter) 参照                                                                                                                                                                                                                    |
| `conversionName` | 任意 | string    | 単一のコンバージョン目標で指標を絞り込み。**未指定の場合は全コンバージョン集計の指標を返却。** `dimension_table`（`combinedPages` / `originalPages` / `pageGroup` 以外の dimension）と `metric_curve`（`metric` ∈ `conversions` / `conversionRate` / `conversionValue`）でのみ有効。それ以外のシナリオで指定すると `4018` を返却 |
| `lang`           | 任意 | string    | ラベルの言語：`EN`（既定）、`ZH`、`JP`。`overview` の `topic = "metrics"` と、`dimension_table` の metric 列 `label` / `description` に反映。不正値は `EN` にフォールバック                                                                                                            |

#### クエリタイプ

**`overview` — トピック別のサマリーデータ**

トピック別の概要データを返します。

**必須：** `topic`、許容値：`metrics` / `sources` / `location` / `device`。

> より詳細な明細（特定検索エンジン / 引用 URL / キャンペーン名、または OS / ブラウザ分布など）は `queryType: "dimension_table"` と対応する `dimension` を使用してください。

**`topic = "metrics"` — 指標サマリー**

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "data": {
        "topic": "metrics",
        "metrics": {
            "visits": {
                "value": "12,500",
                "label": "訪問数",
                "description": "サイトが訪問された回数です。セッションともいいます。1人のユーザーがサイトに訪問すると「1」訪問数とみなされます。"
            },
            "users": {
                "value": "8,900",
                "label": "UU",
                "description": "選択された期間内でサイトに訪問したユーザー数(デバイス数)です。"
            },
            "pageView": {
                "value": "32,000",
                "label": "PV",
                "description": "ウェブページがロードされた回数です。"
            },
            "newVisitsRate": {
                "value": "65.00%",
                "label": "新規率",
                "description": "全体の訪問数に対して、初めてサイトに訪れた訪問の割合です。"
            },
            "returnVisitsRate": {
                "value": "35.00%",
                "label": "再訪問率",
                "description": "全体の訪問数に対して、以前にサイトを訪れたことのある訪問の割合です。"
            },
            "avgPageView": {
                "value": "2.56",
                "label": "PV/UU",
                "description": "選択された期間における1ユーザーあたりの平均PV数です。"
            },
            "avgVisits": {
                "value": "1.40",
                "label": "訪問数/UU",
                "description": "選択された期間における1ユーザーあたりの平均サイト訪問数です。"
            },
            "avgVisitDuration": {
                "value": "3m 7s",
                "label": "平均滞在時間",
                "description": "訪問開始してから終了するまでの滞在時間を平均した指標です。"
            },
            "avgLoadTime": {
                "value": "4s",
                "label": "平均ロード時間",
                "description": "ページ読み込みが完了するまでの時間の平均です。"
            },
            "bounceRate": {
                "value": "42.00%",
                "label": "直帰率",
                "description": "総訪問数の内、1ページしか見なかった訪問(直帰訪問)の割合です。"
            }
        }
    }
}
```

**`topic = "sources"` — 流入元**

**リクエスト例：**

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

**レスポンス例：**

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

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

**リクエスト例：**

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

**レスポンス例：**

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

**`topic = "device"` — 端末分布**

**リクエスト例：**

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

**レスポンス例：**

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

**`dimension_table` — ディメンション別 Top-N 表**

単一ディメンションでグループ化された Top-N 表を返します。

**必須：** `dimension` — [利用可能なディメンション](#dc-dimensions) 参照。

**任意：** `sortBy` (string) / `sortOrder` (`asc`/`desc`) / `limit`（1-1000、既定 1000）。レスポンスは 1000 行上限。

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "data": {
        "columns": [
            { "name": "country", "type": "dimension", "dataType": "STRING" },
            { "name": "visits", "type": "metric", "dataType": "INTEGER", "label": "訪問数", "description": "サイトが訪問された回数です。セッションともいいます。1人のユーザーがサイトに訪問すると「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": "CV率", "description": "総訪問数の内、特定のコンバージョン地点に到達した訪問の割合です。" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER", "label": "CV数", "description": "特定のコンバージョン地点に到達した訪問数です。" },
            { "name": "bounceRate", "type": "metric", "dataType": "RATE", "label": "直帰率", "description": "総訪問数の内、1ページしか見なかった訪問(直帰訪問)の割合です。" }
        ],
        "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%"
            }
        ]
    }
}
```

> `metric` タイプの列には `label` / `description` が付与されます（言語は `lang` フィールドで切り替え、既定は `EN`）。 Metric 値は製品 UI の列と合わせて文字列でフォーマット済み：INTEGER は千区切り（`"1,145"`）、RATE はパーセント（`"52.18%"`）、`avgVisitDuration` は HH:MM:SS（`"00:02:49"`）、`avgLoadTime` は秒以下の精度（`"2.45s"`）。数値が必要な場合は文字列をパースしてください。

**例：ページ一覧**

「入口ページ」で Top-N を表示。`conversionName` 未指定の場合は全コンバージョン集計の指標を返却します。

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

**レスポンス例：**

```json
{
    "code": 200,
    "data": {
        "columns": [
            { "name": "url", "type": "dimension", "dataType": "STRING" },
            { "name": "title", "type": "dimension", "dataType": "STRING" },
            { "name": "entrances", "type": "metric", "dataType": "INTEGER", "label": "入口数", "description": "該当ページが訪問開始ページとなった訪問の数です。" },
            { "name": "newVisitsRate", "type": "metric", "dataType": "RATE", "label": "新規率", "description": "全体の訪問数に対して、初めてサイトに訪れた訪問の割合です。" },
            { "name": "avgPageVisits", "type": "metric", "dataType": "NUMBER", "label": "平均訪問PV数", "description": "このページから閲覧開始した場合の平均PV数です。" },
            { "name": "avgVisitDuration", "type": "metric", "dataType": "TIME", "label": "平均滞在時間", "description": "訪問開始してから終了するまでの滞在時間を平均した指標です。" },
            { "name": "bounceRate", "type": "metric", "dataType": "RATE", "label": "直帰率", "description": "総訪問数の内、1ページしか見なかった訪問(直帰訪問)の割合です。" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER", "label": "CV数", "description": "特定のコンバージョン地点に到達した訪問数です。" },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE", "label": "CV率", "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%" }
        ]
    }
}
```

> ページ URL 系ディメンション（`combinedPages` / `originalPages` / `entryCombinedPages` / `entryOriginalPages`）は常に `url` + `title` の列を返却。`pageGroup` ディメンションはグループ名の文字列を返却。
>
> **`conversionName` の適用範囲**：
>
> * `entryCombinedPages` / `entryOriginalPages`（入口ページ）は**サポート**：指定すると `conversions` と `conversionRate` の 2 列が選択したコンバージョン目標のみで集計されます（製品 UI 入口ページ表の右上「コンバージョン選択」ドロップダウンと同等）。他の指標は変わりません。
> * `combinedPages` / `originalPages` / `pageGroup`（ページ / ページグループ）は**未対応**：これらディメンションはコンバージョン指標を算出しないため、`conversionName` を渡すと `4018` を返却します。

**例：単一コンバージョン目標で指標を絞り込み**

`conversionName` を指定すると、指標（`conversions` / `conversionRate` 等）はそのコンバージョンのみで集計されます。

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

**レスポンス例：**

```json
{
    "code": 200,
    "data": {
        "columns": [
            { "name": "url", "type": "dimension", "dataType": "STRING" },
            { "name": "title", "type": "dimension", "dataType": "STRING" },
            { "name": "entrances", "type": "metric", "dataType": "INTEGER", "label": "入口数", "description": "該当ページが訪問開始ページとなった訪問の数です。" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER", "label": "CV数", "description": "特定のコンバージョン地点に到達した訪問数です。" },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE", "label": "CV率", "description": "..." }
        ],
        "rows": [
            { "url": "https://ptengine.jp/app/signup", "title": "登録 | Ptengine", "entrances": "1,042", "conversions": "312", "conversionRate": "29.94%" },
            { "url": "https://ptengine.jp", "title": "Ptengineウェブ運営All-in-Oneプラットフォーム | ウェブの改善や改善業務はこれひとつで完結", "entrances": "815", "conversions": "187", "conversionRate": "22.94%" }
        ]
    }
}
```

**`metric_curve` — 単一指標の時系列**

単一指標の時系列を返します。

**必須：** `metric`、許容値は [利用可能な指標](#dc-metrics) を参照；`granularity`、許容値：`hour` / `day` / `week` / `month`。レスポンスの `time` フィールド形式：`YYYY-MM-DD`（`hour` 粒度の場合は `YYYY-MM-DDTHH`）。

> **`hour` 粒度の制約**：`startDate` と `endDate` は同じ日でなければなりません。それ以外は `4002` を返却。`day` / `week` / `month` には制約なし。

**リクエスト例：**

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

**レスポンス例：**

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

#### 利用可能な指標

| 指標                 | タイプ     | 説明        |
| ------------------ | ------- | --------- |
| `visits`           | INTEGER | 訪問数       |
| `users`            | INTEGER | UU        |
| `pageView`         | INTEGER | PV        |
| `newVisitsRate`    | RATE    | 新規率       |
| `returnVisitsRate` | RATE    | 再訪問率      |
| `avgVisits`        | RATE    | 訪問数/UU    |
| `avgPageView`      | RATE    | PV/UU     |
| `avgVisitDuration` | TIME    | 平均滞在時間    |
| `bounceRate`       | RATE    | 直帰率       |
| `avgLoadTime`      | TIME    | 平均ロード時間   |
| `conversions`      | INTEGER | CV数       |
| `conversionRate`   | RATE    | CV率       |
| `conversionValue`  | NUMBER  | コンバージョン価値 |

#### 利用可能なディメンション（`queryType: "dimension_table"` 用）

| ディメンション              | 説明             |
| -------------------- | -------------- |
| `country`            | 国/地域           |
| `state`              | 都道府県           |
| `os`                 | OS             |
| `osVersion`          | OSのバージョン       |
| `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 キーが紐づくプロファイルと一致する必要があります。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 は `conversionName` 不要（指定しても無視されます）                                                                                                        |
| `metric`         | 条件付き必須 | string    | `metric_curve` タイプで必須 — `completions` / `conversionRate` / `conversionValue`                                                                                                                          |
| `granularity`    | 条件付き必須 | string    | `metric_curve` タイプで必須 — `hour` / `day` / `week` / `month`                                                                                                                                             |
| `filters`        | 任意     | object\[] | 絞り込み条件（セグメント）。§2.1 [Filter](#filter) 参照                                                                                                                                                               |
| `lang`           | 任意     | string    | label / description の言語：`EN`（既定）、`ZH`、`JP`。現状 `queryType = "metrics"` の応答のみ反映。不正値は `EN` にフォールバック                                                                                                      |

#### クエリタイプ

**`metrics` — コンバージョン指標**

5 つの指標を返却：**CV数 / CV率 / CV成果 / ポジティブ / ネガティブ**。各指標は `{ value, label }` として返却、`label` は `lang` フィールドに応じて切り替わります。

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "data": {
        "queryType": "metrics",
        "metrics": {
            "conversions":     { "value": "214",     "label": "CV数" },
            "conversionRate":  { "value": "45.73%",  "label": "CV率" },
            "conversionValue": { "value": "-21,100", "label": "CV成果" },
            "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`（CV率）/ `conversionValue`（CV成果）；`granularity` — `hour` / `day` / `week` / `month`。

**リクエスト例：**

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

**レスポンス例：**

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

**`sources_breakdown` — 流入元別分布**

流入元別のコンバージョン内訳。

**リクエスト例：**

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

**レスポンス例：**

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

**`ad_name_breakdown` — 広告名別分布**

広告名（UTM Campaign）別にコンバージョンを内訳。

**リクエスト例：**

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

**レスポンス例：**

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

**`ad_source_breakdown` — 広告流入元別分布**

広告流入元（UTM Source）別にコンバージョンを内訳。

**リクエスト例：**

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

**レスポンス例：**

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

**`funnel` — ファネル**

各ステップの進入数・離脱数・次ステップへの転化率を返却。

**リクエスト例：**

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

**レスポンス例：**

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

**フィールド説明：**

| フィールド                         | 意味                                              |
| ----------------------------- | ----------------------------------------------- |
| `entries`                     | このステップへの進入数（`external + convert`）               |
| `external`                    | このステップへの外部進入数（前ステップを経由せず直接進入）                   |
| `dropoff`                     | 流出数 = `entries − 次ステップの convert`（最終ステップは 0）     |
| `conversionToNextRate`        | 次ステップへの転化率（最終ステップは `null`）                      |
| `entryPaths`                  | このステップへの外部進入入口 URL 一覧、訪問数の降順                    |
| `dropoffPaths`                | このステップの流出先 URL 一覧、訪問数の降順；追跡不能な流出は `Exit` に集約    |
| `summary.totalConversions`    | ファネル最終到達数（最終ステップの `entries`）                    |
| `summary.totalConversionRate` | 総転化率 = 最終ステップの `entries` / 全ステップの `external` 合計 |

**`regular` — ポジティブ目標一覧**

すべての「ポジティブ」（価値 ≥ 0）コンバージョン目標と各指標を、1 目標 1 行で返却。

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "data": {
        "queryType": "regular",
        "columns": [
            { "name": "conversionName", "type": "dimension", "dataType": "STRING" },
            { "name": "conversions", "type": "metric", "dataType": "INTEGER" },
            { "name": "conversionRate", "type": "metric", "dataType": "RATE" },
            { "name": "revenue", "type": "metric", "dataType": "NUMBER" }
        ],
        "rows": [
            { "conversionName": "ptmind 登録", "conversions": "850", "conversionRate": "6.20%", "revenue": "0" },
            { "conversionName": "ホワイトペーパーDL", "conversions": "130", "conversionRate": "1.00%", "revenue": "0" }
        ]
    }
}
```

**`negative` — ネガティブ目標一覧**

構造は `regular` と同じ。すべての「ネガティブ」（価値 < 0、損失目標）を 1 行 1 目標で返却。各行に追加で `loss` カラム（損失絶対値）。

#### 注意事項

* `conversionName` は `funnel` のみ必須。他の queryType は `conversionName` 不要（指定しても無視されます）。
* `funnel` の `conversionName` は **1 つの目標** に正確にヒット必須。複数ヒット時（例：`"ptmind"` が `"ptmind 登録"` と `"ptmind 購入"` 両方に一致）は 4012 とヒット一覧を返却 — より具体的な名前を使用してください。
* `POST /v1/conversion/goals` で先にすべての目標を取得してからリクエストを構築してください。

***

## 3. Experience

### 3.1 Experience 一覧取得

プロファイル配下のすべての Experience の基本情報（目標とバージョン一覧含む）を返します。後続エンドポイントの `id`、`goalId`、`versionId` はすべてこのエンドポイントの返値から取得します。

#### リクエストパラメータ

| パラメータ       | 必須 | 型      | 説明                                                                                                                        |
| ----------- | -- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `profileId` | 必須 | string | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。Ptengine の URL `https://www.ptengine.jp/app/{profileId}/home` の `566d12f9` 部分など |

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        {
            "id": "6c3bad4b-d953-4088-9fcd-d8cbd976b3a2",
            "name": "春のプロモーションポップアップ",
            "status": "RUNNING",
            "type": "POPUP",
            "goals": [{ "id": "6a8bedde-...", "name": "購入完了" }],
            "versions": [
                { "id": "a2696719-...", "name": "Control" },
                { "id": "b3c8f210-...", "name": "Pattern 1" }
            ]
        }
    ]
}
```

| 返却フィールド    | 説明                                                              |
| ---------- | --------------------------------------------------------------- |
| `id`       | Experience ID。レポートエンドポイントの `id` パラメータ                           |
| `name`     | Experience 名                                                    |
| `status`   | ステータス：`DRAFT` / `RUNNING` / `PAUSE` / `SCHEDULED`               |
| `type`     | タイプ：`POPUP` / `STICKY_BAR` / `INLINE` / `ADVANCED` / `REDIRECT` |
| `goals`    | 目標一覧。A/B テストエンドポイントの `goalId` パラメータ                             |
| `versions` | バージョン一覧。フォームエンドポイントの `versionId` パラメータ                          |

***

### 3.2 ユーザー属性一覧取得

利用可能なユーザー属性一覧を返します。Insight エンドポイントで `dimension="userProperty"` を指定する場合、このエンドポイントから `property` パラメータを取得します。

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        { "name": "plan_name", "displayName": "プラン名", "source": ["code"], "type": "STRING" },
        { "name": "signup_date", "displayName": "登録日", "source": ["default"], "type": "DATE" }
    ]
}
```

***

### 3.3 Experience 概要指標

複数 Experience の指標を一括取得します。

#### リクエストパラメータ

| パラメータ         | 必須 | 型         | 説明                                                                                                                        |
| ------------- | -- | --------- | ------------------------------------------------------------------------------------------------------------------------- |
| `profileId`   | 必須 | string    | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。Ptengine の URL `https://www.ptengine.jp/app/{profileId}/home` の `566d12f9` 部分など |
| `experiences` | 必須 | object\[] | Experience 一覧（`id` + `name`、list エンドポイントから）                                                                               |
| `metrics`     | 任意 | string\[] | 返却する指標フィールド。未指定時は既定全指標。サポートフィールドは下記表                                                                                      |
| `lang`        | 任意 | string    | 返却言語：`EN`（既定）、`ZH`、`JP`                                                                                                   |

**`metrics` サポートフィールド：**

| フィールド                | 説明                               | タイプ     |
| -------------------- | -------------------------------- | ------- |
| `viewedUsers`        | Experience を見たユーザー数              | value   |
| `views`              | Experience の表示回数                 | value   |
| `clickedUsers`       | Experience 内のボタンやリンクをクリックしたユーザー数 | value   |
| `clickRate`          | Experience 内のクリックユーザー比率          | rate    |
| `closedUsers`        | ポップアップやスティッキーバーを閉じたユーザー数         | value   |
| `closeRate`          | ポップアップやスティッキーバーの閉じる比率            | rate    |
| `formSubmittedUsers` | Experience 内のフォーム送信ユーザー数         | value   |
| `formSubmitRate`     | フォーム送信ユーザーの比率                    | rate    |
| `goalReachedUsers`   | Experience を見た後に目標を達成したユーザー数     | value   |
| `goalReachRate`      | Experience を見た後の目標達成比率           | rate    |
| `goalStatus`         | ユーザー比率／属性合計／平均で目標達成状況を表示         | value   |
| `avgVisitDuration`   | Experience を見たユーザーの平均訪問時間        | time    |
| `avgPagesPerVisit`   | Experience を見たユーザーの訪問あたり平均ページ数   | decimal |
| `bounceRate`         | Experience を見た訪問の直帰率             | rate    |
| `lastUpdatedTime`    | Experience の最終更新時間               | text    |
| `lastUpdatedMember`  | 最終更新者                            | text    |
| `createdTime`        | 作成時間                             | text    |
| `createdMember`      | 作成者                              | text    |
| `runningPeriod`      | Experience の運用期間                 | text    |
| `tags`               | Experience のカスタム属性タグ             | text    |

**リクエスト例：**

```bash
curl -X POST https://xbackend.ptengine.com/open-api/v1/experience/report/overview \
  -H "Content-Type: application/json" \
  -H "x-api-key: pt-your-api-key" \
  -d '{
    "profileId": "566d12f9",
    "experiences": [
      { "id": "6c3bad4b-...", "name": "春のプロモーションポップアップ" },
      { "id": "5bb77b97-...", "name": "登録ガイド" }
    ],
    "metrics": ["viewedUsers", "clickRate", "bounceRate"],
    "lang": "JP"
  }'
```

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        {
            "name": "春のプロモーションポップアップ",
            "viewedUsers": { "value": 100, "label": "表示ユーザー数", "description": "Experience を見たユーザー数。" },
            "clickRate": { "value": "5.00%", "label": "クリック率", "description": "Experience 内のクリックユーザー比率。" },
            "bounceRate": { "value": "42.86%", "label": "直帰率", "description": "Experience を見た訪問の直帰率。" }
        }
    ]
}
```

> すべての指標は `{ value, label, description }` 構造で返却。`label` と `description` は `lang` に応じた言語で返却。

***

### 3.4 主要指標

単一 Experience の総合指標を取得します。

#### リクエストパラメータ

| パラメータ       | 必須 | 型      | 説明                                                                                                                        |
| ----------- | -- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `profileId` | 必須 | string | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。Ptengine の URL `https://www.ptengine.jp/app/{profileId}/home` の `566d12f9` 部分など |
| `id`        | 必須 | string | Experience ID（list エンドポイントから）                                                                                             |
| `startDate` | 必須 | string | 開始日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |
| `endDate`   | 必須 | string | 終了日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |
| `lang`      | 任意 | string | label/description の言語：`EN`（既定）、`ZH`、`JP`                                                                                  |

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "春のプロモーションポップアップ",
        "items": [
            {
                "viewedUsers": { "value": 100, "label": "表示ユーザー数", "description": "..." },
                "views": { "value": 300, "label": "表示回数", "description": "..." },
                "clickedUsers": { "value": 50, "label": "クリックユーザー数", "description": "..." },
                "clickRate": { "value": "41.67%", "label": "クリック率", "description": "..." },
                "goals": [
                    {
                        "name": "購入完了",
                        "reachedUsers": { "value": 5, "label": "目標達成ユーザー数", "description": "..." },
                        "reachRate": { "value": "5.00%", "label": "目標達成率", "description": "..." },
                        "value": { "value": null, "label": "目標達成状況", "description": "..." }
                    }
                ],
                "avgVisitDuration": { "value": "06:33", "label": "平均訪問時間", "description": "..." },
                "avgPagesPerVisit": { "value": "2.50", "label": "平均訪問ページ数", "description": "..." },
                "bounceRate": { "value": "42.86%", "label": "直帰率", "description": "..." }
            }
        ]
    }
}
```

> **注：** 返却される指標は Experience タイプにより自動的にフィルタされます。例：INLINE タイプは `clickedUsers` / `closedUsers` を返却せず、フォームのない Experience は `formSubmittedUsers` を返却しません。

***

### 3.5 セグメント詳細

単一 Experience の指標をディメンション別グループで取得します。

#### リクエストパラメータ

| パラメータ          | 必須     | 型                                                            | 説明                                                                                                                        |
| -------------- | ------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `profileId`    | 必須     | string                                                       | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。Ptengine の URL `https://www.ptengine.jp/app/{profileId}/home` の `566d12f9` 部分など |
| `id`           | 必須     | string                                                       | Experience ID（list エンドポイントから）                                                                                             |
| `startDate`    | 必須     | string                                                       | 開始日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |
| `endDate`      | 必須     | string                                                       | 終了日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |
| `dimension`    | 必須     | string                                                       | 主ディメンション。下記表参照                                                                                                            |
| `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` を渡す必要があります：

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

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "春のプロモーションポップアップ",
        "items": [
            {
                "name": "PC",
                "subName": "新規訪問",
                "viewedUsers": { "value": 80, "label": "表示ユーザー数", "description": "..." },
                "bounceRate": { "value": "38.00%", "label": "直帰率", "description": "..." }
            },
            {
                "name": "モバイル",
                "subName": "再訪問",
                "viewedUsers": { "value": 20, "label": "表示ユーザー数", "description": "..." },
                "bounceRate": { "value": "55.00%", "label": "直帰率", "description": "..." }
            }
        ]
    }
}
```

***

### 3.6 A/B テストの結果

A/B テストで各バージョンの指標比較（uplift と勝率を含む）。

#### リクエストパラメータ

| パラメータ                 | 必須     | 型                                                         | 説明                                                                                                                        |
| --------------------- | ------ | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `profileId`           | 必須     | string                                                    | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。Ptengine の URL `https://www.ptengine.jp/app/{profileId}/home` の `566d12f9` 部分など |
| `id`                  | 必須     | string                                                    | Experience ID（list エンドポイントから）                                                                                             |
| `startDate`           | 必須     | string                                                    | 開始日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |
| `endDate`             | 必須     | string                                                    | 終了日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |
| `compareBy`           | 必須     | string                                                    | バージョン比較の基準指標。下記参照                                                                                                         |
| `goalId`              | 条件付き必須 | `compareBy="goalReached"` の場合必須（list エンドポイントの goals から取得） |                                                                                                                           |
| `showDeletedVersions` | 任意     | 削除済みバージョンを含むか。既定 false                                    |                                                                                                                           |
| `lang`                | 任意     | 返却言語                                                      |                                                                                                                           |

**`compareBy` 許容値：**

| compareBy            | 説明                               |
| -------------------- | -------------------------------- |
| `viewedUsers`        | Experience を見たユーザー数              |
| `clickedUsers`       | Experience 内のボタンやリンクをクリックしたユーザー数 |
| `closedUsers`        | ポップアップやスティッキーバーを閉じたユーザー数         |
| `formSubmittedUsers` | フォーム送信ユーザー数                      |
| `goalReached`        | 目標達成（`goalId` 必須）                |
| `avgVisitDuration`   | Experience を見たユーザーの平均訪問時間        |
| `avgPagesPerVisit`   | 訪問あたり平均ページ数                      |
| `bounceRate`         | Experience を見た訪問の直帰率             |

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "春のプロモーションポップアップ",
        "items": [
            {
                "name": "Control",
                "viewedUsers": { "value": 50, "label": "表示ユーザー数", "description": "..." },
                "goalReachedUsers": { "value": 5, "label": "目標達成ユーザー数", "description": "..." },
                "goalReachRate": { "value": "10.00%", "label": "目標達成率", "description": "..." },
                "uplift": { "value": "Baseline", "label": "上昇率", "description": "..." },
                "probabilityToBeBest": { "value": null, "label": "勝率", "description": "..." }
            },
            {
                "name": "Pattern 1",
                "viewedUsers": { "value": 50, "label": "表示ユーザー数", "description": "..." },
                "goalReachedUsers": { "value": 8, "label": "目標達成ユーザー数", "description": "..." },
                "goalReachRate": { "value": "16.00%", "label": "目標達成率", "description": "..." },
                "uplift": { "value": "+60.00%", "label": "上昇率", "description": "..." },
                "probabilityToBeBest": { "value": "85.30%", "label": "勝率", "description": "..." }
            }
        ]
    }
}
```

> * レスポンスには `compareBy` に対応する指標 + `uplift` + `probabilityToBeBest` のみが含まれます。
> * ベースラインバージョンの `uplift` は `"Baseline"`。他バージョンはパーセンテージ（例：`"+50.00%"` または `"-10.00%"`）。

***

### 3.7 A/B テストの結果 — セグメント詳細

A/B テストで各バージョンの指標比較をディメンション別にグループ。

#### リクエストパラメータ

| パラメータ                 | 必須     | 型       | 説明                                                                                                                        |
| --------------------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `profileId`           | 必須     | string  | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。Ptengine の URL `https://www.ptengine.jp/app/{profileId}/home` の `566d12f9` 部分など |
| `id`                  | 必須     | string  | Experience ID（list エンドポイントから）                                                                                             |
| `startDate`           | 必須     | string  | 開始日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |
| `endDate`             | 必須     | string  | 終了日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |
| `compareBy`           | 必須     | string  | 比較指標（3.6 と同じ）                                                                                                             |
| `goalId`              | 条件付き必須 | string  | `compareBy="goalReached"` の場合必須                                                                                           |
| `dimension`           | 必須     | string  | 主ディメンション（3.5 と同じ）                                                                                                         |
| `subDimension`        | 任意     | string  | 副ディメンション                                                                                                                  |
| `property`            | 条件付き必須 | object  | `dimension="userProperty"` の場合必須                                                                                          |
| `showDeletedVersions` | 任意     | boolean | 削除済みバージョンを含むか。既定 false                                                                                                    |
| `lang`                | 任意     | string  | label/description の言語：`EN`（既定）、`ZH`、`JP`                                                                                  |

**リクエスト例：**

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

**レスポンス例：**

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "experienceName": "春のプロモーションポップアップ",
        "items": [
            {
                "name": "PC",
                "versions": [
                    {
                        "name": "全バージョン",
                        "viewedUsers": { "value": 40, "label": "表示ユーザー数", "description": "..." },
                        "uplift": { "value": "Baseline", "label": "上昇率", "description": "..." }
                    },
                    {
                        "name": "Control",
                        "viewedUsers": { "value": 20, "label": "表示ユーザー数", "description": "..." },
                        "uplift": { "value": "Baseline", "label": "上昇率", "description": "..." }
                    },
                    {
                        "name": "Pattern 1",
                        "viewedUsers": { "value": 20, "label": "表示ユーザー数", "description": "..." },
                        "uplift": { "value": "+30.00%", "label": "上昇率", "description": "..." }
                    }
                ]
            }
        ]
    }
}
```

***

### 3.8 フォーム送信

特定バージョンのフォーム送信詳細データを取得します。

#### リクエストパラメータ

| パラメータ       | 必須 | 型      | 説明                                                                                                                        |
| ----------- | -- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `profileId` | 必須 | string | サイト ID（8 文字）。API キーが紐づくプロファイルと一致する必要があります。Ptengine の URL `https://www.ptengine.jp/app/{profileId}/home` の `566d12f9` 部分など |
| `id`        | 必須 | string | Experience ID（list エンドポイントから）                                                                                             |
| `versionId` | 必須 | string | バージョン ID（list エンドポイントの versions から）                                                                                       |
| `startDate` | 必須 | string | 開始日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |
| `endDate`   | 必須 | string | 終了日。形式：`YYYY-MM-DD` または `YYYY/MM/DD`                                                                                      |

**リクエスト例：**

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

**レスポンス例：**

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

> * `columns` は動的、フォームの実際のフィールドから自動生成。
> * `rows` の各行は 1 件の送信。値のないフィールドは空文字列。

***

### 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`    | パーセンテージ | 閉じる率      |

#### フォーム系指標（フォーム設定済み Experience）

| フィールド                | 形式      | 説明          |
| -------------------- | ------- | ----------- |
| `formSubmittedUsers` | 数値      | フォーム送信ユーザー数 |
| `formSubmitRate`     | パーセンテージ | フォーム送信率     |

#### 目標データ

| フィールド                  | 説明                       |
| ---------------------- | ------------------------ |
| `goals[].name`         | 目標名                      |
| `goals[].reachedUsers` | 達成ユーザー数                  |
| `goals[].reachRate`    | 達成率                      |
| `goals[].value`        | 達成価値（null = ユーザー比率でカウント） |

***

## 付録

### A. エラーコード

| コード    | HTTP ステータス | 説明                                                                                                                                       |
| ------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `4010` | 401        | リクエストヘッダーに `x-api-key` がない                                                                                                               |
| `4011` | 401        | API キーが無効                                                                                                                                |
| `4030` | 403        | `profileId` が API キーに紐づくプロファイルと一致しない                                                                                                     |
| `4031` | 403        | API キーにクエリ権限がない（scope: `query` が必要）                                                                                                      |
| `4001` | 400        | 無効な `queryType`                                                                                                                          |
| `4002` | 400        | 日付形式エラー。`YYYY-MM-DD` または `YYYY/MM/DD` である必要があります                                                                                         |
| `4003` | 400        | クエリ日付がプランのデータ保持期限を超過                                                                                                                     |
| `4006` | 400        | `page_insight` タイプは `funName` 必須                                                                                                         |
| `4007` | 400        | `block_metrics` は特定の deviceType（PC/MOBILE/TABLET）が必要、ALL は不可                                                                             |
| `4008` | 400        | ページブロック未設定。先に Ptengine でページをスキャンしてください                                                                                                   |
| `4009` | 400        | `element_metrics` は特定の deviceType（PC/MOBILE/TABLET）が必要、ALL は不可                                                                           |
| `4012` | 400        | 一致するコンバージョン目標がない                                                                                                                         |
| `4013` | 400        | 必須フィールドが欠落（レスポンスメッセージで具体名を提示）                                                                                                            |
| `4014` | 400        | `deviceType` が無効。`ALL`、`PC`、`MOBILE`、`TABLET` のいずれか必須                                                                                    |
| `4015` | 400        | `dimension` / `subDimension` が無効（レスポンスメッセージで詳細を提示）                                                                                       |
| `4016` | 400        | ページ要素未設定。先に Ptengine でページをスキャンしてください                                                                                                     |
| `4017` | 400        | `compareBy` が無効（レスポンスメッセージで許容値を列挙）                                                                                                       |
| `4018` | 400        | フィールド不正（`/event/query` / `/insight/query` / `/conversion/query`：dimension / metric / queryType / topic / granularity が許容外、またはディメンション数超過） |
| `4019` | 400        | filter 演算子または値が不正（`include`/`exclude` 必須；`value` は空でない配列必須；sortOrder/limit が範囲外）                                                         |
| `4040` | 404        | Experience が見つからない（`id` がプロファイル下に存在しない）                                                                                                  |
| `4290` | 429        | リクエストレート超過（毎分）                                                                                                                           |
| `4291` | 429        | リクエストレート超過（毎日）                                                                                                                           |
| `5000` | 500        | サーバ内部エラー                                                                                                                                 |

`message` はリクエストの `lang`（body または query）に応じた言語（EN/ZH/JP）で返却。未指定または不正値の場合は英語にフォールバック。


---

# Agent Instructions: Querying This Documentation

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

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

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

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

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