QueryControl Messages

QueryControl messages define the maximum boundaries that Google uses for itineraries. Google updates prices for hotels that are defined in your Hotel List Feed, and uses the settings in the QueryControl message to determine the "size" of the updates. By defining the boundaries of pricing updates in a QueryControl message, you can limit the amount of bandwidth that Google uses to update pricing data.

Overview of QueryControl messages

QueryControl messages define the number of days in advance of check-in for the stay that will be queried by Google. You can also use QueryControl messages to override these values for certain properties. In addition, you can use the QueryControl message to exclude properties from being repriced.

The location that the QueryControl messages are sent is defined by you and given to your Technical Account Manager (TAM) during configuration.

By default, Google fetches a new QueryControl message every 24 hours from your server, so settings can be changed once per day with this method.

To remove a hotel from inventory immediately, you can use a Transaction message. For more information, see Removing Inventory.

Each QueryControl message replaces the values of the previous message. As a result, if you make any changes to your QueryControl message, you must include all data when you create a new QueryControl message.

QueryControl message syntax

The root element of a QueryControl message is the <QueryControl> element. This element has no attributes.

You define default itinerary settings with a top-level <ItineraryCapabilities> element. You can then define one or more overrides with <PropertyOverride> elements, also in the <ItineraryCapabilities> block. If you use hints, you can instruct Google to allow multiple hotels for each itinerary with the <HintControl> element. For more information, see Hint Response Messages.

QueryControl messages use the following syntax:

<?xml version="1.0" encoding="UTF-8"?>
<QueryControl>
  <ItineraryCapabilities>
    <!-- Define one DefaultValue block for all hotels -->
    <DefaultValue>
      <State>[ enabled | disabled ]</State>
      <MinAdvancePurchase>minimum_advanced_purchase</MinAdvancePurchase>
      <MaxAdvancePurchase>maximum_advanced_purchase</MaxAdvancePurchase>
      <MinLengthOfStay>minimum_length_of_stay</MinLengthOfStay>
      <MaxLengthOfStay>maximum_length_of_stay</MaxLengthOfStay>
    </DefaultValue>

    <!-- Define any number of PropertyOverride blocks -->
    <PropertyOverride>
      <State>[ enabled | disabled ]</State>
      <MinAdvancePurchase>minimum_advanced_purchase</MinAdvancePurchase>
      <MaxAdvancePurchase>maximum_advanced_purchase</MaxAdvancePurchase>
      <MinLengthOfStay>minimum_length_of_stay</MinLengthOfStay>
      <MaxLengthOfStay>maximum_length_of_stay</MaxLengthOfStay>
      <!-- At least one property is required for each PropertyOverride block -->
      <Property>hotel_ID</Property>
      ...
    </PropertyOverride>
    ...
  </ItineraryCapabilities>

  <HintControl>
    <!-- Optional. For use with hints only. -->
    <MultipleItineraries>checkin_range|affected_dates</MultipleItineraries>
  </HintControl>

  <!-- Deprecated. Use PropertyOverride instead. -->
  <Item>
    <Property>hotel_ID</Property>
    <MaxAdvancePurchase>maximum_advanced_purchase</MaxAdvancePurchase>
    <MaxLengthOfStay>maximum_length_of_stay</MaxLengthOfStay>
  </Item>

</QueryControl>

The following sections describe the elements of a QueryControl message in detail.

<DefaultValue> element details

The <DefaultValue> block in an <ItineraryCapabilities> block defines itinerary settings for all properties. These settings can be overridden for specified properties with <PropertyOverride> blocks.

The following table describes the child elements of the <DefaultValue> element (within an <ItineraryCapabilities> block):

Element Description
<MinAdvancePurchase>
<MaxAdvancePurchase>
Defines the number of days in advance of check-in for which Google can fetch prices.

<MinAdvancePurchase> is the minimum number of days; <MaxAdvancePurchase> is the maximum number of days.

For example, if <MinAdvancePurchase> is 10 and <MaxAdvancePurchase> is 240, Google can fetch prices for stays that begin between 10 and 240 days from today, inclusive.

The value of <MinAdvancePurchase> only controls fetching, not serving. After fetching stops for an itinerary, it will continue to be served for an amount of time before becoming expired. This time is determined by Google.

The values of these elements are used in conjunction with <MinLengthOfStay> and <MaxLengthOfStay> to determine the size of the price update.

