Query Messages

Query messages are requests from Google for pricing or metadata updates. They are used with both the Pull and Changed Pricing 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 room and package information in the specified hotels.

You define the endpoint that Google uses for Query messages and Live Pricing 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 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:

  1. Live pricing: If enabled, queries are sent when a user is actively browsing prices for the specified property or itinerary combination and you have a specified timeframe to respond.

  2. With Context: If enabled, user context recommendations are included in each query that Google sends you and the recommendations reflect the most common types of users who search for the given property or itinerary combinations. Following these recommendations may increase the efficiency of your responses.

  3. Metadata: This is a request for details about rooms and packages for the specified properties.

Live pricing queries

Live pricing queries are requests from Google for real-time price updates in response to user searches. Google receives a search request from a user for a hotel or 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 pricing querying, Google attempts to get a price and display it in the results at the time of the search.

All Live pricing query requests have a response time limit which is typically up to 4000 milliseconds. This limit is specified in the Live pricing query request. If a response cannot be provided within the time limit, it results in a missed participation for the specific opportunity. However, we recommend providing a price anyway so it can be cached and used for future opportunities. The connection for the response remains open for ten minutes or as specified in the partner's configuration.

Live pricing 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 pricing queries, you can show more up-to-date prices that match what the customer searched for.

Live pricing queries are meant to be a secondary mechanism for pricing updates. The primary mechanism for repricing is still through Pull or Changed pricing. Live pricing queries helps fill the gaps where Google does not have prices for hotel or itinerary combinations.

Rules for using Live pricing queries

  • No cached data for the given itinerary exists because the requested itinerary is atypical, such as the dates are very far in the future or the hotel is very infrequently searched for.

  • The date requested is a non-default date.

: Note: The default dates are not eligible for Live pricing queries. Live pricing queries is requested only for non-default dates.

Google typically caches the results of a Live pricing so that the same hotel or itinerary are not queried again. It can request both single hotel or itinerary combinations as well as multi-hotel or single itinerary combinations.

The Live pricing with Context feature enables Google to send specific Live pricing 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 defines the query parameters. Prices received from Live pricing queries with context can be cached as a Room Bundle, if it is a price for a specific occupancy and as a Conditional Rate, if it is for a user country or user device.

With Context queries

With Context queries are regular requests to update our database for the specified property or itinerary combinations. They contain a list of user contexts which are popular for those combinations. If Conditional Rates is used, then sending rates for all possible user contexts may be expensive, therefore you can use this list of user contexts to limit your response. Returning prices for only the specified user contexts covers the vast majority of relevant user queries.

If you are interested in receiving With Context queries, contact your Technical Account Manager (TAM). They can confirm that you are ready to receive such messages and then make a configuration adjustment to begin sending user contexts in queries to you.

Metadata query messages

Metadata query messages contain details about room and package information 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.

Control queries

This section describes how you control which properties and 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 or 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 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>

This example requests pricing updates for each hotel:

5/23/18 - 6/26/18

Live pricing query example

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">
<!-- 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 Pricing Query request -->
  <Checkin>2023-05-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 Pricing 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 a single hotel:

6/23/23 - 6/25/23

A sample transaction message response to this query can be found in the Pricing & Room Inventory (Transactions) XML Reference.

With Context query example

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

With Context queries only specifies user country context. In the future, such queries might also specify user device and occupancy.

Check-in date ranges

If you use Changed Pricing, then the structure of the Query message depends on the hint type that you use for check-in date ranges, exact itineraries, or ranged itineraries. For more information about 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>2023-05-23</FirstDate>
  <LastDate>2023-05-26</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):

5/23/23 - 5/24/23
5/23/23 - 5/25/23
5/23/23 - 5/26/23
5/24/23 - 5/25/23
5/24/23 - 5/26/23
5/24/23 - 5/27/23
5/24/23 - 5/26/23
5/25/23 - 5/27/23
5/25/23 - 5/28/23

Ranged Stays

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

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <FirstDate>2023-05-23</FirstDate>
  <LastDate>2023-05-26</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 each hotel:

5/23/23 - 5/24/23
5/23/23 - 5/25/23
5/23/23 - 5/26/23
5/24/23 - 5/25/23
5/24/23 - 5/26/23
5/24/23 - 5/27/23
5/25/23 - 5/26/23
5/25/23 - 5/27/23
5/25/23 - 5/28/23

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

5/20/23 - 5/23/23
5/21/23 - 5/23/23
5/21/23 - 5/24/23
5/22/23 - 5/23/23
5/22/23 - 5/24/23
5/22/23 - 5/25/23

Metadata query message

The following example shows a <Query> message that requests metadata updates for the room and package information 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 package metadata. For more information, see Defining room and package metadata.