Search
Clear search
Close search
Google apps
Main menu

Using Room Bundles

This section describes the following topics:

Overview: Key Concepts and Workflow

With Room Bundles, you can now offer additional combinations of physical room types with different service packages. Room Bundles let you define multiple room types for a single property, or combine an itinerary of a room with additional services and conditions of sale to your users beyond a standard price. Here's why Room Bundles are so powerful:

  • Showcase higher revenue rooms
  • Increases Click Through Rate
  • Differentiate your listing from competitors
  • Offer users additional room options

 

The following image shows examples of Room Bundles:

In this example, the first "bundle" is likely the base room. The second is a different room type within the same property. The third is a "premium" package of the base room, which might include amenities such as free breakfast or a later checkout.

Displaying Room Bundles in search results is governed by the same selection process as standard room rates. For information about the benefits of Room Bundles, see Using Room Bundles to boost performance.

Metadata

When defining Room Bundles, you typically set the description, amenities, and other information about the Room Bundle ahead of time. This information is known as the Room Bundle metadata. You then reference this metadata in your pricing updates, but don't include it in the pricing update messages.

<RoomData> and <PackageData> elements define itinerary-independent metadata for your properties' rooms and Room Bundles. Using these elements can significantly reduce the size of the feed because it reduces the amount of repetitive data sent in Transaction messages. For example, data such as a room name and description is typically repeated for every itinerary. You can use the <RoomData> and <PackageData> elements to define this type of data once. Itinerary-specific Room Bundle data is then merged with the stored room and package definitions for display.

When you define metadata with a <RoomID> or <PackageID>, Google uses those IDs to find the stored metadata. Google then merges this data with itinerary-specific data to render the contents of your ads. There is special processing to combine the name and description from the <RoomData> and <PackageData> elements, allowing the physical room to be described in <RoomData> and package details to be in <PackageData>. If you define both the room data and package data for a single room or Room Bundle, Google includes both in the ad output, separated by a hyphen.

Data Precedence

Room Bundle data is gathered from all sources and combined, using precedence rules, to produce the final data for a given hotel, itinerary and Room Bundle. The ordering is as follows, from lowest to highest precedence:

  • <PartnerData>
  • <PropertyData>
  • <RoomData>, where the <RoomID> matches the <RoomID> in the <RoomBundle> block
  • <PackageData>, where the <PackageID> matches the <PackageID> in the <RoomBundle> block
  • <RoomBundle>

Room Bundle Child Elements

The following table describes the child elements of the <RoomBundle> element:

Element Required Description
<RoomID> Required Specifies the unique ID for the room data. Use this ID to match the Room Bundle data with what was sent in the <PropertyDataSet> blocks in your property updates. For more information, see Defining Room and Package Metadata and the child elements of <RoomData> and <PackageData> Elements. (You can also use this ID to reference a common room definition in a single Transaction message when defining room data inline.)
<PackageID> Required Specifies the unique ID for the package data. Use this ID to match the Room Bundle data with what was sent in the <PropertyDataSet> blocks in your property updates. For more information, see Defining Room and Package Metadata and the child elements of <RoomData> and <PackageData> Elements. (You can also use this ID to reference a common Room Bundle definition used in a single Transaction message when defining Room Bundle data inline.)
<Occupancy> Optional, Strongly Encouraged Defines the maximum number of guests that a Room Bundle is intended for. For example, a large suite might be able to physically accommodate six guests, but the "Honeymoon Package" is intended for two guests only.

This value must be less than or equal to the Room Data's <Capacity> element, which is the number of people that the room can physically accommodate.

When setting the occupancy in a Points of Sale file, use the NUM-ADULTS attribute, as described in Building Dynamic POS URLs. The default value is "2".

The value of <Occupancy> must be a positive integer between 1 and 20, inclusive.

<RatePlanID> Required Can be used to specify a value in this field that will then be used by the Points of Sale file to construct a custom URL for a point of sale. For more information, see Overview of Points of Sale.
<Baserate> Required Defines the price of the room for the stay. The value of this tag should reflect the following:
  • For the price, set the least expensive double-occupancy rate that you offer.
  • The room must be private; shared rooms are not considered at this time.
  • The total length of a stay, not the average nightly rate.

When the room is unavailable for the itinerary, set the value of the <Baserate> element to -1 to indicate that a room is no longer in inventory. To remove a Room Bundle, use the instructions in Updating Room Bundles.

