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. The exception to this rule occurs during the manual testing of the price endpoint integration through Google-TravelAds-Live. Those sample queries may or may not contain the User-Agent header.

Detailed formatting for Query messages can be found in the Query XML Reference.

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.

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. All Live Query requests have a response time limit, typically up to 4000 milliseconds (limit will be specified in the Live Query request).

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.

The Live Query with Context feature enables Google to send specific Live Query requests based on a user's device type, the country from which they are searching, and the number of occupants including children. Both the Query message and the Transaction message are expanded to include the <Context> element which will define the query parameters. Prices received from Live Queries with Context can be cached either as a Room Bundle (if it is a price for a specific occupancy) and/or as a Fenced Rate (if it is for a user country or user device).

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.

Query message examples

This section shows several examples of pricing Query messages and a metadata Query message. Additional examples are found in the Query XML Reference.

Sample itinerary

The following example shows a pricing <Query> that requests price updates for 4 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>

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

6/10/18 - 6/13/18

Live query with Context 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">
<!-- Note that the latencySensitive attribute is not present by default but can
     be configured to be displayed, on request, by Google. This attribute is only
     displayed for a Live Query request -->
  <Checkin>2017-07-23</Checkin>
  <Nights>2</Nights>
  <DeadlineMs>500</DeadlineMs>
<!-- The deadline represents the timeframe by which a response will need to be
     received by. This element is only displayed for a Live Query request -->
  <PropertyList>
    <Property>6781291</Property>
  </PropertyList>
<!-- Note that Context tags are potentially repeatable -->
  <Context>
<!-- The total number of guests occupying the room (adults+children) -->
    <Occupancy>3</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
<!-- In this example one of the 3 guests is a 5yr old child -->
      <Children>
        <Child age="5"/>
      </Children>
    </OccupancyDetails>
<!-- The user was located in the US when this search was made -->
    <UserCountry>US</UserCountry>
<!-- The user was searching from a mobile device at the time of search -->
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

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

07/23/17 - 7/25/17

A sample transaction message response to this query can be found in the Inventory and Pricing XML Reference.

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>2018-06-10</FirstDate>
  <LastDate>2018-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/18 - 6/11/18
6/10/18 - 6/12/18
6/10/18 - 6/13/18
6/11/18 - 6/12/18
6/11/18 - 6/13/18
6/11/18 - 6/18/18
6/12/18 - 6/13/18
6/12/18 - 6/18/18
6/12/18 - 6/15/18

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>2018-06-10</FirstDate>
  <LastDate>2018-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/18 - 6/11/18
6/10/18 - 6/12/18
6/10/18 - 6/13/18
6/11/18 - 6/12/18
6/11/18 - 6/13/18
6/11/18 - 6/18/18
6/12/18 - 6/13/18
6/12/18 - 6/18/18
6/12/18 - 6/15/18

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

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

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.