Query & Hints XML Reference

This section provides a reference for the XML-based Query and hint-related messages.

<Hint> (Hint Response message)

The root element of a Hint Response message. Hint Response messages specify which hotel/itinerary combinations should be repriced. They are your response to a Hint Request message from Google.

A Hint Response message should specify only those hotels whose prices have changed since the last time Google received a successful Hint Response from your servers.

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

  • Exact itineraries: A combination of check-in date and length of stay.
  • Check-in date ranges: Specifies a range of check-in dates, beginning with the first check-in date and ending with the last check-in date.
  • Ranged stays (or ranged itineraries)

Each of these methods requires a different syntax for the Hint Response message.

For more information, see Hint Response Messages.

<Hint> syntax

The <Hint> element uses different syntax, depending on the type of Hint Response message:

Exact Itineraries

The following shows the syntax for exact itineraries in a Hint Response message:

<!-- 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>

Check-in Ranges

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

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

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

Ranged Stays

The following shows the syntax for ranged stays in a Hint Response message:

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

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

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

<Hint> attributes

The <Hint> element has no attributes.

<Hint> child elements

The <Hint> element has the following child elements:

Child Element Required? Type Hint Response Type Description
<CheckInDate> Required Date Exact itineraries The check-in date for the itinerary.
<FirstDate> Required Date Check-in ranges and ranged itineraries The first date of the date range for a check-in range or ranged stay Hint Response message. Dates are inclusive.
<Item> Required Object All A container for the hotel/itinerary to be updated.
<LastDate> Required* Date Check-in ranges and ranged itineraries The last date of the date range for a check-in range or ranged stay Hint Response message. Dates are inclusive.

* This element is optional for ranged stays.

<LengthOfStay> Required Integer Exact itineraries The number of nights for the itinerary, expressed as a positive integer.
<Property> Required String All The ID of a hotel, using the same ID as the Hotel List Feed. The number of <Property> elements you can specify in a single <Item> block is determined by the type of Hint Response message:

  • Exact itineraries: Up to 100 hotels.
  • Check-in ranges: More than one if you set <MultipleItineraries> to "checkin_range" in your <QueryControl> message.
  • Ranged stay: More than one if you set <MultipleItineraries> to "affected_dates" in your <QueryControl> message.

For more information, see QueryControl Messages.

<Stay> Required Object Exact itineraries A container for the <CheckinDate> and <LengthOfStay> elements in an exact itinerary Hint Response message. Each <Item> can contain only a single <Stay>.
<StaysIncludingRange> Required Object Ranged itineraries A container for the <FirstDate> and <LastDate> elements in a ranged stay Hint Response message.

<Hint> examples

Exact Itineraries

The following example defines multiple itineraries for a single property a Hint Response message:

<!-- 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>

Check-in Ranges

The following example 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:

<!-- 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>

Note that for a check-in range message to be able to specify multiple properties in a single <Item>, the value of <MultipleItineraries> in <QueryControl> must be set to "checkin_range".

Ranged Stays

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

<!-- 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>

Note that for a ranged stay message to be able to specify multiple properties in a single <Item>, the value of <MultipleItineraries> in <QueryControl> must be set to "affected_dates".

For each of these examples, Google responds with a <Query>, and you should then respond with a <Transaction> that includes price updates for the specified hotels/itineraries.

<HintRequest>

The root element of a Hint Request message. Google sends a Hint Request message to your server and expects a response that specifies the hotels and itineraries whose prices have changed since the last time Google received a successful Hint Response from your server.

If there are any price changes, Google then sends a <Query> that fetches the updated pricing data for the indicated hotels and itineraries.

For more information, see Hint Request Messages.

<HintRequest> syntax

The <HintRequest> element uses the following syntax:

Syntax

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

<HintRequest> attributes

The <HintRequest> element has no attributes.

<HintRequest> child elements

The <HintRequest> element has the following child elements:

Child Element Type Description
<LastFetchTime> DateTime The last time that Google succeeded in getting a Hint Response message to a Hint Request message.

If this time is older than the last time you updated prices on your server, then you should respond with a Hint Response message specifying which hotels have changed.

For more information, see Hint Response Messages.

<HintRequest> examples

Example

The following example shows a Hint Request message:

<?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>

The root element of a Query message. Query messages are requests from Google for pricing or metadata updates. They are used with both the Pull and Pull with Hints delivery modes.

There are two types of Query messages:

  • Pricing: Google requests pricing updates for the specified hotels. When you receive a pricing Query message, you should respond with a <Transaction> message that contains the requested pricing information in <Result> elements.

    Live Queries are a special type of pricing Query message in which Google asks for real-time price updates.

    For more information, see Pricing Overview.

  • Metadata: Google requests metadata updates for the rooms and Room Bundles for the specified hotels. When you receive a metadata Query message, you should respond with a <Transaction> message that specifies data about the rooms and Room Bundles in <PropertyDataSet> elements.

    For more information, see Room Bundle metadata.

