Hotel Rate and Rule Search

A Hotel Rate and Rule Search, also known as Complete Hotel Availability, returns room rates and rate rules for bookings for a specified hotel property.

This search is typically performed based on a specific property selected from the results of a Hotel Search, which returns available hotel properties for the requested parameters. However, if the chain and Property ID are already known, a Hotel Rate and Rule Search can be requested without any pre-requisite transactions.

A Hotel Rate and Rule Search is a pre-requisite for selling a hotel segment in a Hotel Booking, unless a direct hotel sell is made. Direct sells require the Property ID, room rates, and other necessary data to be entered directly into the sell segment transaction.

Note: Hotel Rate and Rule Search is performed only for a single property. Requesting rate/room information for multiple properties results in an error.

Schema

Located in Hotel.xsd:

Request

Use HotelDetailsReq to request Hotel Rate and Rule Searches.

Enter the minimum required data:
- The vendor's two-character chain code in HotelChain.
- The unique Property ID for this hotel property in HotelCode.
- In the HotelDetailsModifiers element, the value of the RateRuleDetail attribute must be set to 'Complete'. If this attribute is set to another value, the response will not return complete details.
  More information
  Note that HotelDetailsReq returns different functionality depending on the enumeration set for HotelDetailsModifiers @RateRuleDetail.
  
  If @RateRuleDetail=“Complete”, a full Hotel Rate and Rule Search response is returned with availability, rates, and descriptive data.
  
  If @RateRuleDetail=“None” or is empty, a Hotel Description response is returned with only descriptive information, and no availability or rate information.
  
  If @RateRuleDetail=“RatePlansOnly”, an abridged Hotel Rate and Rule Search for Rate Plans Only response is returned with only availability and rates, but no descriptive data.
- Check-in and check-out dates found in the HotelStay child element of HotelDetailsModifiers.
  
  Whenever possible, check-in and check-out dates should be included in a Hotel Rate and Rule Search request to account for variations in rates, such as:
  - Rates that change during the stay.
  - Seasonal changes in rates.
  - Rates that are based on a certain length of stay.
The following information in the HotelDetailsModifiers is not required but is recommended.
- The number of travelers in the booking in @NumberOfAdults or @NumberOfOccupants. If no number is input, the default number of travelers is one Adult. Additional child travelers can be indicated using NumberOfChildren.
- Rate code: This is imperative to ensure the appropriate discounts (e.g. corporate) associated with a Rate Code are retained where applicable, and the proper rules are returned for the rate specified.
- A NextResultReference may be returned in the response if more rates are available. It can be submitted in a subsequent HotelDetailsReq to retrieve the additional rates.
Additional modifiers can be added to a Hotel Rate and Rule Search request to narrow the search results.

Response

HotelDetailsRsp in the Hotel Service returns response data.

A NextResultReference indicates more data is available and a subsequent Hotel Rate and Rules Search can be sent with the value returned in NextResultReference.

A RequestedHotelDetails element is returned, which corresponds to the requested hotel property. It contains general information about the hotel property, rate data, photos and media URLs, and comments and guest reviews.

HotelType @SourceLink specifies the supplier's participation level.
More information
Source Link indicates the supplier's participation level in the Hotel transaction in a specific response.

If a direct link between the provider and the supplier is temporarily disabled, cached data is returned from the provider's cached database. However, the Participation Level indicator (HotelProperty @ParticipationLevel) continues to indicate the default link connection, and does not change if the direct link is temporarily disabled.

Source Link allows customers to identify if content returned in an individual response is coming directly from the supplier or as cached data from the provider's database. Source Link implementation and Participation Levels vary by provider.
- The Travelport Universal API providers support different levels of participation for data sources. For Galileo (1G) and Apollo (1V) providers, participation levels include:
  - Inside Availability which links directly from the supplier’s system.
  - Link Partner connection, which returns cached rates from Travelport’s RoomMaster system but confirms them through a direct link with the supplier. Participating RoomMaster suppliers regularly upload hotel rates and information to RoomMaster.
  - RoomMaster Only, which returns cached data from RoomMaster.
  If a direct link between the provider and the supplier is temporarily disabled, Galileo and Apollo return data from RoomMaster. However, the Participation Level indicator (HotelProperty @ParticipationLevel) continues to indicate the default link connection, and does not change if the direct link is temporarily disabled.
  
  The Boolean SourceLink attribute for Hotel Description and Hotel Rules responses to indicate if the description or rules data is returned directly from the hotel supplier’s system.
  - If HotelType SourceLink="true", response is received as Inside Availability directly from the hotel supplier.
  - If HotelType SourceLink="false", cached data from RoomMaster is received in the response.
