Query & Hints XML Reference

    This section provides a reference for the Google XML-based Hint Request messages , Hint Response messages , and Query messages .

    <Hint> (Hint Response message)

    The root element of a Hint Response message. Hint Response messages specify which hotel or itinerary combinations should be repriced. They are your response to a Hint Request message from Google.

    A Hint Response message should specify only those hotels whose prices have changed since the last time Google received a successful Hint Response from your servers.

    Hint Response messages use one of the following methods to specify which hotels and itineraries Google should reprice:

    • Exact itineraries: A combination of check-in date and length of stay.

    • Check-in date ranges: Specifies a range of check-in dates, beginning with the first check-in date and ending with the last check-in date.

    • Ranged stays(or ranged itineraries )

    Each of these methods requires a different syntax for the Hint Response message.

    For more information, consult Hint Response messages .

    Syntax

    The <Hint> element uses different syntax, depending on the type of Hint Response message:

    Exact itineraries

    The following shows the syntax for exact itineraries in a Hint Response message:

     <!--  
Exact  
Itinerary  
Hint  
Response  
-->
<?xml  
version="1.0"  
encoding="UTF-8"?>
<Hint>  
<Item>  
<Property> hotel_ID 
</Property>  
...  
<Stay>  
<CheckInDate> checkin_date 
</CheckInDate>  
<LengthOfStay> number_of_nights 
</LengthOfStay>  
</Stay>  
</Item>  
...
</Hint>

    Check-in ranges

    The following shows the syntax for check-in ranges in a Hint Response message:

     <!--  
Check-in  
Ranges  
Hint  
Response  
-->
<?xml  
version="1.0"  
encoding="UTF-8"?>
<Hint>  
<Item>  
<!--  
At  
least  
one  
is  
required  
-->  
<Property> hotel_ID 
</Property>  
[...]  
<!--  
Required  
-->  
<FirstDate> first_checkin_date 
</FirstDate>  
<!--  
Required  
-->  
<LastDate> last_checkin_date 
</LastDate>  
</Item>  
...
</Hint>

    Ranged stays

    The following shows the syntax for ranged stays in a Hint Response message:

     <!--  
Ranged  
Stay  
Hint  
Response  
-->
<?xml  
version="1.0"  
encoding="UTF-8"?>
<Hint>  
<Item>  
<!--  
At  
least  
one  
is  
required  
-->  
<Property>1458700</Property>  
<Property>5418701</Property>  
<StaysIncludingRange>  
<!--  
Required  
-->  
<FirstDate>2025-04-28</FirstDate>  
<!--  
Optional  
-->  
<LastDate>2025-04-29</LastDate>  
</StaysIncludingRange>  
</Item>  
...
</Hint>

    Attributes

    The <Hint> element contains an optional attribute: id . When provided, it is included as the hintId attribute in <Query> messages sent based on this <Hint> .

    Child elements

    The <Hint> element has the following child elements:

    Child Element
    Required?
    Type
    Hint Response Type
    Description
    <CheckInDate>
    Required
    Date
    Exact itineraries
    The check-in date for the itinerary.
    <FirstDate>
    Required
    Date
    Check-in ranges and ranged itineraries
    The first date of the date range for a check-in range or ranged stay Hint Response message. Dates are inclusive.
    <Item>
    Required
    Object
    All
    A container for the hotel/itinerary to be updated.
    <LastDate>
    Required*
    Date
    Check-in ranges and ranged itineraries

    The last date of the date range for a check-in range or ranged stay Hint Response message. Dates are inclusive.

    * This element is optional for ranged stays.

    <LengthOfStay>
    Required
    integer
    Exact itineraries
    The number of nights for the itinerary, expressed as a positive integer.
    <Property>
    Required
    string
    All

    The ID of a hotel, using the same ID as the Hotel List . The number of <Property> elements you can specify in a single <Item> block is determined by the type of Hint Response message:

    • Exact itineraries: Up to 100 hotels.
    • Check-in ranges: More than one if you set <MultipleItineraries> to "checkin_range" in your <QueryControl> message.
    • Ranged stay: More than one if you set <MultipleItineraries> to "affected_dates" in your <QueryControl> message.
    <Stay>
    Required
    Object
    Exact itineraries
    A container for the <CheckinDate> and <LengthOfStay> elements in an exact itinerary Hint Response message. Each <Item> can contain only a single <Stay> .
    <StaysIncludingRange>
    Required
    Object
    Ranged itineraries
    A container for the <FirstDate> and <LastDate> elements in a ranged stay Hint Response message.

    Examples

    Exact itineraries

    The following example defines multiple itineraries for a single property a Hint Response message:

     <!--  
