Hint Response Messages

  • Hint Response messages are sent by your servers to Google in response to a Hint Request message, specifying hotels with price changes.

  • If price changes are indicated in the Hint Response, Google sends a <Query> to fetch updated pricing data for the specified hotels and itineraries.

  • Failing to implement Changed Pricing will result in Google fetching data for all hotels in your Hotel List.

  • Hint Response messages can specify exact itineraries, check-in date ranges, or ranged stays to trigger repricing.

  • The root element of a Hint Response message is <Hint>, containing one or more <Item> elements that request a hotel or itinerary update.

When Google sends a Hint Request message, your servers should respond with a Hint Response message that specifies the hotels whose prices have changed since the last time Google received a successful Hint Response from those same servers. If there are any price changes, Google then sends a <Query> that fetches the updated pricing data for the indicated hotels and itineraries.

For an overview of the repricing process, see the Pricing Overview.

Hint Response messages uses the following methods to reprice the selected hotels and their itineraries:

The root element of a Hint Response message is <Hint>. You request a hotel or itinerary to be updated by using one or more <Item> elements. A single Hint Response message can define any number of <Item> elements.

Each Hint Response message must specify at least one <Property> element for each <Item>. The <Property> identifies a hotel by using the same IDs as the Hotel List. By default, you specify a single hotel ID for each <Item> block. However, you can instruct Google to allow multiple hotels in an item block if you are using check-in date ranges or ranged stays for repricing.

Exact itinerary request and response flow

Hint messages can be based on individual itineraries such as the combination of check-in date and length of stay. In this case, you specify a check-in date and length of stay for your hotels, and Google fetches the new pricing data for just that itinerary.

Partner's response

The following Hint Response message defines a single property and a single itinerary:

<Hint>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2023-05-20</CheckInDate>
      <LengthOfStay>3</LengthOfStay>
    </Stay>
  </Item>
</Hint>

Google's response

Google responds to your Hint Response message with a <Query> similar to the following:

<Query>
  <Checkin>2023-05-20</Checkin>
  <Nights>3</Nights>
  <PropertyList>
    <Property>12345</Property>
  </PropertyList>
</Query>

Create <Transaction>

You are then expected to create a <Transaction> with price updates for the hotel for the following stay:

5/20/23 - 5/23/23

Check-in date ranges request and response flow

A Hint Response message can specify a range of check-in dates, beginning with the first check-in date and ending with the last check-in date. When Google fetches new pricing data, Google pulls itineraries for every check-in date for the hotel starting with those dates and extending up to the length of stay that you indicate.

Partner's ranged dates

The following example for Hint Response message defines a single property with a range of dates for the check-in:

<Hint>
  <Item>
    <Property>12345</Property>
    <FirstDate>2023-05-20</FirstDate>
    <LastDate>2023-05-23</LastDate>
  </Item>
</Hint>

Google's response

Google responds to this Hint Response message with <Query> similar to the following:

<Query>
  <FirstDate>2023-05-20</FirstDate>
  <LastDate>2023-05-23</LastDate>
  <Nights>5</Nights>
  <PropertyList>
    <Property>12345</Property>
  </PropertyList>
</Query>

Create <Transaction>

You are then expected to create a <Transaction> with price updates for the following stays for that hotel:

5/20/23 - 5/21/23
5/20/23 - 5/22/23
5/20/23 - 5/23/23
5/20/23 - 5/24/23
5/20/23 - 5/25/23

5/21/23 - 5/22/23
5/21/23 - 5/23/23
5/21/23 - 5/24/23
5/21/23 - 5/25/23
5/21/23 - 5/26/23

5/22/23 - 5/23/23
5/22/23 - 5/24/23
5/22/23 - 5/25/23
5/22/23 - 5/26/23
5/22/23 - 5/27/23

This example uses length of stay of 5 nights. The default length of stay is 30 days.

Ranged stays request and response flow

A Hint Response message can include a range of dates that have changed. This informs Google that it should fetch any itinerary affected by any of those dates. The actual set of itineraries fetched is a function of both the set of dates with changes and the maximum length of stay.

Partner's ranged stays

The following example Hint Response message uses ranged stays:

<Hint>
  <Item>
    <Property>12345</Property>
    <StaysIncludingRange>
      <FirstDate>2023-05-20</FirstDate>
      <LastDate>2023-05-23</LastDate>
    </StaysIncludingRange>
  </Item>
</Hint>

Google's response

Google responds to your Hint Response message with a <Query> similar to the following:

<Query>
  <FirstDate>2023-05-20</FirstDate>
  <LastDate>2023-05-23</LastDate>
  <AffectedNights>3</AffectedNights>
  <PropertyList>
    <Property>12345</Property>
    <Property>67891</Property>
  </PropertyList>
</Query>

Create <Transaction>

You are then expected to create a <Transaction> with price updates for the hotel for the following stays:

5/17/23 - 5/20/23

5/18/23 - 5/20/23
5/18/23 - 5/21/23

5/19/23 - 5/20/23
5/19/23 - 5/21/23
5/19/23 - 5/22/23

5/20/23 - 5/21/23
5/20/23 - 5/22/23
5/20/23 - 5/23/23

5/21/23 - 5/22/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

5/23/23 - 5/24/23
5/23/23 - 5/25/23
5/23/23 - 5/26/23

Ranged Stays: Batching limits and query splitting

Google limits each pull query to a maximum of 10,000 Hotel-Itinerary pair (a hotel, checkin date, and length of stay) combinations. For a Ranged Stay hint, the number of combinations is calculated using the trapezoid formula to calculate the number of Hotel-Itinerary pair combinations for Ranged Stay Queries:

$$ \text{Total Items} = \left( \text{Date Span} \times \text{LOS} + \frac{\text{LOS} \times (\text{LOS} + 1)}{2} \right) \times N_{\text{hotel_batch_size}} $$

Where:

  • Date Span: The inclusive number of days between <FirstDate> and <LastDate> (Date span = LastDate - FirstDate + 1).
  • LOS: The maximum length of stay requested in the hint (for example, <AffectedNights>14</AffectedNights>).
  • \(N_{\text{hotel_batch_size}}\): The number of properties included in the query batch (configured via hotel_batch_size).

What happens when a hint exceeds 10,000 items?

If the calculated items exceed 10,000, Google automatically splits the query workload:

  1. Initial Attempt (Ranged Stay): A smaller date window covering the start of your range is sent using <AffectedNights>.
  2. First Fallback (If supported - Check-in Range): We will attempt to send smaller remainders of your date range as Check-in Date Range queries using <Nights> (query below).
  3. Final Fallback (Exact Itineraries): We will fall back to expanding the query set to the individual exact itineraries.
<!-- Example: Remainder batch dispatched after a split -->
<Query>
  <FirstDate>2026-10-01</FirstDate>
  <LastDate>2026-10-31</LastDate>
  <Nights>14</Nights>
  <PropertyList>
    <Property>12345</Property>
  </PropertyList>
</Query>
  • Keep property batch sizes balanced: If you update large date windows (such as 180 to 365 days) with stay lengths of 14+ nights, ask your Google Technical Account Manager to set your hotel_batch_size to a lower value to prevent hints from triggering splits.
  • Scope hints tightly: When notifying Google of price changes, restrict <FirstDate> and <LastDate> spans to the specific date intervals where rates actually changed, rather than sending a full calendar year.
  • If your hints cover large date ranges: Ensure your parser accepts either or inside blocks containing <FirstDate> and <LastDate> so that multiple ranged query types can be used to satisfy the pull requests.