- This capability allows customers to identify content returned in the response as being from either the Hotel Supplier (via Inside Availability links with the Supplier) or from Room Master.
- The Source Link indicator is not returned for Hotel responses other than Hotel Description and Hotel Rules, such as Hotel Search, Hotel Rate and Rule Search, and Hotel Booking responses.
HotelProperty identifies the requested hotel.
More information
The response for details or rules may return the following applicable information. Note that the type and amount of data returned may vary by the provider or hotel supplier.
- Hotel property information, such as chain, hotel code (unique Property ID), associated city/airport, and hotel name.
- The property's address and phone number.
- The geographical coordinates (latitude and longitude) of the property.
- The distance and direction.
- The reservation requirements for the hotel.
- Free-text marketing messages for a property /MarketingMessage/Text. The presence or type of marketing messages varies by provider, supplier, and property.
  In earlier releases, marketing messages from the supplier were returned only as free text in HotelDetailItem @Text.
If NextResultsReference is returned, MoreRates="true" is returned in HotelProperty.
HotelDetailItem returns general information about the hotel property and is sent by the provider as free text.
More information
This information is not associated to a specific rate Plan (Booking Code), but rather to the hotel property in general. The amount and type of additional information varies by the provider and hotel supplier, but typically includes information such as:

Check-in and check-out times.

Check-in and check-out times are returned by property in /HotelDetailItem Name="CheckInTime" and Name="CheckOutTime". Because data is forwarded as text data from the supplier, the time formats may vary by supplier and property in the corresponding Text element.

Check-in and check-out times are returned from Galileo, Apollo, and Worldspan.
- Cancellation policies.
- A description of the hotel property.
- Directions to the hotel property.
- Location information, such as whether the hotel is in a historic district, near shopping, or near sports venues.
- Promotional messages.
- Accepted credit cards.
- Description of tax information.
- Property information, such as:
  - The total room count for the property.
  - The number of suites and floors at the property.
  - Conference room capacity.
  - The year the property was built.
  - The year the property was remodeled, if applicable.
- The rating for the property.
- Worldspan may return Name="Meal Plan Indicator", which indicates that the hotel may offer meal plans.
- For Galileo and Apollo, some property information may be provided in a Miscellaneous node. For Worldspan , the Miscellaneous node is parsed and information is returned in separate, identifiable nodes.
  Show more information
  Previously, Worldspan were returning duplicate property description data for Hotel Rate and Rules responses. This data varies by supplier, but typically includes data such as policy and cancellation details, facilities and services information, and marketing campaigns and incentives.
  In HotelRateDetail/RoomRateDescription Name="Miscellaneous", the property descriptions were returned as free text. The same text data was also parsed as defined data:
  In Hotel Rate and Rules (HotelDetailsRsp), discrete data is returned in HotelDetailItem. For example:
  <HotelDetailItem Name="TRANSPORTATION (11)">
  <Text>-PORT COLUMBUS INTL AIRPORT DIRECTIONS- FOLLOW I-670 SOUTH TO EXIT 4 ON THE LEFT. TURN RIGHT AT THE FIRST TRAFFIC LIGHT ONTO CHESTNUT STREET. OUR HOTEL WILL BE ON YOUR RIGHT. </Text>
  This update removes the duplicate Name="Miscellaneous" free-text data in HotelRateDetail/RoomRateDescription, and only returns the parsed versions of the data in HotelDetailItem.
  In addition, hard-coded keywords were removed from the 1P interface with Universal API. Previously, this hard coding resulted in the return of only a limited set of keyword-defined property description data. With this enhancement, all available property description data is returned.

HotelRateDetail provides rate data for the requested stay. Each instance of the element corresponds to a unique Rate Plan (Booking Code). Each rate plan includes information such as cost, taxes, and cancellation information.

More information

@RatePlanType (Booking Code) identifies a specific room type/rate combination.
The price of the room, including:
- The base rate for the total length of stay, which is the price of the room without any additional taxes, fees, or surcharges.
- Any taxes, fees, or additional surcharges for the booking.
- The total price, which combines the base rate and taxes.
- Approximate values and alternate currency
  - If a preferred currency is specified in the request, alternate currency amounts are returned in either @ApproximateTotal or @ApproximateBase. If a preferred currency is not requested, values are returned in @Total and @Base, and approximate values are not returned.
  - Alternate currency amounts from Worldspan are returned in HotelRateByDate @ApproximateBase and/or @Approximate Total. Approximate values are also returned even if a preferred currency is not specified. Values for Worldspan are not returned in @Total and @Base.
    In addition, the /RoomRateDescription ExtraOptions are returned in the requested currency.
  Three approximate values support responses that have a discrepancy between the requested currency and the provider’s default currency:
  - ApproximateBase, which returns the approximate base room rate, excluding taxes or fees. Base values are returned for Rate by Date hotel responses.
  - ApproximateTotal, which returns the approximate total room rate, including taxes and fees.
  - ApproximateTax, which returns approximate taxes associated with the room rate and hotel stay.