Exact  
Itinerary  
Hint  
Response  
-->
<?xml  
version="1.0"  
encoding="UTF-8"?>
<Hint>  
<Item>  
<Property>12345</Property>  
<Stay>  
<CheckInDate>2018-07-03</CheckInDate>  
<LengthOfStay>3</LengthOfStay>  
</Stay>  
</Item>  
<Item>  
<Property>12345</Property>  
<Stay>  
<CheckInDate>2018-07-03</CheckInDate>  
<LengthOfStay>4</LengthOfStay>  
</Stay>  
</Item>
</Hint>

    Check-in ranges

    The following example specifies two hotels whose pricing has changed and should be fetched again. Google gets all itineraries between July 3 and July 6 for properties 12345 and 67890:

     <!--  
Check-in  
Ranges  
Hint  
Response  
-->
<?xml  
version="1.0"  
encoding="UTF-8"?>
<Hint>  
<Item>  
<Property>12345</Property>  
<Property>67890</Property>  
<FirstDate>2018-07-03</FirstDate>  
<LastDate>2018-07-06</LastDate>  
</Item>
</Hint>

    Ranged stays

    The following example shows two different uses of ranged stays, one for a range of nights and the other for a single night:

     <!--  
Ranged  
Stay  
Hint  
Response  
-->
<?xml  
version="1.0"  
encoding="UTF-8"?>
<Hint>  
<!--  
Google  
fetches  
prices  
for  
all  
itineraries  
(first  
and  
last  
date  
are  
set)  
-->  
<Item>  
<Property>12345</Property>  
<StaysIncludingRange>  
<FirstDate>2018-07-03</FirstDate>  
<LastDate>2018-07-06</LastDate>  
</StaysIncludingRange>  
</Item>  
<!--  
Google  
fetches  
prices  
for  
a  
single  
night  
(first  
date  
only)  
-->  
<Item>  
<Property>67890</Property>  
<StaysIncludingRange>  
<FirstDate>2018-07-03</FirstDate>  
</StaysIncludingRange>  
</Item>
</Hint>

    For each of these examples, Google responds with a <Query> , and you should then respond with a <Transaction> that includes price updates for the specified hotels/itineraries.

    <HintRequest>

    The root element of a Hint Request message. Google sends a Hint Request message to your server and expects a response that specifies the hotels and itineraries whose prices have changed since the last time Google received a successful Hint Response from your server.

    If there are any price changes, Google then sends a <Query> that fetches the updated pricing data for the indicated hotels and itineraries.

    For more information, consult Hint Request Messages .

    Syntax

    The <HintRequest> element uses the following syntax:

    Syntax

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<HintRequest>  
<LastFetchTime> last_fetch_time 
</LastFetchTime>
</HintRequest>

    Attributes

    The <HintRequest> element has no attributes.

    Child elements

    The <HintRequest> element has the following child elements:

    Child Element Type Description
    <LastFetchTime>
    		DateTime The last time that Google succeeded in getting a Hint Response message to a Hint Request message.

    If this time is older than the last time you updated prices on your server, then you should respond with a Hint Response message specifying which hotels have changed.

    If there hasn't been a recent successful fetch, this will be set to a fixed interval value (to avoid more serious issues with large backlogs). The current fixed interval value is 1000 seconds, but is subject to change.

    For more information, consult Hint Response Messages .

    Examples

    The following example shows a Hint Request message:

    Hint Request message

    The following example shows a Hint Request message:

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<HintRequest  
id="ABCDEF"  
timestamp="2018-06-07T16:20:00Z">  
<LastFetchTime>2018-03-25T00:04:09Z</LastFetchTime>
</HintRequest>

    <Query>

    The root element of a Query message. Query messages are requests from Google for pricing or metadata updates. They are used with both the Pull and Changed pricing delivery modes .

    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:Google responds to a specific user request, asking for a real-time price update. When partners receive a Live pricing query message, partners should respond with a <Transaction> message that contains requested pricing information in <Result> elements.

    • With context pricing:Google updates its price cache based on contexts which are historically popular. When you receive a With context query message, you should respond with a <Transaction> message that contains the requested pricing information in <Result> elements.

    • Metadata:Google requests metadata updates for the rooms and Room Bundles for the specified hotels. When you receive a Metadata Query message, you should respond with a <Transaction> message that specifies data about the rooms and Room Bundles in <PropertyDataSet> elements. For more information, refer to Room Bundle metadata .

    Syntax

    The <Query> element uses the following syntax:

    Pricing Query

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query>  
<Checkin> YYYY-MM-DD 
</Checkin>  
<Nights> number_of_nights 
</Nights>  
<PropertyList>  
<Property> hotel_id 
</Property>  
...  
</PropertyList>
</Query>

    Live pricing

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query  
latencySensitive= "true_or_false" 
>  
<Checkin> YYYY-MM-DD 
</Checkin>  
<Nights> number_of_nights 
</Nights>  
<!--  
Only  
for  
Check-in  
Date  
Range  
pricing  
queries  
(Changed  
Pricing)  
-->  
<FirstDate> YYYY-MM-DD 
</FirstDate>  
<LastDate> YYYY-MM-DD 
</LastDate>  
<!--  
Only  
for  
Ranged  
Stay  
pricing  
queries  
(Changed  
Pricing)  
-->  
<AffectedNights> number_of_nights 
</AffectedNights>  
<PropertyList>  
<Property> hotel_id 
</Property>  
...  
</PropertyList>  
<!--  
See  
documentation  
below  
for  
<Context>  
-->  
<Context>  
...  
</Context>
</Query>

    With context

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query>  
<Checkin> YYYY-MM-DD 
</Checkin>  
<Nights> number_of_nights 
</Nights>  
<!--  
Only  
for  
Check-in  
Date  
Range  
pricing  
queries  
(Changed  
Pricing)  
-->  
<FirstDate> YYYY-MM-DD 
</FirstDate>  
<LastDate> YYYY-MM-DD 
</LastDate>  
<!--  
Only  
for  
Ranged  
Stay  
pricing  
queries  
(Changed  
Pricing)  
-->  
<AffectedNights> number_of_nights 
</AffectedNights>  
<PropertyContextList>  
<PropertyContext>  
<Property> hotel_id 
</Property>  
...  
<!--  
See  
documentation  
below  
for  
<Context>  
-->  
<Context>  
...  
</Context>  
</PropertyContext>  
</PropertyContextList>
</Query>

    Metadata

     <HotelInfoProperties>  