The syntax for the messages is different, depending on the type. Both types are described in this section.

<Query> syntax

The <Query> element uses the following syntax:

Syntax

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
<!-- The "latencySensitive" attribute appears only with Live Queries -->

  <!-- PRICING QUERIES -->
    <Checkin>YYYY-MM-DD</Checkin>

    <Nights>number_of_nights</Nights>

    <!-- Only for Check-in Date Range pricing queries (Pull + Hints) -->
    <FirstDate>YYYY-MM-DD</FirstDate>
    <LastDate>YYYY-MM-DD</LastDate>

    <!-- Only for Ranged Stay pricing queries (Pull + Hints) -->
    <AffectedNights>number_of_nights</AffectedNights>

    <PropertyList>
      <Property>hotel_id</Property>
       ...
    </PropertyList>

    <!-- Only for Live Queries -->
    <DeadlineMs>deadline</DeadlineMs>
    <Context>
      <Occupancy>total_number_of_guests</Occupancy>
      <UserCountry>country_code</UserCountry>
      <UserDevice>device_type</UserDevice>
    </Context>

  <!-- METADATA QUERIES -->
    <HotelInfoProperties>
      <Property>property_ID</Property>
      ...
    </HotelInfoProperties>

</Query>

<Query> attributes

The <Query> element has no attributes.

<Query> child elements

The <Query> element has the following child elements:

Child Element Query Type Type Description
<AffectedNights> Pricing Integer The number of nights for a ranged stay. This element is used only for Ranged Stay pricing queries used with Pull with Hints.
<Checkin> Pricing Date The dates of a specific price change.
<Context> Pricing (Live Queries only) Object For Live Queries, specifies certain parameters under which the query is made. Child elements include:
  • <Occupancy>: the total number of guests
  • <OccupancyDetails>: the type of guests, such as adults or children
  • <UserCountry>: the country where the user is located
  • <UserDevice>: the type of device the customer used to search for a hotel, such as "mobile," "tablet," or "desktop."

The <Context> element may be repeated in a single request, allowing queries for different occupancies. See <Context> for a list of child elements, syntax, and examples.

<FirstDate> Pricing Date The start date for a range of itineraries to which the pricing applies. This element is used only for Check-in Date Range pricing queries used with Pull with Hints.
<HotelInfoProperties> Metadata String One or more properties for which Google wants updated room and Room Bundle metadata in a metadata Query message. This element can contain one or more <Property> elements that specify hotel property IDs.
<LastDate> Pricing Date The end date for a range of itineraries to which the pricing applies. This element is used only for Check-in Date Range pricing queries used with Pull + Hints.
<Nights> Pricing Integer The number of nights for a particular itinerary, up to 14.
<PropertyList> Pricing Object One or more IDs for hotel that require pricing updates.

Define each hotel in a <Property> element. The value is a string that matches a hotel ID in your Hotel List Feed. For example:

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

<Query> examples

Pricing Query

The following example shows a pricing Query message that requests price updates for a set of hotels, available for 3 nights, and starting on June 10, 2018:

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2018-06-10</Checkin>
  <Nights>3</Nights>
  <PropertyList>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </PropertyList>
</Query>

Metadata Query

The following example shows a metadata Query message:

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

For additional examples, including ranged stay and check-in date range pricing queries, see Query message examples.

<Context>

The <Context> element describes information for a Live Query, including the number and type of guests, the user country, and user device.

<Context> syntax

The <Context> element uses the following syntax:

Syntax

<?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> child elements

The <Context> element has the following child elements:

Child Element Query type Type Description
<Occupancy> Pricing Integer Specifies the total number of guests.
<OccupancyDetails> Pricing Object Is preceded by <Occupancy>. Specifies guests by type, including:

  • <NumAdults>: number of adult guests
  • <Children> and <Child "age">: Specifies which guests are children (typically age 0-17), and optionally includes each child’s age.
  • Note: <OccupancyDetails> may not always appear in a query. In such cases, you should assume that all guests are adults.

<UserCountry> Pricing String Filters rates by the country where user is located. The value is a 2-letter country code such as “US” for United States, or a region code, such as “EU” for “Europe.”
<UserDevice> Pricing String Filters rates by the type of the device the user is searching from. Possible values:
  • mobile
  • desktop
  • tablet

<Context> examples

Example 1

The following example shows a Live Query with <OccupancyDetails> within <Context>. The Live Query is for 4 guests, 2 of which are children, and seeks a rate applicable to a US customer booking from a mobile device:

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2017-06-07</Checkin>
  <Nights>5</Nights>
  <LatencySensitive>true</LatencySensitive>
  <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>

Example 2

The following example shows a Live Query for <Occupancy> within <Context>. The Live Query is for 3 adult guests.

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