Note: The Base Rate and Totals for room rates, returned in HotelRateDetail are not calculated by Universal API because they cannot be guaranteed to be accurate.

HotelRateDetail/RoomRateDescription includes free text descriptions about the Rate Plan. The amount and type of additional information varies by data source and hotel vendor.

Information that can be returned in RoomRateDescription includes:
- Descriptions of the room's view, such as beach front, mountain view, and courtyard view.
- Minimum and maximum lengths of stay
- Guaranteed hold time or guarantee for late arrival.
- Deposit or pre-payment required.
- Meals included in the rate: breakfast, lunch, and dinner. Meal information may also be supplied by a provider using the MealPlans element.
- A commission indicator if the rate include a commission fee.
- Extra fees for additional child or adult travelers.
- Extra fees for additional beds, cribs, or rollaway cots.
- Smoking or non-smoking room.
  - @Name ="SmokingRoomIndicator"
  - @Text: "N" = NonSmoking, "Y" = Smoking, Blank = null
- Range of floors for the associated Rate Plan.
- A Commission indicator and discrete commission data when available. Commissions are usually a percentage of the base stay rate (not including tax or surcharges).
  
  More information
  
  The "Commission" value is available in typeHotelRateDescription @Name, which displays in the response in RequestedHotelDetails/HotelRateDetail/RoomRateDescription/.
  
  In the corresponding Text element, the first text row indicates the presence ("yes") or absence ("no") of a commission for the hotel rate. If the value of the first row is "yes", and a commission value is available, the second text row indicates the percentage of the commission ("nn%"). Commission data is returned only if supported by the supplier and provider. Some responses may return a Commission indicator but not include a percentage value.
  
  For Galileo and Apollo, Commission indicators and percentages are returned as discrete data only for suppliers that have a direct connection to Galileo and Apollo. If cached (RoomMaster®) data is used, the Commission indicator is returned. However, Commission percentages from RoomMaster are not returned as discrete data, but may still be included Room Rate Description text string.

Update

As of 09 February 2017, @Name values for rate and room descriptions were modified. This update applies to Galileo, Apollo, and Worldspan.

Important! Even though there is no schema change associated to these values, client applications must be modified to support the change in RoomRateDescription @Name values.

Hotel.xsd

The rate name and room description are divided into separate values of Name="Room" and Name="Rate". Text is returned in sentence case or title case. For example:

<RoomRateDescription Name="Room">

<Text>1 Queen Bed-nonsmoking</Text>

<Text>Hi Speed 9.95 Day-sweet Dreams Experience Bed</Text>

</RoomRateDescription>

<RoomRateDescription Name="Rate">

<Text>Best Available Rate</Text>

</RoomRateDescription>

Note: If text cannot be parsed, room and rate information is returned in the original format.

See examples in XML Samples for Rate Plan and Room Description in Hotel.xsd.

GuaranteeInfo provides guarantee, deposit, and prepayment data if it is returned by the hotel supplier. Previously, this data was returned only as free text in RoomRateDescription.

More information

A GuaranteeInfo child element is available in /RequestedHotelDetails/HotelRateDetail/ .

All Guarantee attributes are optional, and are only populated if the hotel supplier returns data. If the hotel supplier does not return discrete guarantee, deposit and prepayment information, free text data will continue to be returned in the RoomRateDescription used in previous schema versions. Data is returned in RoomRateDescription @Name="Guarantee", "Deposit", and "Prepayment" and @Text.

It is recommended that the user should always consume all hotel populated values that apply to hotel room rates, payment, policy, guarantee, deposit, pre-payment, cancel penalty and other hotel rate descriptions. Cancellation, nonrefundable and penalty information, when provided by the hotel supplier will be found under HotelDetailItem/ @Name, @Text, RoomRateDescription/ @Name, @Text or CancelInfo/ and attributes separately. The Guarantee, deposit and prepayment information are provided by the hotel supplier, not the provider.

This is supported by Galileo (1G), Apollo (1V), Worldspan (1P).

