予約に関する質問

「予約に関する質問」機能により、旅行者に関する追加情報の収集が容易になります

早期アクセスプレビュー

このドキュメントは、選定されたパートナーのみを対象とした早期アクセスプレビュー・イニシアチブの一環です。ベータ版プログラムは2026年第3四半期に開始され、2027年に一般提供が開始される予定です。

ベータパートナーになることにご興味をお持ちの方は、アカウントマネージャーまでご連絡ください。

概要

「予約に関する質問」機能により、旅行者の追加情報（e.g. 身長、体重、旅行書類の情報、食事制限など）を、柔軟かつtype-safeな方法で収集することができます。

主なメリット

柔軟性： APIのバージョン管理なしで新しいデータ型を追加できます
Type-safe: JSONスキーマは、正しい構造を保証します
検索可能：カタログエンドポイントを通じて利用可能なタイプを照会する機能
フィルタリング済み：支援可能なアクティビティのみが表示されます
ローカライズ済み： Questionsは多言語に対応しています

本文書の用語集

ソリューションアーキテクチャ
中核となる概念、汎用データ型モデル、アクティビティ要件、パートナーの機能、および構造化された回答の提出。
APIエンドポイント
「データタイプカタログ」、「アクティビティのフィルタリング」、および「価格確認」のエンドポイントでは、予約に関する質問が提供されています。
条件付き質問
親子質問の仕組みと、表示・非表示のロジックを制御する演算子について。
連携フロー
End-to-end発見から予約送信までの各ステップ。
データ型の例
スキーマ定義と回答構造を示すデータ型のサンプルです。
ローカライズ
IDを変更せずに、質問や選択肢を複数の言語で返す方法。
検証
Client-sideおよびserver-sideに、検証ルールとエラー応答の形式が記載されています。

ソリューションアーキテクチャ

基本概念

汎用データ型モデル

再利用可能なデータ型モデルは、情報のカテゴリを表しています（必要に応じて追加することも可能です）。e.g. 測定値、選択項目、住所、電話番号などです。

>> データ型モデルについて詳しくはこちら

data-typesの全カタログをご覧になりたい場合は、お電話ください GET /experiences/booking-questions/data-types

活動要件

アクティビティは、予約時の質問を通じて、必要なデータ型を次のように指定します：

その質問に割り当てられた一意の文字列ID
質問文（ローカライズ版）
質問文の説明（ローカライズ版）
データ型のリファレンス
per-travelerを適用するかどうか、あるいはper-booking
検証制約（最小値・最大値、長さなど）
対象となるチケット
指定された親に対する子質問を定義します
オプションの条件分岐ロジック（他の回答によって変わる質問）

パートナーの機能

検索およびコンテンツのエンドポイントにおいて、supported_booking_data_types フィルターパラメータを使用して、サポートするデータ型を指定します。これにより、自分が対応できるアクティビティのみが表示されるようになります。

の任意の型を動的に処理するには、supported_booking_data_types=* を送信してください。
のサポートや、に関するご予約に関するご質問は、supported_booking_data_types=none までお問い合わせください。

回答の体系的な提出

回答は適切にネストされています：

Per-traveler への回答 — 各旅行者オブジェクトの配列内にあります。booking_question_answers
Per-booking回答： — 予約レベルのbooking_question_answers 配列内です。

APIエンドポイント

データ型のカタログを取得する

エンドポイント： GET /experiences/booking-questions/data-types

クエリパラメータ： ?date_updated_start

>> ご利用方法については、「統合フロー：ステップ1」をご覧ください

目的：利用可能なすべてのデータ型モデルの技術リファレンスカタログを返します。

リクエストの例 :

GET /experiences/booking-questions/data-types

レスポンスの例 :

[
    {
      "date_added": "2026-07-14T11:30:08.104575+02:00",
      "date_updated": "2026-07-14T11:30:08.104575+02:00",
      "description": "Used for collecting any measurement with a numeric value and unit. Common examples include height (in/cm/foot/meter), weight (lb/kg/stone), shoe size (us_men/us_women/eu/uk/cm), helmet size (in/cm), waist size (in/cm), and chest size (in/cm). The allowed_units field specifies which units are valid for this measurement.",
      "name": "Measurement",
      "schema_definition": {
        "properties": {
          "unit": {
            "description": "Unit of measurement - must be one of the allowed_options specified for the question",
            "type": "string"
          },
          "value": {
            "description": "Numeric value as string to preserve precision",
            "pattern": "^[0-9]+(\\.[0-9]+)?$",
            "type": "string"
          }
        },
        "required": [
          "value",
          "unit"
        ],
        "type": "object"
      },
      "type": "measurement"
    },
]