The Baserate element takes the following optional attributes:

  • all_inclusive: A Boolean that indicates if this rate includes taxes and fees. In general, set this value to false for US and Canadian end-users and supply values for the <Tax> and <OtherFees> elements. If you use all-inclusive prices, you may not be eligible to appear in the listings if your prices do not separate out taxes and fees for US and Canadian users.

    For all other end-users, you typically include the taxes and fees in the base rate and set the value of the all_inclusive attribute to true. For more information, see Taxes and Fees Policy.

    The default value is false.

  • currency: The 3-digit currency code. For example, USD for US dollars.
<Tax> Required Defines the taxes that are calculated for the final price of a room. The <Tax> element takes a single required attribute, currency, that defines the three-digit currency code for the taxes. For example, USD.
<OtherFees> Required Defines fees other than the base rate and taxes that influence the final price of a room. The <OtherFees> element takes a single required attribute, currency, that defines the three-digit currency code for the fees. For example, USD.
<Custom[1-5]> Optional Defines a custom field that you can use to pass additional data associated with a hotel. You can pass up to five custom values with the following element names:
  • <Custom1>
  • <Custom2>
  • <Custom3>
  • <Custom4>
  • <Custom5>

    The <Custom> elements let you pass arbitrary data. For example, you can specify a value in this field that will then be used by the Points of Sale file to construct a custom URL for a point of sale. For more information, see Points of Sale Files.

Room Bundle Syntax

You define Room Bundles in Transaction messages. The structure of the Transaction message depends on what you are doing: defining the metadata about the Room Bundle or updating the Room Bundle's pricing/availability.

To define Room Bundle metadata: Use a <PackageData> element inside a <PropertyDataSet> element to define metadata about the Room Bundle. For more information, see Defining Room and Package Metadata.

To define Room Bundle pricing and availability: Use a <RoomBundle> element inside the <Result> element of a Transaction message for each package/itinerary combination.

You must define at least one Room Bundle that matches your base room rate. You can then define additional Room Bundles within the same <Result> block for other room types at that property or different packages of services.

The following shows the syntax for defining Room Bundles:

View syntax

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="transaction_timestamp" id="transaction_id">
 <Result>
   <Property>hotel_id</Property>
   <Checkin>check-in_date</Checkin>
   <Nights>number_of_nights</Nights>
   <Baserate currency="currency_code">price</Baserate>
   <Tax currency="currency_code">taxes</Tax>
   <OtherFees currency="currency_code">other_fees</OtherFees>
   <ChargeCurrency>charge_currency</ChargeCurrency>
   <Custom1>customer_value_1</Custom1>
   <AllowablePointsOfSale>
      <PointOfSale id="POS_id"/>
   </AllowablePointsOfSale>
   <RoomBundle>
      <!-- Required (in bold) -->
      <!-- Reference room/package metadata (more efficient than inline) -->
      <RoomID>room_ID</roomID>
      <PackageID>package_ID</packageID>

      <Occupancy>intended_number_of_occupants_for_package</Occupancy>      
      <RatePlanID>rate_plan_ID</RatePlanID>

      <!-- Required -->
      <Baserate currency="currency_code">price</Baserate>

      <!-- Required -->
      <Tax currency="currency_code">taxes</Tax>

      <!-- Required -->
      <OtherFees currency="currency_code">other_fees</OtherFees>

      <!-- Custom values are used as parameters you may need for the POS -->
      <Custom1>custom_value_1</Custom1>
      <Custom2>custom_value_2</Custom2>
      <Custom3>custom_value_3</Custom3>
      <Custom4>custom_value_4</Custom4>
      <Custom5>custom_value_5</Custom5>
  </RoomBundle>
  ...
 </Result>
 ...
</Transaction>

The following child elements of each <RoomBundle> element are required:

  • <RoomID>: Maps a room's description to a Room Bundle.
  • <PackageID>: Maps a package's description to a Room Bundle.
  • <Baserate>
  • <OtherFees>
  • <Tax>

Defining Room and Package Metadata

You define room and package metadata in a Transaction message that is separate from pricing updates. By defining this data ahead of time, your pricing updates do not need to include repetitive information such as descriptions, photo URLs, amenities, and other data about each and every room/package for each and every itinerary. Google stores the metadata for you and inserts it into your ads when they are displayed. You can update room and package metadata at any time with a new Transaction message.