The following settings result in up to 4,320 possible prices for each hotel (240 * 18):

<MinAdvancePurchase>0</MinAdvancePurchase>
<MaxAdvancePurchase>240</MaxAdvancePurchase>
<MinLengthOfStay>1</MinLengthOfStay>
<MaxLengthOfStay>18</MaxLengthOfStay>

The value of <MinAdvancePurchase> must be less than or equal to the value of <MaxAdvancePurchase>, and the values of both must be between 0 and 330, inclusive.

The default value of <MinAdvancePurchase> is 0.

You must explicitly set the value of <MaxAdvancePurchase>. There is no default value.

<MinLengthOfStay>
<MaxLengthOfStay>
Defines the length of stay for which Google can fetch prices.

For example, if <MinLengthOfStay> is 3 and <MaxLengthOfStay> is 21, Google can fetch price data for offers with a length of stay between 3 and 21 days, inclusive.

The values of these elements are used in conjunction with <MinAdvancePurchase> and <MaxAdvancePurchase> to determine the size of the price update.

For Pull with Hints, Google fetches data for 1 to 5 nights of stay, unless you explicitly set the value of <MinLengthOfStay> and/or <MaxLengthOfStay>.

The value of <MinLengthOfStay> must be less than or equal to the value of <MaxLengthOfStay>, and the values of both must be between 1 and 30, inclusive.

The default value of <MinLengthOfStay> is 1.

You must explicitly set the value of <MaxLengthOfStay>. There is no default value.

<State> Whether to include or exclude all properties from pricing updates. Set to "enabled" to include properties in repricing updates. Set to "disabled" to exclude properties from pricing updates. Disabled properties are not included in Live Queries, hints, or any other pricing update messages.

The default value of <State> is "enabled".

You can override the value of this element for individual properties by using the <PropertyOverride> element.

You can override settings in the <DefaultValue> block for individual hotels. To do this, create one or more <PropertyOverride> blocks, also in the <ItineraryCapabilities> block.

<PropertyOverride> element details

<PropertyOverride> blocks contained within an <ItineraryCapabilities> block define repricing settings for the properties within that block. These repricing settings override the values you set in the <DefaultValue> block only for those properties that you specify in <PropertyOverride>. You can also use <PropertyOverride> blocks to disable repricing of certain properties.

Each <PropertyOverride> block contains one or more <Property> elements.

You can define any number of <PropertyOverride> blocks in an <ItineraryCapabilities> block. For example, you can use one <PropertyOverride> block to disable repricing of one set of properties, and another block to define properties to reprice with a much wider range of itineraries than your defaults. A third block could define very narrow itineraries.

The following table describes the child elements of the <PropertyOverride> element (within an <ItineraryCapabilities> block):

Element Description
<MinAdvancePurchase>
<MaxAdvancePurchase>
Same as <MinAdvancePurchase> and <MaxAdvancePurchase> in the <DefaultValue> block, except that this value applies to the hotels in this <PropertyOverride> block only.
<MinLengthOfStay>
<MaxLengthOfStay>
Same as <MinLengthOfStay> and <MaxLengthOfStay> in the <DefaultValue> block, except that this value applies to the hotels in this <PropertyOverride> block only.
<Property> The ID of the hotel that matches the ID you set in your Hotel List Feed.
<State> Whether to include or exclude the listed properties from pricing updates. Set to "enabled" to include the properties in repricing updates. Set to "disabled" to exclude properties from pricing updates. Disabled properties are not included in Live Queries, hints, or any other pricing update messages.

The value of <State> applies to properties specified in <Property> child elements of this <PropertyOverride> block only.

The default value of <State> is "enabled".

Each property can appear in a single <PropertyOverride> block only.

<HintControl> element details

A QueryControl message can optionally contain a <HintControl> block. Within this block you can use the <MultipleItineraries> element to configure your Hint Response messages. The value of the <MultipleItineraries> element defines whether you can specify multiple hotels for each itinerary or date range in a Hint Response message. You can specify one of the following values for this element:

  • checkin_range: Lets you specify multiple properties and multiple itineraries for Check-in Date Range hints. These are hints in which you set the values of the <FirstDate> and <LastDate> child elements of <Item>.
  • affected_dates: Lets you specify multiple properties for Check-in Date Range or Ranged Itinerary hints. These are hints in which you set the values of the <FirstDate> and <LastDate> child elements of <Item>, or use the <StaysIncludingRange> element.
  • Omitted (default): If you do not specify a value for the <MultipleItineraries> element, then you can only specify one hotel for each <Item> block in a Hint Response message.