アクティビティのフィルタリング

クエリパラメータ： supported_booking_data_types

対象： /experiences/activities/content および/experiences/activities/availability のエンドポイント

目的：指定されたデータ型が必須質問で使用されているアクティビティのみを結果に含めるようにフィルタリングします。

例 :

GET /experiences/activities/content
  ?activity_id=123&activity_id=456
  &language=en-US
  &supported_booking_data_types=measurement
  &supported_booking_data_types=selection
  &supported_booking_data_types=text

すべてのタイプを処理し、すべてのアクティビティを表示するには、supported_booking_data_types=* を使用してください。その場合、お客様は「価格確認」および「予約」におけるすべての質問タイプへの対応を担当していただくことになります。
予約に関するお問い合わせ以外については、supported_booking_data_types=none をご利用ください。これにより、予約に関する質問がないアクティビティのみが返されます。

料金確認（ご予約に関する質問を含みます）

エンドポイント： GET /experiences/activities/{activity_id}/price-check

目的：は、価格の確認を行い、そのアクティビティに関する予約に関する質問（ある場合）を返します。

リクエストの例 :

GET /experiences/activities/12345/price-check?token=abc123&tickets=...

レスポンスの例 :

{
  "status": "available",
  "offer_pricing": {
    "total": {
      "value": "150.00",
      "currency": "USD"
    }
  },
  "booking_questions": [
    {
      "id": "height_1",
      "type": "measurement",
      "question": "What is your height?",
      "description": "Required for safety equipment fitting",
      "applies_to": "per_traveler",
      "ticket_ids": ["12346","12345"]
      "allowed_options": [
        { "id": "in", "label": "in" },
        { "id": "cm", "label": "cm" }
      ]
    },
    {
      "id": "weight_1",
      "type": "measurement",
      "question": "What is your weight?",
      "description": "Required for zipline weight limits",
      "applies_to": "per_traveler",
      "ticket_ids": ["12346","12345"]
      "allowed_options": [
        { "id": "lb", "label": "lb" },
        { "id": "kg", "label": "kg" }
      ]
    }
  ],
  "links": {
    "create": {
      "method": "POST",
      "href": "/itineraries/activity"
    }
  }
}

注：以前の検索やコンテンツの呼び出しで、supported_booking_data_types を使用してアクティビティをフィルタリングした場合、返されるすべての質問には、サポートされているデータ型が使用されます。

条件付きの質問

質問は、前の質問への回答に応じて条件付きになる場合があります。これは、ユーザーの選択に応じてさまざまな情報を収集するのに役立ちます。

仕組み

親の質問 — その回答によってその後の展開が決まる質問（通常は「selection」形式の質問）です。
子クエリ — 親を参照する「conditional」フィールドを持つクエリです。
双方向の関係 — 親はchildren 配列に子を一覧表示し、子は完全な条件分岐ロジックを用いて親を参照します。

例：連絡方法の選択

保護者からの質問：

{
  "id": "contact_method_1",
  "type": "selection",
  "question": "How would you prefer to be contacted?",
  "applies_to": "per_traveler",
  "ticket_ids": ["12346","12345"]
  "children": ["contact_phone_1", "contact_whatsapp_1", "contact_email_1"],
  "allow_multiple": false,
  "allowed_options": [
    { "id": "phone", "label": "Phone Call" },
    { "id": "whatsapp", "label": "WhatsApp" },
    { "id": "email", "label": "Email" },
    { "id": "no_contact", "label": "No Contact" }
  ]
}

条件付きの子質問：

[
  {
    "id": "contact_phone_1",
    "type": "phone",
    "question": "What is your phone number?",
    "applies_to": "per_traveler",
    "conditional": {
      "parent_question_id": "contact_method_1",
      "show_when": {
        "operator": "equals",
        "field": "selected",
        "values": ["phone"]
      }
    }
  },
  {
    "id": "contact_whatsapp_1",
    "type": "text",
    "question": "What is your WhatsApp username?",
    "applies_to": "per_traveler",
    "conditional": {
      "parent_question_id": "contact_method_1",
      "show_when": {
        "operator": "equals",
        "field": "selected",
        "values": ["whatsapp"]
      }
    }
  },
  {
    "id": "contact_email_1",
    "type": "email",
    "question": "What is your email address?",
    "applies_to": "per_traveler",
    "conditional": {
      "parent_question_id": "contact_method_1",
      "show_when": {
        "operator": "equals",
        "field": "selected",
        "values": ["email"]
      }
    }
  }
]

条件演算子