To define room and package metadata, send a Transaction message with <PackageData> and/or <RoomData> elements defined in it. You set a package ID and a room ID on each block that you then reference in your <Results> blocks of pricing updates. If the room and package data changes (for example, if you add a new room type in a property), send a new Transaction message that contains the updated room and package data.

Google recommends that you define metadata during your Hotel Ads setup process. After pre-defining the metadata, you only need to reference the <RoomID> and <PackageID> values in your pricing updates rather than include all that information again. Google uses those IDs to match rooms and Room Bundles with the stored metadata. When you pre-define metadata, all room and package information is defined (and stored by Google) only once, removing the need to include them in your pricing updates and greatly reducing the overall size of your Transaction messages.

If metadata changes, then you send a new Transaction message with the updates. Google replaces the existing metadata about a room or package with the new data.

The following example shows a Transaction message that defines room and package metadata:

View example

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2015-04-24T20:44:56-04:00" id="TXNID">
  <!-- A transaction message with room types result. -->
  <PropertyDataSet>
    <Property>12345</Property>
    <RoomData>
      <RoomID>single</RoomID>
      <Name>
        <Text text="Single room" language="en"/>
        <Text text="Chambre simple" language="fr"/>
      </Name>
      <Description>
        <Text text="A single room" language="en"/>
        <Text text="Le chambre simple" language="fr"/>
      </Description>
      <PhotoURL>
        <Caption>
          <Text text="Living area" language="en"/>
          <Text text="Le chambre" language="fr"/>
        </Caption>
        <URL>http://www.foo.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
      <PhotoURL>
        <URL>http://www.foo.com/static/bar/image1235.jpg</URL>
      </PhotoURL>
      <Capacity>2</Capacity>
    </RoomData>
    <RoomData>
      <RoomID>double</RoomID>
      <Name>
        <Text text="Double room" language="en"/>
        <Text text="Chambre double" language="fr"/>
      </Name>
      <Occupancy>2</Occupancy>
    </RoomData>
    <PackageData>
      <PackageID>refundbreakfast</PackageID>
      <Name>
        <Text text="Refundable Room with Breakfast" language="en"/>
        <Text text="Chambre remboursable avec le petit déjeuner" language="fr"/>
      </Name>
      <Description>
        <Text text="Continental Breakfast" language="en"/>
        <Text text="Petit déjeuner continental" language="fr"/>
      </Description>
      <ChargeCurrency>hotel</ChargeCurrency>
      <Refundable available="1" refundable_until_days="3"/>
      <BreakfastIncluded>1</BreakfastIncluded>
    </PackageData>
    <PackageData>
      <PackageID>prepaid</PackageID>
      <Name>
        <Text text="Nonrefundable" language="en"/>
        <Text text="Non remboursable" language="fr"/>
      </Name>
      <Description>
        <Text text="Blah blah blad" language="en"/>
        <Text text="Le blah blah blad" language="fr"/>
      </Description>
      <Occupancy>2</Occupancy>
      <ChargeCurrency>web</ChargeCurrency>
      <Refundable available="0"/>
    </PackageData>
  </PropertyDataSet>
</Transaction>

Because prices for room/itinerary combinations change much more frequently than the room or package descriptions, defining metadata is a much more efficient use of Transaction messages. In addition, errors such as mismatching room descriptions can be eliminated by using metadata rather than defining data inline.

The <PackageData> and <RoomData> elements are child elements of the the <PropertyDataSet> element. For more information, see <PropertyDataSet> Element.

You update Room Bundle metadata with a response to Google's Query message. The Query message has the following format:


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

You respond to this type of Query message with a Transaction message that defines the room and package metadata for the specified hotels. For more information, see Query Messages.

Comparing Occupancy and Capacity

When defining Room Bundles, you must understand the difference between occupancy and capacity:

  • Occupancy is the number of guests that a Room Bundle is intended to apply to. For example, the "Honeymoon Package" has an occupancy of two. You set the value of a package's occupancy by using the <PackageData> or <RoomBundle> elements' <Occupancy> child element, as described in Overview of Transaction Messages.
  • Capacity is the maximum number of people that a room can physically accommodate. The capacity of a room is always equal to or higher than the occupancy. For example, the "Honeymoon Suite" in your hotel has a maximum capacity of six people, but you price a bundle for two guests. You set the value of a package's capacity by using the <RoomData> element's <Capacity> child element, as described in Overview of Transaction Messages.

