予約に関する質問
「予約に関する質問」機能により、旅行者に関する追加情報の収集が容易になります
早期アクセスプレビュー
このドキュメントは、選定されたパートナーのみを対象とした早期アクセスプレビュー・イニシアチブの一環です。ベータ版プログラムは2026年第3四半期に開始され、2027年に一般提供が開始される予定です。
ベータパートナーになることにご興味をお持ちの方は、アカウントマ ネージャー までご連絡ください。
概要
「予約に関する質問」機能により、旅行者に関する追加情報(e.g. 身長、体重、旅行書類の情報、食事制限など)を、柔軟かつtype-safeな方法で収集することができます。
主なメリット
- 柔軟性: APIのバージョン管理なしで新しいデータ型を追加できます
- Type-safe: JSONスキーマは、正しい構造を保証します
- 検索可能: カタログエンドポイントを通じて利用可能なタイプを照会する機能
- フィルタリング済み: 支援可能なアクティビティのみが表示されます
- ローカライズ済み: 質問は複数の言語に対応しています
本文書用語集
- ソリューションアーキテクチャ
中核となる概念、汎用データ型モデル、アクティビティ要件、パートナーの機能、および構造化された回答の提出。 - 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レスポンスの例 :
{
"data_types": [
{
"type": "measurement",
"name": "Size Measurement",
"description": "Used for collecting dimensional measurements. Common examples include height, helmet size, waist size, and chest size.",
"date_added": "2023-09-20",
"schema_definition": {
"additionalProp1": {}
},
"validation_rules_options": {
"number": [
"min_length",
"max_length",
"pattern"
]
}
}
],
"validation_rules": {
"max_length": {
"description": "Maximum length of the string value, measured in Unicode code points.",
"type": "integer"
},
"pattern": {
"description": "A regular expression that the entire string value must match.",
"type": "string"
}
}
}アクティビティのフィルタリング
クエリパラメータ: 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-01date_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に関するご質問は、1回まとめてお寄せください
- 条件付き質問の処理(親の回答に基づいて表示/非表示にする)
ステップ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は、回答の提出に一貫性を持たせるため、言語を問わず同一のままとなります。
検証
Client-side検証
パートナーの皆様は、データ型カタログのスキーマを使用して、client-sideの回答を検証し、構造が正しいことを確認してください。
Server-side検証
予約エンドポイントは、以下の点を検証します:
- 必須の質問にはすべて回答が記載されています
- 回答の構造がデータ型のスキーマと一致しています
- 値が検証制約を満たしています
- 条件付きの質問には適切に答えます
- 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
}
]
}
]
}