Hint Response Messages

When Google sends a HintRequest 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 fetches the updated pricing data for the indicated hotels and itineraries with a Query message.

For an overview of the repricing process, see Updating Prices.

Hint Response messages can use the following methods to specify which hotels and itineraries Google should reprice:

The root element of a Hint Response message is the <Hint> element. You request a hotel/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> element identifies a hotel by using the same IDs as the Hotel List Feed. 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 itineraries for repricing. For more information, see QueryControl messages.

Exact itineraries

Hint messages can be based on individual itineraries (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.

Exact itinerary syntax

The following shows the syntax for exact itinerary messages:

<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least 1 is required -->
    <Property>hotel_ID</Property>
    ...
    <Stay>
      <!-- Required -->
      <CheckInDate>checkin_date</CheckInDate>
      <!-- Required -->
      <LengthOfStay>number_of_nights</LengthOfStay>
    </Stay>
  </Item>
  ...
</Hint>

Exact itinerary element descriptions

The following table describes the child elements of the <Item> element for exact itineraries:

Element Required Description
<Property> Required Identifies the hotel using the same ID as the Hotel List Feed. You can specify up to 100 hotels with additional <Property> elements.
<Stay> Required Contains the check-in date and length of stay for the itinerary that is to be repriced.
<CheckInDate> Required Defines the check-in date for the itinerary.

The value of this element uses the following syntax: YYYY-MM-DD, where:

  • YYYY is the four-digit year
  • MM is the two-digit month
  • DD is the two-digit day
<LengthOfStay> Required Defines the number of nights for the itinerary, expressed as a positive integer.

Each <Item> element can contain only a single <Stay> element.

Exact itinerary request/response flow

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

<Hint>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2014-06-10</CheckInDate>
      <LengthOfStay>3</LengthOfStay>
    </Stay>
  </Item>
</Hint>

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

<Query>
  <Checkin>2014-06-10</Checkin>
  <Nights>3</Nights>
  <PropertyList>
    <Property>12345</Property>
  </PropertyList>
</Query>

You are then expected to respond with price updates for the hotel for the following stay:

6/10/14 - 6/13/14

Exact itinerary example

The following example shows a Hint Response message. This example specifies two hotels whose pricing has changed (thus causing Google to fetch the updated prices for the specified hotels again):

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

Check-in date ranges

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 these dates, and extending up to the length of stay that you indicate.

Check-in date ranges syntax

The following shows the syntax for a Hint Response message that uses check-in date ranges:

<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <!-- Can be > 1 if MultipleItineraries is set to "checkin_range" in QueryControl -->
    <Property>hotel_ID</Property>
    [...]

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

The default length of stay when using hints is 5 days. To change the default length of stay, set a new value in the QueryControl message.

Check-in date ranges elements description

The following table describes the child elements of the <Item> element for check-in date ranges:

Element Required Description
<Property> Required Identifies the hotel using the same ID as the Hotel List Feed. You can specify more than one property if <MultipleItineraries> is set to "checkin_range" in the QueryControl message.
<FirstDate> Required Defines the first date of the check-in date range. Dates are inclusive.

The value of this element uses the following syntax: YYYY-MM-DD, where:

  • YYYY is the four-digit year
  • MM is the two-digit month
  • DD is the two-digit day
<LastDate> Required Defines the last date of the check-in date range. Dates are inclusive.

The value of this element uses the following syntax: YYYY-MM-DD, where:

  • YYYY is the four-digit year
  • MM is the two-digit month
  • DD is the two-digit day

Check-in date ranges request/response flow

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

<Hint>
  <Item>
    <Property>12345</Property>
    <FirstDate>2014-06-10</FirstDate>
    <LastDate>2014-06-13</LastDate>
  </Item>
</Hint>

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

<Query>
  <FirstDate>2014-06-10</FirstDate>
  <LastDate>2014-06-12</LastDate>
  <Nights>5</Nights>
  <PropertyList>
    <Property>12345</Property>
  </PropertyList>
</Query>

You are then expected to respond with price updates for the hotel for the following stays:

6/10/14 - 6/11/14
6/10/14 - 6/12/14
6/10/14 - 6/13/14
6/10/14 - 6/14/14
6/10/14 - 6/15/14

6/11/14 - 6/12/14
6/11/14 - 6/13/14
6/11/14 - 6/14/14
6/11/14 - 6/15/14
6/11/14 - 6/16/14

6/12/14 - 6/13/14
6/12/14 - 6/14/14
6/12/14 - 6/15/14
6/12/14 - 6/16/14
6/12/14 - 6/17/14

This example uses the default length of stay, 5 nights.

Check-in date range example

The following example shows a Hint Response message that specifies two hotels whose pricing has changed and should be fetched again. Google gets all itineraries between July 3 and July 6 for properties 12345 and 67890.

<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>12345</Property>
    <Property>67890</Property>
    <FirstDate>2014-07-03</FirstDate>
    <LastDate>2014-07-06</LastDate>
  </Item>
</Hint>

Ranged itineraries (or ranged stays)

A Hint Response message can include a range of nights for an itinerary. This informs Google that it should fetch any itinerary containing any of those nights. The actual set of itineraries fetched is a function of both the set of nights with changed prices and the maximum length of stay.

Ranged stay syntax

The following example shows the syntax for ranged stays:

<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <!-- Can be > 1 if MultipleItineraries is set to "affected_dates" in your QueryControl message -->
    <Property>hotel_ID</Property>
    [...]

    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>first_date</FirstDate>

      <!-- Optional -->
      <LastDate>last_date</LastDate>
    </StaysIncludingRange>
  </Item>
  ...
</Hint>

Ranged stay element descriptions

The following table describes the child elements of the <Item> element for ranged stays:

Element Required Description
<Property> Required Identifies the hotel using the same ID as the Hotel List Feed. You can specify up to 100 hotels with additional <Property> elements.
<StaysIncludingRange> Required Contains the first and last dates for the date range that is to be repriced. Each <Item> element can have only one <StaysIncludingRange>.
<FirstDate> Required Defines the first date that a price change goes into effect. Dates are inclusive.

The value of this element uses the following syntax: YYYY-MM-DD, where:

  • YYYY is the four-digit year
  • MM is the two-digit month
  • DD is the two-digit day
<LastDate> Optional Defines the last date that a price change goes into effect. Dates are inclusive.

If you do not specify a <LastDate> element, then Google fetches new pricing for a single night stay.

The value of this element uses the following syntax: YYYY-MM-DD, where:

  • YYYY is the four-digit year
  • MM is the two-digit month
  • DD is the two-digit day

Ranged stay request/response flow

The following example Hint Response message uses ranged stays:

<Hint>
  <Item>
    <Property>12345</Property>
    <StaysIncludingRange>
      <FirstDate>2014-06-10</FirstDate>
      <LastDate>2014-06-13</LastDate>
    </StaysIncludingRange>
  </Item>
</Hint>

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

<Query>
  <FirstDate>2014-06-10</FirstDate>
  <LastDate>2014-06-13</LastDate>
  <AffectedNights>3</AffectedNights>
  <PropertyList>
    <Property>12345</Property>
    <Property>67891</Property>
  </PropertyList>
</Query>

You are then expected to create a Hint Response message with price updates for the hotel for the following stays:

6/07/14 - 6/10/14

6/08/14 - 6/10/14
6/08/14 - 6/11/14

6/09/14 - 6/10/14
6/09/14 - 6/11/14
6/09/14 - 6/12/14

6/10/14 - 6/11/14
6/10/14 - 6/12/14
6/10/14 - 6/13/14

6/11/14 - 6/12/14
6/11/14 - 6/13/14
6/11/14 - 6/14/14

6/12/14 - 6/13/14
6/12/14 - 6/14/14
6/12/14 - 6/15/14

6/13/14 - 6/14/14
6/13/14 - 6/15/14
6/13/14 - 6/16/14

Notice that with ranged stays, all itineraries, including those that start before the first date but overlap with it, should be repriced.

Ranged stay example

The following example shows two different uses of ranged stays, one for a range of nights and the other for a single night:

<?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>2014-07-03</FirstDate>
      <LastDate>2014-07-06</LastDate>
    </StaysIncludingRange>
  </Item>

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