オペレーター	意味
`contains`	そのフィールドには、指定された値のいずれかが含まれています
`equals`	そのフィールドは、指定された値のいずれかと完全に一致します
`not_contains`	このフィールドには、指定された値は含まれていません
`not_equals`	このフィールドは、指定された値のいずれとも一致しません

統合フロー

ステップ1：ディスカバリーフェーズ

サポート可能なデータ型を確認するには、データ型カタログを呼び出してください：

GET /experiences/booking-questions/data-types?date_updated_start=2026-02-01

date_updated_startが指定された場合、指定された日付以降に追加されたデータ型のみが返されます。

ステップ2：フィルタリング機能を使った検索

互換性のある質問を含むアクティビティのみを表示するようにフィルタリングします：

GET /experiences/activities/content
  ?activity_id=123&activity_id=456&activity_id=789
  &language=en-US
  &supported_booking_data_types=measurement
  &supported_booking_data_types=selection
  &supported_booking_data_types=text

これにより、指定されたデータ型が必須の質問に使用されているアクティビティのみが検索結果に表示されます。

ステップ3：価格の確認

料金確認の際、返信に予約に関する質問が含まれています：

GET /experiences/activities/12345/price-check?token=abc123&tickets=...

レスポンスには、booking_questions 配列（存在する場合）が含まれます。すべての質問では、フィルターで指定されたデータ型が使用されます。

ステップ4：回答を集める

回答を収集するためのUIを構築します：

各データ型に応じて適切な入力を生成してください
データ型カタログのスキーマを使用して、client-sideの妥当性を検証してください
「per-traveler」に関する質問については、旅行者ごとに回答を集めてください
per-bookingに関するご質問は、一度まとめてお寄せください
条件付き質問の処理（親の回答に基づいて表示／非表示を切り替える）

ステップ5：予約を送信する

ご予約のお申し込みとともに、回答をご提出ください：

POST /itineraries/activity

{
  "primary_traveler": [
    {
      "given_name": "John",
      "family_name": "Doe",
      "booking_question_answers": [
        {
          "question_id": "height_1",
          "answer": {
            "value": "72",
            "unit": "in"
          }
        },
        {
          "question_id": "weight_1",
          "answer": {
            "value": "180",
            "unit": "lb"
          }
        }
      ]
    }
  ],
  "booking_question_answers": [
    {
      "question_id": "emergency_contact_1",
      "answer": {
        "value": "Jane Doe, +1-555-1234"
      }
    }
  ]
}

データ型の例

サイズ（寸法）

スキーマ定義：

{
  "type": "object",
  "required": ["value", "unit"],
  "properties": {
    "value": {
      "type": "string",
      "pattern": "^[0-9]+(\\.[0-9]+)?$"
    },
    "unit": {
      "type": "string"
    }
  }
}

回答例：

{
  "value": "72",
  "unit": "in"
}

ローカライズ

Price Checkのlanguage パラメータにより、質問は複数の言語に対応しています。

英語の例：

GET /experiences/activities/12345/price-check?token=...&language=en-US

{
  "id": "dietary_1",
  "type": "selection",
  "question": "Dietary preferences (optional)",
  "description": "Please share any dietary restrictions or allergies."
  "applies_to": "per_traveler",
  "allow_multiple": false
  "ticket_ids": ["12345", "12346"]
  "options": [
    { "id": "vegetarian", "label": "Vegetarian" },
    { "id": "vegan", "label": "Vegan" }
  ]
}

スペイン語の例：

. についても同じ質問ですlanguage=es-ES。

GET /experiences/activities/12345/price-check?token=...&language=es-ES

{
  "id": "dietary_1",
  "type": "selection",
  "question": "Preferencias alimentarias (opcional)",
  "description": "Por favor, indica las restricciones alimentarias o alergias. "
  "applies_to": "per_traveler",
  "allow_multiple": false
  "ticket_ids": ["12345", "12346"]
  "options": [
    { "id": "vegetarian", "label": "Vegetariano" },
    { "id": "vegan", "label": "Vegano" }
  ]
}

注：の質問IDおよび選択肢IDは、回答の提出に一貫性を持たせるため、言語を問わず同一のままとなります。

必須の質問にはすべて回答があります
回答の構造がデータ型のスキーマと一致しています
値が検証制約を満たしています
条件付きの質問には適切に回答されます
Per-traveler旅行者一人ひとりに質問が用意されています
Per-booking問題は一度だけ提示されます

エラーレスポンス

{
  "type": "validation_failed",
  "message": "One or more booking question answers are invalid",
  "errors": [
    {
      "type": "missing_required_answer",
      "message": "Required question 'height_1' not answered for traveler 1",
      "fields": [
        {
          "path": "$.travelers[0].booking_question_answers",
          "value": null
        }
      ]
    }
  ]
}