HotelRatebyDate provides rate data for each day of the stay.

More information

The base rate for the total length of stay, which is the price of the room without any additional taxes, fees, or surcharges.

Note: The Base Rate and Totals for room rates, returned in HotelRateByDate, are not calculated by Universal API because they cannot be guaranteed to be accurate.

Any taxes, fees, or additional surcharges for the booking.

The total price, which combines the base rate and taxes.

Approximate Base and Total, which display the rate in the preferred currency, for instances when the exact value is not available from the supplier or when the conversion rate is not yet determined.

If no preferred currency is requested, the supplier’s currency is returned as the default in /HotelRateDetail/HotelRateByDate @Base and/or @ Total.

If a preferred currency is requested, that currency is returned in /HotelRateDetail/HotelRateByDate @ApproximateBase and/or @ApproximateTotal.

RateMatchIndicator indicates if the room and price were validated for specific modifiers in the request such as rate category, room count, number of child or adult guests, and bed types. The indicator confirms whether the requested parameters or substitute parameters are available in the response.

CancelInfo returns cancellation information.

CancelInfo

Sometimes a hotel supplier may provide an indicator for a hotel room rate that is non-refundable or that has additional cancellation information room plan type.

The CancelInfo element is used to return this cancellation information for Galileo and Apollo suppliers that participate in Complete Pricing Plus (CP2). The CancelInfo element attributes may be populated in both Hotel and Universal Record responses if data is provided by a hotel supplier.

@NonRefundableStayIndicator and @CancelDeadline are discrete data for Worldspan in Hotel Rate and Rule Search only. Previously, Worldspan returned free-text data in HotelDetailRsp/RequestedHotelDetails/HotelRateDetail/RoomRateDescription @Name @Text. When applicable, Worldspan continue to return free text in addition to the @CancelDeadline value:

RoomRateDescription Name="Cancel Policy Exist" Text="Please reference the Cancellation Policy in Hotel Rules"

Show Attributes

Attributes	Definition
@NonRefundableStayIndicator	Returned from hotel room rate. true = non-refundable false = refundable unknown = unknown or not provided by hotel.
@CancelDeadline	YYYY-MM-DDTHH:MM The date and time to cancel the hotel reservation without penalty. All dates and times are local to the hotel property. blank or not present = unknown or not provided by hotel
@TaxInclusive	Shows if the cancellation penalty includes taxes. True = yes False = no blank or not present = unknown or not provided by hotel.
@FeeInclusive	Shows if the cancellation penalty includes extra fees. True= yes False=no blank or not present= unknown or not provided by hotel.
@CancelPenaltyAmount	If provided, returns the ISO three-character currency code and value amount with decimal. For example, CAD100.00. blank or not present= unknown or not provided by hotel.
@NumberOfNights	The number of nights that are charged as the cancellation penalty. For example: 3. Integer: 0 – 99 blank or not present= unknown or not provided by hotel.
@CancelPenaltyPercent	Percentage of booking that will be charged as the cancellation penalty. For example: 100. Integer: 1 – 999 blank or not present = unknown or not provided by hotel.
@CancelPenaltyPercentAppliesTo	Explanation of the cancellation penalty percent. Text. 0-64 characters. blank or not present = unknown or not provided by hotel.
@OffsetTimeUnit, @OffsetUnitMultiplier, @OffsetDropTime	Indicate the deadline time associated with a cancellation. More Information The following attributes were added to CancelInfo to indicate the time period of the deadline either after booking or before arrival at the hotel stay. @OffsetTimeUnit: "Year”, “Month”, “Day”, or “Hour”. @OffsetUnitMultiplier: The number of units for the deadline. @OffsetDropTime: "AfterBooking" or "BeforeArrival". For example: <CancelInfo NonRefundableStayIndicator="true" OffsetTimeUnit=”Week” OffsetUnitMultiplier=”2” OffsetDropTime=”BeforeArrival”/> Cancellation is non-refundable after two weeks before arrival at the hotel stay. Offset time is returned only for Galileo (1G) and Apollo (1V). Offset time is not returned for Worldspan (1P).

Alternate Availabilities

If the requested hotel property is not available for the specified dates, the provider may return one or more alternate hotel properties that are available in HotelAlternateProperties. Availability of alternate properties depends on the provider and the supplier's participation level with the provider.

Next Steps

A Hotel Rules search is strongly recommended to return booking code rules associated with the selected rate. Some providers may return partial rules in a Rate and Rule Search response. However, Universal API supports all rules responses with the Hotel Rules call.