<Property> property_ID 
</Property>  
...
</HotelInfoProperties>

    Attributes

    The <Query> element may contain one attribute: latencySensitive .

    The latencySensitive attribute is optional. When provided and set to true , it indicates that the query is a Live Pricing Query . To have Google send queries with the latencySensitive attribute, contact your Technical Account Manager (TAM).

    Child elements

    The <Query> element has the following child elements:

    Child Element
    Query Type
    Type
    Description
    <AffectedNights>
    Pricing
    integer
    The number of nights for a ranged stay. This element is used only for Ranged Stay pricing queries used with Changed Pricing.
    <Checkin>
    Pricing
    Date
    The dates of a specific price change.
    <Context>
    Pricing (Live Pricing Queries only)
    <Context>
    For Live Pricing Queries, specifies certain parameters under which the query is made. Child elements include:
    • <Occupancy> : the total number of guests
    • <OccupancyDetails> : the type of guests, such as adults or children
    • <UserCountry> : the country where the user is located
    • <UserDevice> : the type of device the guest used to search for a hotel, such as "mobile ," " tablet ," or " desktop ."

    The <Context> element may be repeated in a single request, allowing queries for different occupancies. Consult <Context> for a list of child elements, syntax, and examples.

    <FirstDate>
    Pricing
    Date
    The start date for a range of itineraries to which the pricing applies. This element is used only for Check-in Date Range pricing queries used with Changed Pricing.
    <HotelInfoProperties>
    Metadata
    string
    One or more properties for which Google wants updated room and Room Bundle metadata in a metadata Query message. This element can contain one or more <Property> elements that specify hotel property IDs.
    <LastDate>
    Pricing
    Date
    The end date for a range of itineraries to which the pricing applies. This element is used only for Check-in Date Range pricing queries used with Pull + Hints.
    <Nights>
    Pricing
    integer
    The number of nights for a particular itinerary, up to 30.
    <PropertyList>
    Pricing
    Object

    One or more IDs for hotel that require pricing updates.

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

    <PropertyList>
  <Property>pid1</Property>
  <Property>pid2</Property>