For more information, see Hint Response Messages.

<Item> element details (Deprecated)

NOTE: The <Item> element is deprecated. Documentation is included here for legacy implementations. Use the <PropertyOverride> inside the <ItineraryCapabilities> block instead.

The following table describes the child elements of the <Item> element in a QueryControl message:

Element Required Description
<MaxAdvancePurchase> Required Same as <MaxAdvancePurchase> in the <DefaultValue> block, except that this value applies to the hotels in this <Item> block only.
<MaxLengthOfStay> Required Same as <MaxLengthOfStay> in the <DefaultValue> block, except that this value applies to the hotel in this <Item> block only.
<Property> Required The ID of the hotel that matches the ID you set in your Hotel List Feed.

QueryControl message examples

This section includes several examples of QueryControl messages.

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

You can use the Feed Validation tool in Hotel Ads Center to ensure that your QueryControl messages conform to this schema. For more information, see Tools.

For examples that use <HintControl> blocks, see Hint Response Messages.

Setting defaults example

The following example shows a QueryControl message that defines the pricing settings for all hotels:

<?xml version="1.0" encoding="UTF-8"?>
<QueryControl>
  <ItineraryCapabilities>
    <!-- Define defaults for all properties. -->
    <DefaultValue>
      <MaxAdvancePurchase>210</MaxAdvancePurchase>
      <MaxLengthOfStay>18</MaxLengthOfStay>
    </DefaultValue>
  </ItineraryCapabilities>
</QueryControl>

Defining overrides example

The following example builds on the previous example and defines several blocks that override the defaults:

<?xml version="1.0" encoding="UTF-8"?>
<QueryControl>
  <ItineraryCapabilities>
    <!-- Define defaults for all properties. -->
    <DefaultValue>
      <MaxAdvancePurchase>210</MaxAdvancePurchase>
      <MaxLengthOfStay>18</MaxLengthOfStay>
    </DefaultValue>

    <!-- Define different values for several properties. -->
    <PropertyOverride>
      <MinAdvancePurchase>4</MinAdvancePurchase>
      <MaxAdvancePurchase>320</MaxAdvancePurchase>
      <MinLengthOfStay>7</MinLengthOfStay>
      <MaxLengthOfStay>21</MaxLengthOfStay>
      <Property>12345</Property>
      <Property>67891</Property>
      <Property>060773</Property>
    </PropertyOverride>

    <!-- Define narrower values for a single property. -->
    <PropertyOverride>
      <MaxAdvancePurchase>60</MaxAdvancePurchase>
      <MinLengthOfStay>6</MinLengthOfStay>
      <MaxLengthOfStay>8</MaxLengthOfStay>
      <Property>8675309</Property>
    </PropertyOverride>

  </ItineraryCapabilities>
</QueryControl>

Disabling properties example

The following example builds on the previous examples and prevents several hotels from being repriced:

<?xml version="1.0" encoding="UTF-8"?>
<QueryControl>
  <ItineraryCapabilities>
    <!-- Define defaults for all properties. -->
    <DefaultValue>
      <MaxAdvancePurchase>210</MaxAdvancePurchase>
      <MaxLengthOfStay>18</MaxLengthOfStay>
    </DefaultValue>

    <!-- Prevent several properties from being repriced. -->
    <PropertyOverride>
      <State>disabled</State>
      <Property>11235</Property>
      <Property>81321</Property>
      <Property>345589</Property>
    </PropertyOverride>

    <!-- Define different values for several properties. -->
    <PropertyOverride>
      <MinAdvancePurchase>4</MinAdvancePurchase>
      <MaxAdvancePurchase>320</MaxAdvancePurchase>
      <MinLengthOfStay>7</MinLengthOfStay>
      <MaxLengthOfStay>21</MaxLengthOfStay>
      <Property>12345</Property>
      <Property>67891</Property>
      <Property>060773</Property>
    </PropertyOverride>

    <!-- Define narrower values for a single property. -->
    <PropertyOverride>
      <MaxAdvancePurchase>60</MaxAdvancePurchase>
      <MinLengthOfStay>6</MinLengthOfStay>
      <MaxLengthOfStay>8</MaxLengthOfStay>
      <Property>8675309</Property>
    </PropertyOverride>

  </ItineraryCapabilities>
</QueryControl>