Query messages are requests from Google for pricing or metadata updates. They
are used with both the Pull and Changed Pricing
[delivery modes](https://developers.google.com/hotels/hotel-prices/dev-guide/query-messages).

The root element of Query messages is [`<Query>`](https://developers.google.com/hotels/hotel-prices/xml-reference/queries#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](https://developers.google.com/hotels/hotel-prices/xml-reference/queries).

## 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>`](https://developers.google.com/hotels/hotel-prices/xml-reference/transaction-messages#Transaction) message that contains the requested pricing information.

For more information, see [Pricing Overview](https://developers.google.com/hotels/hotel-prices/dev-guide/updating-prices).

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.

> [!IMPORTANT]
> **Key Point:** Due to the [New Search experience](https://developers.google.com/search/blog/2024/02/search-experiences-in-eea), Live Query is no longer available when the user is in an EEA country and issues a navigational (hotel-specific) query with dates or changes dates in the search results page.

### 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](https://developers.google.com/hotels/hotel-prices/dev-guide/room-bundles),
if it is a price for a specific occupancy and as a [Conditional Rate](https://developers.google.com/hotels/hotel-prices/dev-guide/fenced-rates),
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](https://developers.google.com/hotels/hotel-prices/dev-guide/fenced-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.

> [!IMPORTANT]
> **Key Point:** Language isn't specified in With Context request messages. So, if you specify `<LanguageCode>` in your rate rules, then the With Context response should include all relevant language-specific rates. If you aren't sure, it is recommended that you use country conditions instead of language conditions for determining user origin or nationality. However, if you have rates which are specific to the primary language of the user, then use language conditions.

## 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>`](https://developers.google.com/hotels/hotel-prices/xml-reference/transaction-messages#Transaction) message that specifies pricing for the requested properties
in [`<Result>`](https://developers.google.com/hotels/hotel-prices/xml-reference/transaction-messages#Result) elements.

For more information, see [Defining room and package metadata](https://developers.google.com/hotels/hotel-prices/dev-guide/room-bundles#metadata).

## 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](https://developers.google.com/hotels/hotel-prices/xml-reference/queries).

### Sample itinerary

The following example shows a pricing [`<Query>`](https://developers.google.com/hotels/hotel-prices/xml-reference/queries#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>

> [!NOTE]
> **Note:** Child occupancy rates should only be send through Live pricing with context and not through Pull or Changed pricing.

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](https://developers.google.com/hotels/hotel-prices/xml-reference/transaction-messages).

### 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](https://developers.google.com/hotels/hotel-prices/dev-guide/hint-response-messages).

The following example shows a pricing [`<Query>`](https://developers.google.com/hotels/hotel-prices/xml-reference/queries#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/25/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>`](https://developers.google.com/hotels/hotel-prices/xml-reference/queries#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>`](https://developers.google.com/hotels/hotel-prices/xml-reference/queries#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](https://developers.google.com/hotels/hotel-prices/dev-guide/room-bundles#metadata).