</PropertyList>

    Examples

    Pricing query

    The following example shows a pricing Query message that requests price updates for a set of 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>

    Live pricing query

    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">  
<Checkin>2017-06-07</Checkin>  
<Nights>5</Nights>  
<DeadlineMs>500</DeadlineMs>  
<PropertyList>  
<Property>8675309</Property>  
</PropertyList>  
<Context>  
<Occupancy>4</Occupancy>  
<OccupancyDetails>  
<NumAdults>2</NumAdults>  
<Children>  
<Child  
age="8"/>  
<Child  
age="5"/>  
</Children>  
</OccupancyDetails>  
<UserCountry>US</UserCountry>  
<UserDevice>mobile</UserDevice>  
</Context>
</Query>

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

    Metadata query

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query>  
<HotelInfoProperties>  
<Property>pid5</Property>  
<Property>pid8</Property>  
<Property>pid13</Property>  
<Property>pid21</Property>  
</HotelInfoProperties>
</Query>

    For additional examples, including ranged stay and check-in date range pricing queries, check out the Query message examples .

    <Context>

    The <Context> element describes information for a Live pricing query , including the number and type of guests, the user country, and user device.

    Multiple <Context> will never be used with different user countries or user devices. When multiple <Context> are used to query for multiple occupancies, provide each occupancy price as an additional Room Bundle for the corresponding property or itinerary. Each property or itinerary should have a single <Result> block with the prices for multiple occupancies included.

    For the response details for the <Context> query, see <OccupancyDetails> .

    Syntax

    The <Context> element uses the following syntax:

    Syntax

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query  
latencySensitive= "true_or_false" 
>  
<Checkin> date 
</Checkin>  
<Nights> number_of_nights 
</Nights>  
<DeadlineMs> number_of_milliseconds 
</DeadlineMs>  
<PropertyList>  
<Property> property_ID 
</Property>  
</PropertyList>  
<Context>  
<Occupancy> total_number_of_guests 
</Occupancy>  
<OccupancyDetails>  
<NumAdults> number_of_adults 
</NumAdults>  
<Children>  
<Child  
age= age_of_one_child_guest 
/>  
<Child  
age= age_of_one_child_guest 
/>  
</Children>  
</OccupancyDetails>  
<UserCountry> end_user_country 
</UserCountry>  
<UserDevice> user_device_type 
</UserDevice>  
</Context>
</Query>

    Child elements

    The <Context> element has the following child elements:

    Child Element
    Query type
    Type
    Description
    <Occupancy>
    Pricing
    integer
    Specifies the total number of guests.

    While not mandatory, queries with <Occupancy> should result in a transaction message with the appropriate Room Bundles defined for each <Occupancy> , but if the Room Bundles are unavailable it is recommended that you specify the <Occupancy> element.

    Note: <Occupancy> may not always appear in a query. In such cases, you should return prices of all occupancies.

    <OccupancyDetails>
    Pricing
    Object
    Is preceded by <Occupancy> . Specifies guests by type, including:
    • <NumAdults> : number of adult guests
    • <Children> and <Child=" age "> : Specifies which guests are children (typically age 0-17), and optionally includes each child's age.

    While not mandatory, queries with <OccupancyDetails> should result in a transaction message with the appropriate Room Bundles defined for each <Occupancy> , but if the Room Bundles are unavailable it is recommended that you specify the <OccupancyDetails> element.

    Note: <OccupancyDetails> may not always appear in a query. In such cases, you should assume that all guests are adults.

    <UserCountry>
    Pricing
    string

    Filters rates by the country where user is located. The value is a 2-letter country code such as "US" for United States, or a region code, such as "EU" for "Europe".

    Queries with <UserCountry> defined should result in a transaction message with the appropriate <Rates> block defined for the queried country.

    <UserDevice>
    Pricing
    string

    Filters rates by the type of the device the user is searching from. Possible values:

    • mobile
    • desktop
    • tablet

    Queries with <UserDevice> defined should result in a transaction message with the appropriate <Rates> block defined for the queried device type.

    Examples

    Occupancy

    The following example shows a Live pricing query for <Occupancy> within <Context> . The Live pricing query is for 3 adult guests.

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query  
latencySensitive="true">  
<Checkin>2017-06-07</Checkin>  
<Nights>4</Nights>  
<DeadlineMs>500</DeadlineMs>  
<PropertyList>  
<Property>45617</Property>  
</PropertyList>  
<Context>  
<Occupancy>3</Occupancy>  
<UserCountry>US</UserCountry>  
<UserDevice>mobile</UserDevice>  
</Context>
</Query>

    Occupancy details

    The following example shows a Live pricing query with <OccupancyDetails> within <Context> . The Live pricing query is for 4 guests, 2 of which are children, and seeks a rate applicable to a US guest booking from a mobile device:

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query  
latencySensitive="true">  
<Checkin>2017-06-07</Checkin>  
<Nights>5</Nights>  
<DeadlineMs>500</DeadlineMs>  
<PropertyList>  
<Property>8675309</Property>  
</PropertyList>  
<Context>  
<Occupancy>4</Occupancy>  
<OccupancyDetails>  
<NumAdults>2</NumAdults>  
<Children>  
<Child  
age="4"/>  
<Child  
age="12"/>  
</Children>  
</OccupancyDetails>  
<UserCountry>US</UserCountry>  
<UserDevice>mobile</UserDevice>  
</Context>
</Query>

    Multiple contexts

    The following example shows the use of an additional <Context> element in a Live pricing query.

     <?xml  
version="1.0"  
encoding="UTF-8"?>
<Query  
latencySensitive="true">  
<Checkin>2017-06-07</Checkin>  
<Nights>4</Nights>  
<DeadlineMs>500</DeadlineMs>  
<PropertyList>  
<Property>45617</Property>  
</PropertyList>  
<Context>  
<Occupancy>3</Occupancy>  
<UserCountry>US</UserCountry>  
<UserDevice>mobile</UserDevice>  
</Context>  
<Context>  
<Occupancy>6</Occupancy>  
<OccupancyDetails>  
<NumAdults>4</NumAdults>  
<Children>  
<Child  
age="6"/>  
<Child  
age="10"/>  
</Children>  
</OccupancyDetails>  
<UserCountry>US</UserCountry>  
<UserDevice>mobile</UserDevice>  
</Context>
</Query>
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: