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:

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

The following are examples for With Context query:

Basic Query With Context

 <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query>  
<Checkin>2023-05-23</Checkin>  
<Nights>2</Nights>  
<PropertyContextList>  
<PropertyContext>  
<Property>8675309</Property>  
<!--  
In  
the  
future,  
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>

Query With Context including occupancy

 <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query>  
<Checkin>2025-07-10</Checkin>  
<Nights>2</Nights>  
<PropertyContextList>  
<PropertyContext>  
<Property>8675309</Property>  
<Context>  
<UserCountry>US</UserCountry>  
</Context>  
<Occupancy>3</Occupancy>  
<OccupancyDetails>  
<NumAdults>2</NumAdults>  
<Children>  
<Child  
age="7"/>  
</Children>  
</OccupancyDetails>  
</PropertyContext>  
<PropertyContext>  
<Property>8675310</Property>  
<Context>  
<UserCountry>GB</UserCountry>  
</Context>  
<Occupancy>1</Occupancy>  
<OccupancyDetails>  
<NumAdults>1</NumAdults>  
</OccupancyDetails>  
</PropertyContext>  
</PropertyContextList>
</Query>

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

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>