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.

Query message overview

There are two types of Query messages:

  • Pricing: Google sends a Query message that requests pricing updates for the specified hotels. 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 Updating Prices.

    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: Google sends a Query message that requests metadata updates for the rooms and Room Bundles in the specified hotels. When your server receives a metadata Query message, it should respond with a Transaction message that contains the requested details about rooms and Room Bundles within those properties. For more information, see Defining Room and Package Metadata.

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.

You define default settings for itineraries in QueryControl messages, which are updated once per day. You can also use QueryControl messages to include or exclude certain hotels from your inventory.

Query message syntax

The root element of Query messages from Google is <Query>. This element does not have any attributes.

The structure of the Query message depends on the type of message; "pricing" Query messages and "metadata" Query messages use different syntax, as described in the following sections.

Pricing query message syntax

Pricing Query messages specify the property/itinerary combinations for which you supply prices.

The following XML structure shows the pricing Query message syntax:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Required -->
<Query>
  <Checkin>YYYY-MM-DD</Checkin>

  <Nights>number_of_nights</Nights>

  <!-- Only for Check-in Date Range queries (Pull + Hints) -->
  <FirstDate>itinerary_range_start_date</FirstDate>
  <LastDate>itinerary_range_end_date</LastDate>

  <!-- Only for Ranged Stay queries (Pull + Hints) -->
  <AffectedNights>affected_nights</AffectedNights>

  <PropertyList>
    <Property>hotel_id</Property>
     ...
  </PropertyList>

  <!-- Only for Live Queries -->
  <LatencySensitive>[ false | true ]</LatencySensitive>
  <DeadlineMs>timeframe</DeadlineMs>

</Query>

The following table describes the attributes and top-level elements of a pricing Query message:

Element/Attribute Description
<Nights> Specifies the number of nights for a particular itinerary, up to 14. The value of this element is a positive integer.

The following example sets the number of nights to 3:

<Nights>3</Nights>
<Checkin> Specifies the dates of a specific price change. Dates are in the form YYYY-MM-DD, where YYYY represents a four-digit year, MM represents a two-digit month, and DD represents a two-digit day.

The following example sets the date to July 14, 2014:

<Checkin>2014-07-14</Checkin>
<PropertyList>

Contains one or more <Property> elements that specify IDs of hotels that require pricing updates.

The value of each <Property> element is a string that matches a hotel ID in your Hotel List Feed. For example:

<PropertyList>
  <Property>pid1</Property>
  <Property>pid2</Property>
</PropertyList>
<FirstDate> Specifies the start date for a range of itineraries to which the pricing applies. This element is used only for Check-in Date Range queries used with Pull + Hints.
<LastDate> Specifies the end date for a range of itineraries to which the pricing applies. This element is used only for Check-in Date Range queries used with Pull + Hints.
<AffectedNights> Specifies the number of nights for a ranged stay. This element is used only for Ranged Stay queries used with Pull with Hints.
<LatencySensitive> (Live Querying only) "true" if the request is a Live Query. Otherwise, "false".

When set to "true", you must respond to the Live Query within the number of milliseconds specified by <DeadlineMs>.

For more information, see Live Queries.

<DeadlineMs> (Live Querying only) Specifies the amount of time, in milliseconds, that you have to respond to a Live Query. If you respond with a price within this amount of time, then your ad can be included in the auction. If you do not respond within this amount of time, then you risk not being part of the auction.

The presence of this value indicates that the request is a Live Query. Messages that do not include this element are not Live Queries.

For more information, see Live Queries.

Metadata query message syntax

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

Query messages that request metadata updates use the <HotelInfoProperties> element. This element contains one or more <Property> elements that list the hotels for which Google requests updates.

The following XML structure shows the metadata Query message syntax:

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <HotelInfoProperties>
    <Property>property_id</Property>
    ...
  </HotelInfoProperties>
</Query>

The following table describes the top-level elements of a metadata Query message:

Element Description
<HotelInfoProperties> Contains a list of hotel properties for which Google requests updated room and Room Bundle metadata for. This element can contain one or more <Property> elements that contain hotel property IDs.

The Query message schema defines the structure and constraints of a Query message. For more information, see Schemas.

Controlling queries

This section describes how you control which properties and/or itineraries can be the subject of queries.

Itinerary capabilities

Itinerary capabilities determine the possible boundaries of pricing queries. You define rules that determine the range of dates and maximum lengths of stay that you support.

To define your itinerary capabilities, use the following elements in the QueryControl message:

  • <MaxAdvancePurchase>
  • <MaxLengthOfStay>

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.

For more information, see QueryControl Messages.

Excluding properties

You can disable queries for groups of properties by using the <PropertyOverride> element in your QueryControl message. 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 your QueryControl message. Set the value of the <State> child element 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":

<PropertyOverride>
  <State>disabled</State>
  <Property>8675309</Property>
  <Property>060773</Property>
  <Property>42</Property>
</PropertyOverride>

To enable a block of hotels that were previously disabled, change the value of the <State> element 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 your QueryControl message, but each hotel ID can appear in only one block.

For more information about editing the QueryControl messages, see QueryControl Messages.

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

  • The cached prices are outdated, based on Google's estimation.
  • 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.

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 currently request information for a single hotel/itinerary combination.

You configure Live Queries in your QueryControl messages, as you would other query settings. You can limit Live Queries by the number of days for advanced purchases, lengths of stays, and properties to exclude.

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 message 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>2014-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>
  <Checkin>2015-06-07</Checkin>
  <Nights>46</Nights>
  <PropertyList>
    <Property>8675309</Property>
  </PropertyList>
  <LatencySensitive>true</LatencySensitive>
  <DeadlineMs>500</DeadlineMs>
</Query>

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

6/07/15 - 7/23/15

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.

In addition, Google can specify more than one hotel in a Query message, depending on the value of the QueryControl message's <MultipleItineraries> element. For more information, see QueryControl 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-13</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.