Query & Hints XML Reference

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

NOTE:Query Control messages were discontinued on June 7, 2018. All partners after that date have default maximum itinerary settings (330-day advance booking window x 30-day length of stay). If your system doesn’t support 330x30, please contact your technical account manager.

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

NOTE: If you do not implement Hint Response messages, Google's Query messages request data for all properties identified in your Hotel List Feed.

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, consult Hint Response Messages.

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>

Attributes

The <Hint> element has no attributes.

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

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, consult Hint Request Messages.

The Hint Request Message Schema defines the structure and constraints of a Hint Request message.

Syntax

The <HintRequest> element uses the following syntax:

Syntax

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

Attributes

The <HintRequest> element has no attributes.

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, consult Hint Response Messages.

Examples

Hint Request message

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, consult 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, consult Room Bundle metadata.

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

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>

The Query message schema defines the structure and constraints of a Query message.

Attributes

The <Query> element may contain one attribute: <LatencySensitive>.

The <LatencySensitive> attribute is optional. When provided and set to true, it indicates that the query is a live query. To have Google send queries with the <LatencySensitive> attribute, please send a request to your technical account manager.

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. Consult <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>

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, check out the 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.

Multiple <Context> will never be used with different user countries or user devices. When multiple <Context> are used to query for multiple occupancies, please provide each occupancy price as an additional Room Bundle for the corresponding property/itinerary. Each property/itinerary should have a single <Result> block with the prices for multiple occupancies included.

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>

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. While not mandatory, queries with <Occupancy> should result in a transaction message with the appropriate Room Bundles defined for each <Occupancy> queried. Note: <Occupancy> may not always appear in a query. In such cases, you should return prices of all occupancies.
<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. While not mandatory, queries with <OccupancyDetails> should result in a transaction message with the appropriate Room Bundles defined for each <Occupancy> queried. 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.” Queries with <UserCountry> defined should result in a transaction message with the appropriate <Rates> block defined for the queried country.
<UserDevice>	Pricing	String	Filters rates by the type of the device the user is searching from. Possible values: mobile desktop tablet Queries with <UserDevice> defined should result in a transaction message with the appropriate <Rates> block defined for the queried device type.

Examples

Occupancy

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

Occupancy Details

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

Multiple Contexts

The following example shows the use of an additional <Context> element in a Live Query.

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