Query & Hints XML Reference

This section provides a reference for the Google XML-based Hint Request messages, Hint Response messages, and Query messages.

<Hint> (Hint Response message)

The root element of a Hint Response message. Hint Response messages specify which hotel or 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, 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 -->
    <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 -->
    <Property>hotel_ID</Property>
    [...]

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

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

Attributes

The <Hint> element contains an optional attribute: id. When provided, it is included as the hintId attribute in <Query> messages sent based on this <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. 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>

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>

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.

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.

If there hasn't been a recent successful fetch, this will be set to a fixed interval value (to avoid more serious issues with large backlogs). The current fixed interval value is 1000 seconds, but is subject to change.

For more information, consult Hint Response Messages.

Examples

The following example shows a Hint Request message:

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 Changed pricing delivery modes.

Pricing query messages

Pricing Query messages specify the property and itinerary combinations for which you supply the prices.

When your server receives a pricing Query message, it should respond with a <Transaction> message that contains the requested pricing information.

For more information, see Pricing Overview.

There are three special types of Query messages:

  • Live pricing: Google responds to a specific user request, asking for a real-time price update. When partners receive a Live pricing query message, partners should respond with a <Transaction> message that contains requested pricing information in <Result> elements.

  • With context pricing: Google updates its price cache based on contexts which are historically popular. When you receive a With context query message, you should respond with a <Transaction> message that contains the requested pricing information in <Result> elements.

  • 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, refer to Room Bundle metadata.

Syntax

The <Query> element uses the following syntax:

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

Live pricing

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

With context

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

Metadata

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

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 Pricing Query. To have Google send queries with the latencySensitive attribute, contact your Technical Account Manager (TAM).

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 Changed Pricing.
<Checkin> Pricing Date The dates of a specific price change.
<Context> Pricing (Live Pricing Queries only) <Context> For Live Pricing 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 guest 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 Changed Pricing.
<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 30.
<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. 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 May 23, 2023:

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

Live pricing query

The following example shows a Live Pricing Query with a response time limit of 500 milliseconds:

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

With 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, occupancy and 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>

Metadata query

<?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 pricing 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, provide each occupancy price as an additional Room Bundle for the corresponding property or itinerary. Each property or itinerary should have a single <Result> block with the prices for multiple occupancies included.

For the response details for the <Context> query, see <OccupancyDetails>.

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>, but if the Room Bundles are unavailable it is recommended that you specify the <Occupancy> element.

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>, but if the Room Bundles are unavailable it is recommended that you specify the <OccupancyDetails> element.

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 pricing query for <Occupancy> within <Context>. The Live pricing 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 pricing query with <OccupancyDetails> within <Context>. The Live pricing query is for 4 guests, 2 of which are children, and seeks a rate applicable to a US guest 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 pricing 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>