Query Messages

Query messages are requests from Google for pricing or metadata updates. They are used with both the Pull and Pull with Hints delivery modes.

The root element of Query messages is <Query>.

The structure of the Query message depends on the type of message:

  • Pricing: Google sends a Query message that requests pricing updates for the specified hotels.
  • Metadata: Google sends a Query message that requests data about the rooms and Room Bundles in the specified hotels.

You define the endpoint that Google uses for Query messages (and Live Queries) during your initial configuration. For more information, contact your Technical Account Manager (TAM).

Google sends a Query message as an HTTP POST request with the Content-Type header set to "application/xml" and the User-Agent header set to Google-HotelAdsPrices.

Pricing Query messages

Pricing Query messages specify the property/itinerary combinations for which you supply then 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.

In some cases, Query messages request pricing for a real-time search. In these cases, you have a specified timeframe in which to respond. These are known as Live Queries.

Metadata Query messages

Metadata Query messages contain details about rooms and Room Bundles for the specified properties.

When you receive a metadata Query message, you should respond with a <Transaction> message that specifies pricing for the requested properties in <Result> elements.

For more information, see Defining room and package metadata.

Controlling queries

This section describes how you control which properties and/or itineraries can be the subject of Query messages from Google.

Itinerary boundaries

You determine the possible boundaries of pricing queries using <ItineraryCapabilities>. You define rules that determine the range of dates and maximum lengths of stay that you support.

You can set default values for <MaxAdvancePurchase> and <MaxLengthOfStay> that apply to all hotel/itinerary combinations. You can also define these settings for groups of hotels.

Excluding properties

You can disable queries for groups of properties by using <PropertyOverride>. For example, you might want to exclude properties that have very consistent pricing, or hotels with prices that are already frequently updated.

To exclude properties from querying, add a <PropertyOverride> block to <QueryControl>. Set the value of <State> to "disabled", and list each of the properties with a <Property> element within that block.

The following example disables queries for properties "8675309", "060773", and "42":

<?xml version="1.0" encoding="UTF-8"?>
<QueryControl>
  <ItineraryCapabilities>
    <PropertyOverride>
      <State>disabled</State>
      <Property>8675309</Property>
      <Property>060773</Property>
      <Property>42</Property>
    </PropertyOverride>
  </ItineraryCapabilities>
</QueryControl>

To enable a block of hotels that were previously disabled, change the value of <State> to "enabled" or delete that block. The default behavior is for all hotels to be enabled unless explicitly disabled.

You can define any number of <PropertyOverride> blocks in <QueryControl>, but each hotel ID can appear in only one block.

Live Queries

Live Queries are requests from Google for real-time price updates in response to end-user searches. Google receives a search request from an end-user for a hotel/itinerary combination, and because pricing data is not available or not current, Google requests a price update from you at the time of the search. With Live Querying, Google attempts to get a price and display it in the results at the time of the search.

Live Queries are also contextual and can retrieve prices for the following parameters: user country, device type, occupancy (number of guests), and whether those guests are adults or children. With Live Queries, you can show more up-to-date prices that match what the customer searched for.

Live Queries are meant to be a secondary mechanism for pricing updates. (The primary mechanism for repricing is still through Pull or Pull with Hints.) Live Queries help fill the gaps where Google does not have prices for hotel/itinerary combinations.

Live Queries are typically used under the following circumstances:

  • No cached data for the given itinerary exists, either because the requested itinerary is atypical (such as dates that are very far in the future) or the hotel is very infrequently searched for.
  • The date requested is a non-default date. (Note that default dates are not eligible for Live Queries. Live Queries will only be requested for non-default dates.)

Google typically caches the results of a Live Query so that the same hotel/itinerary will not need to be Live Queried again.

Live Queries can request both single hotel/itinerary combinations as well as multi-hotel/single itinerary combinations.

Query message examples

This section shows several examples of pricing Query messages and a metadata Query message.

Simple itinerary

The following example shows a pricing <Query> that requests price updates for 4 hotels, available for 3 nights, and starting on June 10, 2014:

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

This example requests pricing updates for the following stay only (for each hotel):

6/10/14 - 6/14/14

Live query example

The following example shows a Live 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>

This example requests a price for the following stay only (for a single hotel):

6/07/15 - 7/23/15

It also asks, through the <Context> element, for a rate for 4 guests, including 2 adults and 2 children, applicable to U.S. customers booking from a mobile device

Check-in date ranges

If you use Pull with Hints, then the structure of the Query message depends on the hint type that you use (check-in date ranges, exact itineraries, or ranged itineraries). For more information on each of these hint types, see Hint Response Messages.

The following example shows a pricing <Query> message for check-in date ranges:

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

This example requests pricing updates for the following stays (for each hotel):

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

Ranged Itineraries (or Ranged Stays)

The following example shows a pricing <Query> message for ranged stays:

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <FirstDate>2014-06-10</FirstDate>
  <LastDate>2014-06-13</LastDate>
  <AffectedNights>3</AffectedNights>
  <PropertyList>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </PropertyList>
</Query>

This example requests pricing updates for the following stays (for each hotel):

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

Plus stays that started before (but include) the given night:

6/7/14 - 6/10/14
6/8/14 - 6/10/14
6/8/14 - 6/11/14
6/9/14 - 6/10/14
6/9/14 - 6/11/14
6/9/14 - 6/12/14

Metadata query message

The following example shows a <Query> message that requests metadata updates for the rooms and Room Bundles for several properties:

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

You respond to this type of Query message with a Transaction message that defines room and Room Bundle metadata. For more information, see Defining room and package metadata.

Send feedback about...

Hotel Prices
Need help? Visit our support page.