When pricing a Room Bundle, you must give the price for the number of guests that the bundle is intended to be for (the value specified in the bundle's <Occupancy> element). If <Occupancy> is set to two, then the price in that package must be for two people. You cannot set <Occupancy> to four guests, and set the bundle's price for two guests.

Updating Prices

To change the price of a Room Bundle, set the new Baserate in the <Result> element. Room Bundles are different from hotel prices in the way that you update them. A hotel price is either positive (available for the given itinerary at the given price) or -1 (not available). To remove a room/itinerary combination from inventory, you set the Result's Baserate to -1. To remove a Room Bundle for a given room/itinerary, remove the <RoomBundle> element from the <Result> in the Transaction message.

Every time you update a room/itinerary's <Result> block in your Transaction messages, you must include a complete set of available Room Bundles for each <Result>. Hotel Ads replaces the existing set of Room Bundles with the new set. If you do not include any Room Bundles in the <Result>, then Hotel Ads removes all Room Bundles for that room/itinerary.

Room Bundle Example

The following example shows two Room Bundles for the given itinerary (2-night check-in starting on 6/7/15):

Example

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2015-04-24T20:44:56-04:00" id="42">
  <Result>
    <Property>1234</Property>
    <Checkin>2015-06-07</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">199.99</Baserate>
    <Tax currency="USD">25.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
    <AllowablePointsOfSale>
      <PointOfSale id="bookingsite1.com"/>
    </AllowablePointsOfSale>

    <!-- Base Rate Room Bundle -->
    <RoomBundle>
      <RoomID>single</RoomID>
      <!-- Price for 2 ("occupancy") -->         
      <Baserate currency="USD">199.99</Baserate>
      <Tax currency="USD">25.12</Tax>
      <OtherFees currency="USD">10.00</OtherFees>
    </RoomBundle>
    
    <!-- Premium Room Bundle -->
    <RoomBundle>
      <RoomID>single</RoomID>
      <PackageID>refundbreakfast</PackageID>
      <!-- Price for 2 ("occupancy") -->         
      <Baserate currency="USD">298.88</Baserate>
      <Tax currency="USD">42.12</Tax>
      <OtherFees currency="USD">10.00</OtherFees>
    </RoomBundle>
  </Result>
</Transaction>

This example references pre-defined room and package metadata (referenced by the <RoomID> and <PackageID>).

Note that when you add Room Bundles, you must include one that matches the basic room's Baserate.

For each <Result> element, the contained set of Room Bundles overwrites the existing set for that property/itinerary combination. If you do not define any Room Bundles in the <Result>, then all Room Bundles are removed and only the base room for that hotel/itinerary shows up in search results

Room Bundles Inline

If it is very difficult to send your room and package data separate from your pricing, Room Bundles does support the same child elements as the <PackageData> and <RoomData> elements. Defining metadata inline is discouraged because it greatly increases the size of Transaction messages and introduces more opportunities for errors.

For more information on those elements, see Overview of Transaction messages.

Be sure to use elements such as <Name> to make your Room Bundles more attractive to potential customers. In this case, define names and other descriptive information in metadata, and be sure it matches the hotel's landing page.

RoomBundle inline data syntax

View syntax

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="transaction_timestamp" id="transaction_id">
 <Result>
   <Property>hotel_id</Property>
   <Checkin>check-in_date</Checkin>
   <Nights>number_of_nights</Nights>
   <Baserate currency="currency_code">price</Baserate>
   <Tax currency="currency_code">taxes</Tax>
   <OtherFees currency="currency_code">other_fees</OtherFees>
   <ChargeCurrency>charge_currency</ChargeCurrency>
   <Custom1>customer_value_1</Custom1>
   <AllowablePointsOfSale>
      <PointOfSale id="POS_id"/>
   </AllowablePointsOfSale>
   <RoomBundle>
      <!-- Define data inline (less efficient) -->
      <RoomData>
        <Name>
           <!-- One for each supported language -->
           <Text text="room_name" language="language_code"/>
        </Name>
        <Description>
           <!-- One for each supported language -->
           <Text text="room_description" language="language_code"/>
        </Description>
        <PhotoURL>
          <Caption>
           <!-- One for each supported language -->
            <Text text="photo_caption" language="language_code"/>
          </Caption>
          <URL>image_location</URL>
        </PhotoURL>
        <Capacity>maximum_capacity_for_room</Capacity>
      </RoomData>
      <PackageData>
        <Name>
           <!-- One for each supported language -->
           <Text text="room_name" language="language_code"/>
        </Name>
        <Description>
           <!-- One for each supported language -->
           <Text text="room_description" language="language_code"/>
        </Description>
        <Occupancy>occupancy_limit</Occupancy>
        <ChargeCurrency>charge_currency</ChargeCurrency>
        <Refundable available="refund_avail" 
              refundable_until_days="refund_days"
              refundable_until_time="refund_time"/>
        <BreakfastIncluded>breakfast_included</BreakfastIncluded>
        <ParkingIncluded>parking_included</ParkingIncluded>
        <InternetIncluded>internet_included</InternetIncluded>
      </PackageData>
      <RatePlanID>rate_plan_id</RatePlanID>
      
      <!-- Required -->
      <Baserate currency="currency_code">price</Baserate>

      <!-- Required -->
      <Tax currency="currency_code">taxes</Tax>

      <!-- Required -->
      <OtherFees currency="currency_code">other_fees</OtherFees>

      <Custom1>custom_value_1</Custom1>
      <AllowablePointsOfSale>
        <PointOfSale id="POS_id"/>
      </AllowablePointsOfSale>
  </RoomBundle>
  ...
 </Result>
 ...
</Transaction>

The following example shows the same Room Bundles with the room and package data defined inline:

Example

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2014-04-24T20:44:56-04:00" id="42">
  <Result>
    <Property>1234</Property>
    <Checkin>2015-06-07</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">199.99</Baserate>
    <Tax currency="USD">25.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
    <AllowablePointsOfSale>
      <PointOfSale id="bookingsite1.com"/>
    </AllowablePointsOfSale>

    <!-- Base Rate Room Bundle -->
    <RoomBundle>
      <RoomData>
        <Name>
          <Text text="Single Queen Room - Non-Smoking" language="en"/>
          <Text text="Chambre de la Roi Premium - Pas de Fumeurs" language="fr"/>
        </Name>
        <!-- Room can accommodate 4, but bundle is for 2 -->         
        <Capacity>4</Capacity>
      </RoomData>
      <PackageData>
        <Occupancy>2</Occupancy>
        <ChargeCurrency>web</ChargeCurrency>
        <Refundable available="1" refundable_until_days="7"
             refundable_until_time="18:00:00"/>
        <ParkingIncluded>1</ParkingIncluded>
        <InternetIncluded>1</InternetIncluded>
      </PackageData>
      <!-- Price for 2 ("occupancy") -->         
      <Baserate currency="USD">199.99</Baserate>
      <Tax currency="USD">25.12</Tax>
      <OtherFees currency="USD">10.00</OtherFees>
    </RoomBundle>
    

    <!-- Premium Room Bundle -->
    <RoomBundle>
      <RoomData>
        <Name>
          <Text text="Premium King Room - Non-Smoking" language="en"/>
          <Text text="Chambre de le Roi Premium - Pas de Fumeurs" language="fr"/>
        </Name>
        <!-- Room can accommodate 4, but bundle is for 2 -->         
        <Capacity>4</Capacity>
      </RoomData>
      <PackageData>
        <Occupancy>2</Occupancy>
        <ChargeCurrency>web</ChargeCurrency>
        <Refundable available="1" refundable_until_days="1"
             refundable_until_time="18:00:00"/>
        <BreakfastIncluded>1</BreakfastIncluded>
        <ParkingIncluded>1</ParkingIncluded>
        <InternetIncluded>1</InternetIncluded>
      </PackageData>
      <!-- Price for 2 ("occupancy") -->         
      <Baserate currency="USD">298.88</Baserate>
      <Tax currency="USD">42.12</Tax>
      <OtherFees currency="USD">10.00</OtherFees>
    </RoomBundle>
  </Result>
</Transaction>

Elements such as <RoomData> and <PackageData> include information that is often common across many Room Bundles. Rather than include the same information in each Room Bundle, you can define the values of these elements once, and then reference the definitions with a room ID or package ID. For more information, see Defining Room and Package Metadata.

Was this article helpful?
How can we improve it?