クエリとヒントの XML リファレンス

このセクションでは、Google XML ベースの Hint Request メッセージ、Hint Response メッセージ、Query メッセージのリファレンスを紹介します。

<Hint>（Hint Response メッセージ）

Hint Response メッセージのルート要素。Hint Response メッセージでは、料金を変更するホテルまたは宿泊プランの組み合わせを指定します。これらは、Google からの Hint Request メッセージに対する、お客様の応答です。

Hint Response メッセージでは、Google がお客様のサーバーから正常に Hint Response を受信して以降に料金が変更されたホテルのみを指定する必要があります。

Hint Response メッセージでは、Google が料金を変更する必要があるホテルや宿泊プランを次のいずれかの方法で指定します。

  • 完全一致の旅行プラン: チェックイン日と滞在日数の組み合わせ。

  • チェックイン期間: 最初のチェックイン日から最後のチェックイン日までのチェックイン日の範囲を指定します。

  • 期間指定滞在（または期間指定宿泊プラン）

これらの各方法では、Hint Response メッセージに関して、異なる構文が必要になります。

詳しくは、Hint Response メッセージをご覧ください。

構文

<Hint> 要素は、Hint Response メッセージのタイプに応じて異なる構文を使用します。

完全一致宿泊プラン

Hint Response メッセージの完全一致宿泊プランに対応する構文は次のとおりです。

<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>hotel_ID</Property>
    ...
    <Stay>
      <CheckInDate>checkin_date</CheckInDate>
      <LengthOfStay>number_of_nights</LengthOfStay>
    </Stay>
  </Item>
  ...
</Hint>

チェックイン範囲

Hint Response メッセージのチェックイン範囲に対応する構文は次のとおりです。

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>hotel_ID</Property>
    [...]

    <!-- Required -->
    <FirstDate>first_checkin_date</FirstDate>
    <!-- Required -->
    <LastDate>last_checkin_date</LastDate>
  </Item>
  ...
</Hint>

期間指定滞在

Hint Response メッセージの期間指定滞在に対応する構文は次のとおりです。

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>1458700</Property>
    <Property>5418701</Property>
    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>2025-04-28</FirstDate>
      <!-- Optional -->
      <LastDate>2025-04-29</LastDate>
    </StaysIncludingRange>
  </Item>
  ...
</Hint>

属性

<Hint> 要素には、省略可能な属性 id が含まれています。指定すると、この <Hint> に基づいて送信される <Query> メッセージに hintId 属性として含まれます。

子要素

<Hint> 要素には次の子要素があります。

子要素 必須 タイプ Hint Response のタイプ 説明
<CheckInDate> Required Date 完全一致宿泊プラン 宿泊プランのチェックイン日。
<FirstDate> Required Date チェックイン範囲と期間指定宿泊プラン 期間の最初の日付。チェックイン範囲または期間指定滞在の Hint Response メッセージで指定します。指定した日を含みます。
<Item> Required Object すべて 更新するホテルと宿泊プランのコンテナ。
<LastDate> Required* Date チェックイン範囲と期間指定宿泊プラン

期間の最後の日付。チェックイン範囲または期間指定滞在の Hint Response メッセージで指定します。指定した日付が含まれます。

* この要素は、期間指定滞在では省略可能です。
<LengthOfStay> Required integer 完全一致宿泊プラン 宿泊プランの泊数。正の整数で指定します。
<Property> Required string すべて

ホテルの ID（ホテルリストと同じ ID を使用）。1 つの <Item> ブロックで指定できる <Property> 要素の数は、Hint Response メッセージのタイプによって決まります。

  • 完全一致宿泊プラン: 最大 100 件までのホテル。
  • チェックイン範囲: <QueryControl> メッセージで <MultipleItineraries> を "checkin_range" に設定した場合は複数。
  • 期間指定滞在: <QueryControl> メッセージで <MultipleItineraries> を "affected_dates" に設定した場合は複数。
<Stay> Required Object 完全一致宿泊プラン 完全一致プランの Hint Response メッセージに含める <CheckinDate> 要素と <LengthOfStay> 要素のコンテナ。各 <Item> には <Stay> を 1 つだけ含めることができます。
<StaysIncludingRange> Required Object 期間指定宿泊プラン 期間指定滞在の Hint Response メッセージに含める <FirstDate> 要素と <LastDate> 要素のコンテナ。

例

完全一致宿泊プラン

次の例では、1 つの宿泊施設の Hint Response メッセージに複数の宿泊プランを定義しています。

<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2018-07-03</CheckInDate>
      <LengthOfStay>3</LengthOfStay>
    </Stay>
  </Item>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2018-07-03</CheckInDate>
      <LengthOfStay>4</LengthOfStay>
    </Stay>
  </Item>
</Hint>

チェックイン範囲

次の例では、料金が変更されたため再度取得する必要がある 2 つのホテルを指定しています。この場合、Google は 7 月 3 日から 7 月 6 日までの期間で、宿泊施設 12345 と 67890 の宿泊プランをすべて取得します。

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>12345</Property>
    <Property>67890</Property>
    <FirstDate>2018-07-03</FirstDate>
    <LastDate>2018-07-06</LastDate>
  </Item>
</Hint>

期間指定滞在

期間指定滞在の 2 通りの使用方法の例を次に示します。1 つは複数の泊数を指定し、もう一方では 1 泊のみを指定しています。

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <!-- Google fetches prices for all itineraries (first and last date are set) -->
  <Item>
    <Property>12345</Property>
    <StaysIncludingRange>
      <FirstDate>2018-07-03</FirstDate>
      <LastDate>2018-07-06</LastDate>
    </StaysIncludingRange>
  </Item>

  <!-- Google fetches prices for a single night (first date only) -->
  <Item>
    <Property>67890</Property>
    <StaysIncludingRange>
      <FirstDate>2018-07-03</FirstDate>
    </StaysIncludingRange>
  </Item>
</Hint>

これらの各例で、Google は <Query> で応答します。お客様側は、<Transaction> に指定ホテルと宿泊プランの料金更新データを含めて応答する必要があります。

<HintRequest>

Hint Request メッセージのルート要素。Google は、お客様のサーバーに Hint Request メッセージを送信し、その応答として、前回 Google がお客様のサーバーから正常に Hint Response を受信して以降に料金が変更されたホテルと宿泊プランを含むメッセージを期待します。

料金変更があった場合、Google は <Query> を送信して、指定されたホテルと宿泊プランの更新済み料金設定データを取得します。

詳しくは、Hint Request メッセージをご覧ください。

構文

<HintRequest> 要素の構文は次のとおりです。

構文

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
  <LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>

属性

<HintRequest> 要素には属性はありません。

子要素

<HintRequest> 要素には次の子要素があります。

子要素 タイプ 説明
<LastFetchTime> DateTime Hint Request メッセージに対する Hint Response メッセージを Google が最後に正常に取得した時間です。

この時間が、最後にサーバー上の料金を更新した時間よりも古い場合、応答の Hint Response メッセージではどのホテルに変更が加えられたかを指定する必要があります。

最近正常に取得されていない場合は、（バックログが大量に発生して深刻な問題が発生しないように）固定間隔の値に設定されます。現在の固定間隔の値は 1, 000 秒ですが、変更される可能性があります。

詳しくは、 Hint Response メッセージをご覧ください。

例

次の例は、ヒント リクエスト メッセージを示しています。

Hint Request メッセージ

次の例に、Hint Request メッセージを示します。

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest id="ABCDEF" timestamp="2018-06-07T16:20:00Z">
  <LastFetchTime>2018-03-25T00:04:09Z</LastFetchTime>
</HintRequest>

<Query>

Query メッセージのルート要素。Query メッセージは、料金設定やメタデータの更新データを要求する Google からのリクエストです。プル配信モードと変更済み料金配信モードの両方で使用されます。

料金クエリ メッセージ

料金クエリ メッセージは、料金設定で指定したホテルと旅行プランの組み合わせを指定します。

料金クエリ メッセージを受信したサーバーは、要求された料金設定の情報を含む <Transaction> メッセージで応答する必要があります。

詳しくは、料金設定の概要をご覧ください。

Query メッセージには次の 3 つの特別なタイプがあります。

  • ライブ料金: リアルタイムの料金更新を求める特定のユーザー リクエストに Google が応答します。パートナーが Live pricing query メッセージを受信した場合は、リクエストされた料金情報を <Result> 要素に含めて <Transaction> メッセージで応答する必要があります。

  • コンテキストに基づく料金設定: Google は、過去に人気があったコンテキストに基づいて料金キャッシュを更新します。With context query メッセージを受信した場合は、リクエストされた料金情報を <Result> 要素に含めて <Transaction> メッセージで応答する必要があります。

  • メタデータ: Google は、指定されたホテルについて、客室と条件の組み合わせに関するメタデータの更新情報をリクエストします。Metadata Query メッセージを受信した場合は、<PropertyDataSet> 要素に客室と条件の組み合わせに関するデータを指定する <Transaction> メッセージで応答する必要があります。詳しくは、条件の組み合わせのメタデータをご覧ください。

構文

<Query> 要素の構文は次のとおりです。

料金設定クエリ

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
</Query>

ライブ料金

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
  <FirstDate>YYYY-MM-DD</FirstDate>
  <LastDate>YYYY-MM-DD</LastDate>
  <!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
  <AffectedNights>number_of_nights</AffectedNights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
  <!-- See documentation below for <Context> -->
  <Context>
   ...
  </Context>
</Query>

コンテキストあり

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
  <FirstDate>YYYY-MM-DD</FirstDate>
  <LastDate>YYYY-MM-DD</LastDate>
  <!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
  <AffectedNights>number_of_nights</AffectedNights>
  <PropertyContextList>
    <PropertyContext>
      <Property>hotel_id</Property>
      ...
      <!-- See documentation below for <Context> -->
      <Context>
      ...
      </Context>
    </PropertyContext>
  </PropertyContextList>
</Query>

メタデータ

<HotelInfoProperties>
  <Property>property_ID</Property>
  ...
</HotelInfoProperties>

属性

<Query> 要素には属性が 1 つ（latencySensitive）含まれることがあります。

latencySensitive 属性は省略可能です。この値が true として指定されている場合、クエリが Live Pricing Query であることを示します。latencySensitive 属性を含むクエリの受け取りを希望する場合は、テクニカル アカウント マネージャー（TAM）にお問い合わせください。

子要素

<Query> 要素には次の子要素があります。

子要素 クエリのタイプ タイプ 説明
<AffectedNights> Pricing integer 期間指定滞在の泊数。この要素は、変更済み料金で使用する期間指定滞在の料金クエリにのみ使用されます。
<Checkin> Pricing Date 特定の料金変更の日付。
<Context> Pricing (Live Pricing Queries only) <Context> ライブ料金クエリについて、特定のパラメータを指定します（このパラメータに基づいてクエリが作成されます）。次の子要素があります。
  • <Occupancy>: 宿泊客の合計数
  • <OccupancyDetails>: 宿泊客の種類（大人や子どもなど）
  • <UserCountry>: ユーザーの居住国
  • <UserDevice>: 宿泊客がホテルの検索に使用したデバイスのタイプ（"mobile、tablet、desktop など）。

<Context> 要素は 1 つのリクエストで繰り返すことができ、さまざまな定員をクエリできます。子要素、構文、例の一覧については <Context> をご覧ください。
<FirstDate> Pricing Date 料金を適用する宿泊プランの期間の開始日。この要素は、変更済み料金で使用するチェックイン期間の料金設定クエリでのみ使用されます。
<HotelInfoProperties> Metadata string 1 つ以上の宿泊施設。Google はこれらの宿泊施設に関して、メタデータ Query メッセージで客室および条件の組み合わせの更新メタデータを要求します。この要素には、ホテル プロパティ ID を指定する 1 つ以上の <Property> 要素を格納することができます。
<LastDate> Pricing Date 料金設定を適用する宿泊プランの期間の終了日。この要素は、ヒントを使用したプル配信で使用するチェックイン期間の料金設定クエリでのみ使用されます。
<Nights> Pricing integer 特定の宿泊プランの泊数（最大 30）。
<PropertyList> Pricing Object

料金設定の更新が必要なホテルの 1 つ以上の ID。

各ホテルを <Property> 要素で定義します。この値は、ホテルリストのホテル ID と一致する文字列です。例:

<PropertyList>
  <Property>pid1</Property>
  <Property>pid2</Property>
</PropertyList>

例

料金クエリ

次の例は、2023 年 5 月 23 日以降の 3 泊分について、一連のホテルの料金更新データを要求する料金設定 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>

ライブ料金クエリ

次の例は、500 ミリ秒の応答時間制限のあるライブ料金クエリです。

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>5</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>8675309</Property>
  </PropertyList>
  <Context>
    <Occupancy>4</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
      <Children>
        <Child age="8"/>
        <Child age="5"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

コンテキスト クエリを使用

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2023-05-23</Checkin>
  <Nights>2</Nights>
  <PropertyContextList>
    <PropertyContext>
      <Property>8675309</Property>
      <!-- In the future, 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>

メタデータ クエリ

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <HotelInfoProperties>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </HotelInfoProperties>
</Query>

期間指定滞在やチェックイン期間の料金設定クエリなど、他の例については、Query メッセージの例をご覧ください。

<Context>

<Context> 要素には、宿泊者の数と種類、ユーザーの国、ユーザーのデバイスなど、Live pricing query に関する情報を記述します。

ユーザーの国とユーザーのデバイスについては、複数の <Context> を使用して複数の異なる情報が記述されることはありません。宿泊者の数と種類については、複数の <Context> を使用して複数の定員のクエリが送信されることがあります。その場合は、対応する宿泊施設と宿泊プランの追加の条件の組み合わせとして、それぞれの定員の料金を指定してください。宿泊施設または旅行プランごとに、指定されている複数の定員の料金を含む 1 つの <Result> ブロックが必要です。

<Context> クエリのレスポンスの詳細については、<OccupancyDetails> をご覧ください。

構文

<Context> 要素の構文は次のとおりです。

構文

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
  <Checkin>date</Checkin>
  <Nights>number_of_nights</Nights>
  <DeadlineMs>number_of_milliseconds</DeadlineMs>
  <PropertyList>
    <Property>property_ID</Property>
  </PropertyList>
  <Context>
    <Occupancy>total_number_of_guests</Occupancy>
    <OccupancyDetails>
      <NumAdults>number_of_adults</NumAdults>
      <Children>
        <Child age=age_of_one_child_guest/>
        <Child age=age_of_one_child_guest/>
      </Children>
    </OccupancyDetails>
    <UserCountry>end_user_country</UserCountry>
    <UserDevice>user_device_type</UserDevice>
  </Context>
</Query>

子要素

<Context> 要素には次の子要素があります。

子要素 クエリタイプ タイプ 説明
<Occupancy> Pricing integer 宿泊客の合計数を指定します。

必須ではありませんが、<Occupancy> を含むクエリには、指定された <Occupancy> ごとに適切な条件の組み合わせを定義した Transaction メッセージで応答することをおすすめします。ただし、条件の組み合わせを使用できない場合は、<Occupancy> 要素を指定することをおすすめします。

注:<Occupancy> が常にクエリに含まれるとは限りません。含まれていない場合は、すべての定員の料金を返す必要があります。
<OccupancyDetails> Pricing Object 前に <Occupancy> が付きます。次の情報を含め、宿泊客をタイプで指定します。
  • <NumAdults>: 大人の宿泊客の数
  • <Children> と <Child="age">: どの宿泊客がお子様（通常は 0 ～ 17 歳）であるかを指定し、必要に応じてお子様ごとの年齢を指定します。

必須ではありませんが、<OccupancyDetails> を含むクエリには、指定された <Occupancy> ごとに適切な条件の組み合わせを定義した Transaction メッセージで応答することをおすすめします。ただし、条件の組み合わせを使用できない場合は、<OccupancyDetails> 要素を指定することをおすすめします。

注: <OccupancyDetails> が常にクエリに含まれるとは限りません。含まれていない場合は、すべての宿泊客が大人であると見なす必要があります。
<UserCountry> Pricing string

ユーザーの居住国を基準にして料金をフィルタします。値は、2 文字の国コード（米国の "US" など）または地域コード（ヨーロッパの "EU" など）です。

<UserCountry> が定義されたクエリには、指定された国に対して適切な <Rates> ブロックを定義した Transaction メッセージで応答する必要があります。
<UserDevice> Pricing string

ユーザーが検索を行っているデバイスのタイプを基準にして料金をフィルタします。 考えられる値は次のとおりです。

  • mobile
  • desktop
  • tablet

<UserDevice> が定義されたクエリには、指定されたデバイスタイプに対して適切な <Rates> ブロックを定義した Transaction メッセージで応答する必要があります。

例

利用率

次の例は、<Context> 内の <Occupancy> のライブ料金クエリを示しています。このライブ料金クエリは 3 名の大人の宿泊客が対象です。

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>4</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>45617</Property>
  </PropertyList>
  <Context>
    <Occupancy>3</Occupancy>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

定員の詳細

次の例は、<Context> 内に <OccupancyDetails> を含むライブ料金クエリを示しています。このライブ料金クエリは 4 名の宿泊客が対象で、そのうち 2 名がお子様であり、モバイル デバイスから行われる米国人の宿泊客の予約に適用される料金を探します。

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>5</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>8675309</Property>
  </PropertyList>
  <Context>
    <Occupancy>4</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
      <Children>
        <Child age="4"/>
        <Child age="12"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

複数のコンテキスト

次の例では、ライブ料金クエリで複数の <Context> 要素がどのように使われているかを示します。

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>4</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>45617</Property>
  </PropertyList>
  <Context>
    <Occupancy>3</Occupancy>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
  <Context>
    <Occupancy>6</Occupancy>
    <OccupancyDetails>
      <NumAdults>4</NumAdults>
      <Children>
        <Child age="6"/>
        <Child age="10"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>