クエリ メッセージは、料金やメタデータの更新に関する Google からのリクエストです。これらは、プル型と変更済み料金の両方の配信モードで使用されます。
クエリ メッセージのルート要素は <Query>
です。
クエリ メッセージの構造は、メッセージの種類によって異なります。
料金設定: Google は、指定されたホテルの料金の更新をリクエストするクエリ メッセージを送信します。
メタデータ: Google は、指定されたホテルの客室とパッケージの情報に関するデータをリクエストするクエリ メッセージを送信します。
Google がクエリ メッセージとライブ料金クエリに使用するエンドポイントを、初期構成時に定義します。詳細については、テクニカル アカウント マネージャー(TAM)にお問い合わせください。
Google は、Content-Type
ヘッダーを「application/xml」に、User-Agent
ヘッダーを Google-HotelAdsPrices
に設定した HTTP POST
リクエストとしてクエリ メッセージを送信します。このルールの例外は、Google-TravelAds-Live
による価格エンドポイントの統合の手動テスト中に発生します。これらのサンプルクエリには、User-Agent
ヘッダーが含まれている場合があります。
クエリ メッセージの詳細な形式については、クエリ XML リファレンスをご覧ください。
料金クエリ メッセージ
料金クエリ メッセージでは、料金を指定する宿泊施設または旅行プランの組み合わせを指定します。
サーバーは、料金クエリ メッセージを受信すると、要求された料金情報を含む <Transaction>
メッセージを返す必要があります。pricing
詳細については、料金の概要をご覧ください。
クエリ メッセージには、次の 3 つの特別なタイプがあります。
ライブ料金: 有効にすると、ユーザーが指定された宿泊施設または旅行プランの組み合わせの料金を積極的に閲覧し、回答期限が指定された場合にクエリが送信されます。
コンテキストあり: 有効にすると、Google が送信する各クエリにユーザー コンテキストのレコメンデーションが含まれ、レコメンデーションは特定の宿泊施設または旅行プランの組み合わせを検索する最も一般的なタイプのユーザーを反映します。これらの推奨事項に従うと、レスポンスの効率が向上する場合があります。
メタデータ: 指定された宿泊施設の客室とパッケージの詳細に対するリクエストです。
ライブ料金のクエリ
ライブ料金クエリは、ユーザーの検索に応じて Google からリアルタイムで料金を更新するためのリクエストです。Google は、ユーザーからホテルまたは旅行プランの組み合わせの検索リクエストを受け取り、料金データが存在しないか最新ではないことから、検索の時点で料金の更新をリクエストします。ライブ料金クエリでは、Google が料金を取得し、検索時に結果に表示しようとします。
すべてのライブ料金クエリ リクエストには、通常最大 4,000 ミリ秒の応答時間の上限があります。この上限は、ライブ料金クエリ リクエストで指定します。制限時間内に応答できない場合、特定の機会に参加できなくなります。ただし、キャッシュに保存して将来の機会に使用できるように、価格を指定することをおすすめします。レスポンスの接続は 10 分間、またはパートナーの構成で指定されたとおりに開いたままになります。
ライブ料金クエリもコンテキストに依存し、ユーザーの国、デバイスタイプ、定員(ゲストの人数)、それらのゲストが大人か子供かというパラメータで料金を取得できます。ライブ料金クエリを使用すると、ユーザーの検索内容に一致する最新の料金を表示できます。
ライブ料金クエリは、料金更新の二次的なメカニズムとして使用することを目的としています。料金変更を行う主な方法は、引き続きプル型料金または変更済み料金を使用することです。ライブ料金クエリは、Google がホテルまたは旅行プランの組み合わせの料金を保持していない場合に役立ちます。
ライブ料金クエリの使用に関するルール
指定された旅行プランのキャッシュ データは存在しません。これは、日付がかなり先の日付である、またはホテルの検索頻度が非常に低いなど、要求された旅行プランが一般的ではないためです。
リクエストした日付がデフォルト以外の日付である。
: 注: デフォルトの日付はライブ料金クエリの対象外です。ライブ料金クエリは、デフォルト以外の日付に対してのみリクエストされます。
Google は通常、ライブ料金の結果をキャッシュに保存して、同じホテルや旅行プランが再度クエリされないようにします。1 つのホテルまたは 1 つの旅行プランの組み合わせ、複数のホテルまたは 1 つの旅行プランの組み合わせをリクエストできます。
コンテキストに基づくライブ料金機能を使用すると、Google は、ユーザーのデバイスタイプ、検索元の国、子供を含む宿泊人数に基づいて、特定のライブ料金リクエストを送信できます。クエリ メッセージとトランザクション メッセージの両方が展開され、クエリ パラメータを定義する <Context>
要素が追加されます。コンテキスト付きのライブ料金クエリから受け取った料金は、特定の宿泊人数に対する料金の場合は条件の組み合わせとして、ユーザーの国またはユーザー デバイス向けの場合は限定価格としてキャッシュに保存できます。
コンテキスト クエリを使用
コンテキスト クエリは、指定された宿泊施設や旅行プランの組み合わせでデータベースを更新する定期的なリクエストです。コンテナには、これらの組み合わせでよく利用されるユーザー コンテキストのリストが含まれています。限定価格を使用する場合、想定されるすべてのユーザー コンテキストに対して料金を送信するとコストが高くなる可能性があります。そのため、このユーザー コンテキストのリストを使用してレスポンスを制限できます。指定されたユーザー コンテキストに対してのみ料金を返すことで、関連するユーザークエリの大部分をカバーできます。
メタデータ クエリ メッセージ
メタデータ クエリ メッセージには、指定されたプロパティの客室とパッケージに関する情報が含まれます。
メタデータ クエリ メッセージを受信したら、<Result>
要素でリクエストされた宿泊施設の料金を指定する <Transaction>
メッセージで応答する必要があります。
詳しくは、客室とパッケージのメタデータの定義をご覧ください。
制御クエリ
このセクションでは、Google からの Query メッセージの件名にする宿泊施設と旅行プランを管理する方法について説明します。
旅程の境界線
料金クエリの境界は、<ItineraryCapabilities>
を使用して決定します。サポートする日付の範囲と最長滞在日数を決定するルールを定義します。
<MaxAdvancePurchase>
と <MaxLengthOfStay>
には、ホテルまたは旅行プランのすべての組み合わせに適用されるデフォルト値を設定できます。ホテルのグループに対して設定を定義することもできます。
クエリ メッセージの例
このセクションでは、料金クエリ メッセージとメタデータ クエリ メッセージの例をいくつか示します。その他の例については、クエリ XML リファレンスをご覧ください。
旅行プランの例
次の例は、2023 年 5 月 23 日から 3 泊分の 4 軒のホテルの料金更新データをリクエストする料金 <Query>
を示しています。
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<Checkin>2023-05-23</Checkin>
<Nights>3</Nights>
<PropertyList>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</PropertyList>
</Query>
次の例では、各ホテルの料金の更新をリクエストします。
5/23/18 - 6/26/18
ライブ料金クエリの例
次の例は、レスポンス時間の上限が 500 ミリ秒のライブ料金クエリを示しています。
<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
<!-- Note that the latencySensitive attribute is not present by default but can
be configured to be displayed, on request, by Google. This attribute is only
displayed for a Live Pricing Query request -->
<Checkin>2023-05-23</Checkin>
<Nights>2</Nights>
<DeadlineMs>500</DeadlineMs>
<!-- The deadline represents the timeframe by which a response will need to be
received by. This element is only displayed for a Live Pricing Query request -->
<PropertyList>
<Property>6781291</Property>
</PropertyList>
<!-- Note that Context tags are potentially repeatable -->
<Context>
<!-- The total number of guests occupying the room (adults+children) -->
<Occupancy>3</Occupancy>
<OccupancyDetails>
<NumAdults>2</NumAdults>
<!-- In this example one of the 3 guests is a 5yr old child -->
<Children>
<Child age="5"/>
</Children>
</OccupancyDetails>
<!-- The user was located in the US when this search was made -->
<UserCountry>US</UserCountry>
<!-- The user was searching from a mobile device at the time of search -->
<UserDevice>mobile</UserDevice>
</Context>
</Query>
次の例では、1 つのホテルの料金をリクエストしています。
6/23/23 - 6/25/23
このクエリに対するトランザクション メッセージのレスポンス例については、料金と客室在庫(トランザクション)XML リファレンスをご覧ください。
コンテキストを使用したクエリの例
次の例は、コンテキストを使用したクエリの例です。
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<Checkin>2023-05-23</Checkin>
<Nights>2</Nights>
<PropertyContextList>
<PropertyContext>
<Property>8675309</Property>
<!-- In the future, occupancy and device might be specified -->
<Context><UserCountry>US</UserCountry></Context>
<Context><UserCountry>GB</UserCountry></Context>
</PropertyContext>
<PropertyContext>
<Property>8675310</Property>
<Property>8675311</Property>
<Context><UserCountry>CA</UserCountry></Context>
</PropertyContext>
</PropertyContextList>
</Query>
コンテキスト クエリでは、ユーザーの国のコンテキストのみを指定します。将来的には、このようなクエリでユーザーのデバイスと定員も指定される可能性があります。
チェックイン期間
変更済み料金を使用する場合、クエリ メッセージの構造は、チェックイン期間、正確な旅行プラン、期間指定旅行プランに使用するヒントの種類によって異なります。これらのヒントの種類について詳しくは、ヒント応答メッセージをご覧ください。
次の例は、チェックイン期間の料金 <Query>
メッセージを示しています。
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<FirstDate>2023-05-23</FirstDate>
<LastDate>2023-05-26</LastDate>
<Nights>3</Nights>
<PropertyList>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</PropertyList>
</Query>
この例では、各ホテルについて次の宿泊料金の更新をリクエストしています。
5/23/23 - 5/24/23
5/23/23 - 5/25/23
5/23/23 - 5/26/23
5/24/23 - 5/25/23
5/24/23 - 5/26/23
5/24/23 - 5/27/23
5/24/23 - 5/26/23
5/25/23 - 5/27/23
5/25/23 - 5/28/23
期間指定滞在
次の例は、期間指定滞在の料金 <Query>
メッセージを示しています。
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<FirstDate>2023-05-23</FirstDate>
<LastDate>2023-05-26</LastDate>
<AffectedNights>3</AffectedNights>
<PropertyList>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</PropertyList>
</Query>
次の例では、各ホテルの料金の更新をリクエストします。
5/23/23 - 5/24/23
5/23/23 - 5/25/23
5/23/23 - 5/26/23
5/24/23 - 5/25/23
5/24/23 - 5/26/23
5/24/23 - 5/27/23
5/25/23 - 5/26/23
5/25/23 - 5/27/23
5/25/23 - 5/28/23
さらに、その日の前(ただしその日も含む)に始まる宿泊料金も適用できます。
5/20/23 - 5/23/23
5/21/23 - 5/23/23
5/21/23 - 5/24/23
5/22/23 - 5/23/23
5/22/23 - 5/24/23
5/22/23 - 5/25/23
メタデータ クエリ メッセージ
次の例は、複数の宿泊施設の客室とパッケージ情報のメタデータの更新をリクエストする <Query>
メッセージを示しています。
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<HotelInfoProperties>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</HotelInfoProperties>
</Query>
このタイプのクエリ メッセージには、客室とパッケージのメタデータを定義するトランザクション メッセージで応答します。詳しくは、客室とパッケージのメタデータの定義をご覧ください。