Retrieves room data for a specific hotel that accommodates the provided guest count and any other criteria.

This request can be constructed to provide data for room selection or other pre-booking shopping areas, or to verify price data prior to submitting a booking.

Method 2 is required prior to placing a reservation - it confirms the most current pricing and availability data needed for a successful booking.

Method 2: Verify Selected Room for Checkout

Use this option only after the customer has selected a specific room to book.

This request configuration will retrieve the most current price data for the customer's selected room to help reduce the chance of a booking failure due to a price mismatch or sold out error.

Method 1: Return Availability and Pricing for All Rooms

Use this method for room selection pages or other shopping areas where information on multiple rooms within a property is required.


In addition to the required base elements, you may also send the indicated optional elements to request room-level images or tailor the type of hotel information included in the response.

Request Parameters
Name Required
apiExperience
hotelId
arrivalDate
departureDate
RoomGroup
includeRoomImages
includeHotelFeeBreakdown
options
Request Parameters
Name Required
apiExperience
hotelId
arrivalDate
departureDate
RoomGroup
rateCode
roomTypeCode
includeDetails
includeHotelFeeBreakdown
Request Formats
XML/REST URL: GET http://api.ean.com/ean-services/rs/hotel/v3/avail?
XML Parent Element: <HotelRoomAvailabilityRequest>
Unique Protocol Requirements
REST: Room and guest counts are formatted differently than XML. Review the REST room format section on the hotel list page.

Please note: required parameters for this service are now broken down by the two service methods provided above.

Request Parameters

Base Parameters
Name Value Required for Method Description
apiExperience string 1&2 Use this attribute to identify the origin of your request. Choose an applicable value from the set provided below for each request you send.

Values:
PARTNER_CALL_CENTER - request from an agent in your call center
PARTNER_WEBSITE - request from a customer-facing website
PARTNER_MOBILE_WEB - request from a mobile-formatted website
PARTNER_MOBILE_APP - request from a mobile app
PARTNER_BOT_CACHE - request from a cache bot
PARTNER_BOT_REPORTING - request from a reporting bot

hotelId long 1&2 ID of the property to query for room availability
arrivalDate string 1&2

Check-in date, in MM/DD/YYYY format.

Include today's date to request same-day availability. Bookings may be made up to 11:59PM local hotel time (9:59PM for PST and Pacific islands).

departureDate string   1&2 Check-out date, in MM/DD/YYYY format.

Availability can be searched up to 500 days in advance of this date.

Total length of stay cannot be greater than 28 nights.
RoomGroup object 1&2 Container for the Room arrays that define guest and room count. If you used REST in your list request, remember to continue to follow the unique REST format.
RoomGroup.Room array 1&2 The number of Room nodes defines the number of rooms requested. Each node has its own adult/child guest count.

Properties allow up to 8 rooms per booking.
Room.numberOfAdults int 1&2 Adult guest count for the room.

Properties typically accommodate no more than 4 guests before incurring extra person fees.

To avoid "no results" errors, always limit occupancy to the highest maxRoomOccupancy returned in the hotel list response for the property.

Do not offer more than 8 guests per room, as results will not return above this guest count for most markets.

Room.numberOfChildren int 1&2 if child count > 0 Child guest count for the room. Required for all properties when children. Used in combination with childAges to determine availability and rates.
Room.childAges comma-separated
list of int
1&2 if child count > 0 Send the individual ages of the children in the room as a comma-separated list.

Some hotels define children vs. adults differently, so always require this info from customers when child guests are specified. E.g. a child of age 17 may be considered an adult by a property and incur an extra person charge if a room is already at capacity with previously defined adult guests.
roomTypeCode string 2 only Used only if the customer's specific room choice is already known. This will return the cancellation policy, bed types, and smoking preferences for the room.

Send together with rateCode
rateCode string 2 only Used only if the customer's specific room choice is already known. This will return the cancellation policy, bed types, and smoking preferences for the room.

Send together with roomTypeCode
includeDetails boolean 2 only Used for method 2 after the customer has selected a room.

Send as true to return booking-ready rate data for the provided room and rate codes.

Send together with roomTypeCode and rateCode
includeRoomImages boolean no Retrieves room-level images for the specified hotelId.

Also available as a standalone request.
includeHotelFeeBreakdown boolean no Returns a more detailed response structure for the HotelFees array that includes how often each fee applies and how it is applied. Available with minorRev=24 and higher.
options string or comma-separated
list of string
no Use this parameter in place of a separate hotel information request when using method 1 to populate room options for a property.

Send a single value, or combination of values as comma-separated list.

Values:
HOTEL_DETAILS Retrieve only the hotel details (property description)
ROOM_TYPES Retrieve room types
ROOM_AMENITIES Retrieve room amenities list (kitchenette, TV, etc)
PROPERTY_AMENITIES Retrieve property amenities list (spa, gym, conference rooms)
HOTEL_IMAGES Retrieve only the hotel image URLs (not room images)
numberOfBedRooms int no This parameter is valid for condos/vacation rentals only. Specifies the number of bedrooms requested - 4 maximum.
supplierType string no Supply the same value returned in the previous hotel list response.

Values:
E: Expedia Collect
rateKey string no Key for the parameters that determined the rate provided in the prior hotel list response.
Hotel Room Response
Returns rooms at the specific hotel requested that will accommodate the specified guest count during the specified dates of stay, or confirms availability and pricing for the provided roomTypeCode and rateCode.

This response also returns check-in instructions, further property details, detailed rate information, and most importantly the rateKey required for booking.

If the options object was included in a Method 1 request, the details specified within the object will also be returned if available.

Response Content
Parent Element: HotelRoomAvailabilityResponse
Attribute: size - number of rooms returned

Name Value Description
hotelId long ID for the property. This same ID will be used in any subsequent reservation requests.
arrivalDate string Confirms the check-in date submitted in the request.
departureDate string Confirms the check-out date submitted in the request.
hotelName string Name of the hotel
hotelAddress string Hotel street address
hotelCity string Hotel city
hotelStateProvince string Two character code for the state/province containing the specified city. Returns only for US, CA, and AU country codes.

References:
US State Codes
Canadian Province/Territory Codes
Australian Province/Territory Codes
  • Australian Capital - AC
  • New South Wales - NW
  • Northern Territory - NO
  • Queensland - QL
  • South Australia - SA
  • Tasmania - TS
  • Victoria - VC
  • Western Australia - WT
hotelCountry string Two character ISO-3166 code for the country the hotel is located in.
numberOfRoomsRequested int Confirms the number of Room nodes sent in the request.
checkInInstructions string Must be displayed if returned by the property.
May include fees that can be incurred at check-in, instructions for after-hours check-in, etc
specialCheckInInstructions string Contains information critical for check-in, such as a requirement to notify the property of an expected arrival time. Display this information in the same area as the primary check-in instructions.
HotelRoomResponse array Each node contains rates and details for an individual room at the hotel. The JSON response format of this array may cause issues in Axis.
HotelRoomResponse.policy string Additional miscellaneous policies, e.g. photo ID required for check-in.
HotelRoomResponse.rateCode string Code to the displayed rate.
HotelRoomResponse.roomTypeCode string Room type code for the room.

If the options parameter was sent in the room availability request, this element will not return. The value is instead sent as the roomCode attribute of the RoomType object.
HotelRoomResponse.rateDescription string

Short description of both the room and the rate to be charged, e.g. Deluxe Room King - All Inclusive.

Recommended for primary display.

HotelRoomResponse.roomTypeDescription string Short description of the room type, e.g. Deluxe Room King.

If the options parameter was sent in the room availability request, this element will not return. The value is instead sent as the description element within the RoomType object.
HotelRoomResponse.supplierType string Supplier of the hotel. This same supplier will be used to process any reservations placed.

Values:
E: Expedia Collect
HotelRoomResponse.otherInformation string Other miscellaneous info on the hotel, if available.
HotelRoomResponse.propertyId string Expedia's ID for the hotel. Use this value to map to a hotelId when cross-referencing to Expedia.
HotelRoomResponse.smokingPreferences comma-separated list of string Available smoking preferences for the room, if any.

Values:
NS: non-smoking
S: smoking
E: either
HotelRoomResponse.minGuestAge int The minimum age of any guests in the room, e.g. 18 or 21 if children are not allowed.. Will return as 0 or not at all if there is no minimum age.
HotelRoomResponse.quotedOccupancy int Maximum number of guests the room can accommodate without incurring extra person fees.
HotelRoomResponse.rateOccupancyPerRoom int Maximum number of guests the room can accommodate, including guests who may incur extra person fees. Equivalent of maxRoomOccupancy in the list response.

If this value exceeds the value of quotedOccupancy, check for extra person fees in the Surcharges array and alert users accordingly.
string Deprecated. Do not use any values returned.
HotelRoomResponse.BedTypes array The bed type choices for the individual room. May return a single bed type or a choice to include at booking time. Review details for bed types
HotelRoomResponse.ValueAdds container for ValueAdd Contains an array of ValueAdd elements, if available, for the provided room and rate. Has a size attribute to indicate the number of value adds returned.
ValueAdds.ValueAdd array

Contains a description element for a free service offered with the provided room and rate, such as free breakfast or wireless internet.

Known value adds are detailed on the ValueAdds Array overview page.

HotelRoomResponse.RoomImages array Array of any available room-level image URLs, if requested via the includeRoomImages parameter.
HotelRoomResponse.RoomType object Returned when options parameter is sent with a value of ROOM_TYPES and/or ROOM_AMENITIES.

Attributes:
roomCode: replaces roomTypeCode element
roomTypeId
RoomType.description string Replaces roomTypeDescription element. Must display on individual room pages as well as any booking and booking confirmation pages.
RoomType.descriptionLong string More detailed room description, if available.
RoomType.roomAmenities array List of room amenities if available (same content and structure as listed in the hotel information response)
RoomType.HotelDetails object Hotel Description Content (same content and structure as listed in the hotel information response)
RoomType.PropertyAmenities object Hotel Amenities Information (same content and structure as listed in the hotel information response)
RoomType.HotelImages object Hotel Image Information (same content and structure as listed in the hotel information response)
HotelRoomResponse.RateInfos container for RateInfo Contains an array of RateInfo elements that provide detailed rate information for individual rooms.

If you are using an older integration running on minorRev=6 or earlier, RateInfo will return without the RateInfos container.
RateInfos.RateInfo object Contains all rate information for a single room within several different objects and individual values.

Attributes:
priceBreakdown boolean Indicates if a full price breakdown including taxes and total price to be charged is included.
promo boolean Indicates if the rate returned is a promotional rate.
rateChange boolean Indicates if the rate is different for at least one of the nights during the stay.
RateInfo.RoomGroup object Confirms the contents of the same RoomGroup object sent in the request as they apply to the rates provided. For minorRev=29 and higher, contains per-room nightly rate details.
RoomGroup.Room object Object's child elements confirm the specific numberOfAdults, numberOfChildren, and childAges used to calculate the rates provided
Room.rateKey object Key to the search parameters and other values determining the rate

Note that this value is almost always different from the value returned in the hotel availability response - always pass over the value from this response to the booking request.

Every time search parameters are changed (guest count change, different dates of stay, adding children, etc) a new request must be sent to obtain a new value for this parameter.

For minorRev=18 and below, this element will return in the main body of the response.
Room.ChargeableNightlyRates array Container for NightlyRate array for the room. Rates returned are specific to the individual room and return in sequential order across the duration of the stay.

For an average per-night cost across multiple rooms, use the values provided by nightlyRatesPerRoom.

Returns for minorRev=29 and higher.
ChargeableNightlyRates.NightlyRate object Provides the rate for a single night within the span of the requested stay. When returned within this location, rates are always specific to the containing Room.

Indicates the presence of a promo rate, the base rate, and the rate after the promo is applied (if applicable). Contains attributes only.

Returns for minorRev=29 and higher.

Attributes:
promo boolean Indicates if a promo rate is applied for this night's rate.
rate float The nightly rate after the promo, if any, is applied.
baseRate float The nightly rate before the promo, if any, is applied.
ChargeableNightlyRates.NightlyRate object

Rate information converted to the customer's requested currency. Returned only if the requested currency is non-billable by the hotel or within the customer's market region. Contains the same attributes as ChargeableNightyRates. Returns for minorRev=29 and higher.

ChargeableNightlyRates.
ConvertedNightlyRates
object Rate information converted to the customer's requested currency. Returned only if the requested currency is non-billable by the hotel or within the customer's market region. Contains the same attributes as ChargeableNightyRates. Returns for minorRev=29 and higher.
RateInfo.promoId string ID for the promo offer returned, if any.
RateInfo.promoDescription string Description for the promo returned, if any. Max of 255 chars will return.
RateInfo.promoDetailText string Extra details for the promo returned, if any.
RateInfo.nonRefundable boolean Indicates if the booking is nonrefundable. Must display if returned - all charges are final after a successful booking. This value always takes precedence over any differing policy data.
RateInfo.depositRequired boolean Always returns as true for Expedia Collect.
RateInfo.rateType string Indicates if the rate returned is prepaid via EAN or post-paid at the hotel. Either returns with a value of MerchantStandard for prepaid availability, or does not return at all for post-paid.
RateInfo.currentAllotment int The number of bookable rooms remaining at the property. Use this value to create rules for urgency messaging to alert users to low availability on busy travel dates or at popular properties.

If the value returns as 0, it does not indicate a lack of rooms at the property. The rules needed to calculate the value were simply not met - this value does not indicate absolute availability.
RateInfo.cancellationPolicy string Hotel's cancellation policy for this room. Must display on individual room pages as well as any booking and booking confirmation pages.
RateInfo.CancelPolicyInfoList container for Cancel
PolicyInfo
Details specifics of the cancellation policy, typically the times determining the penalty period and the penalties incurred for cancellation.
Review details for the CancelPolicyInfo array
RateInfo.ChargeableRateInfo object This object's attributes contain the absolute total to be charged for the reservation as well as rate averages and totals. Nodes within the object provide details on individual nightly rates and surcharges.

Attributes:
total float The total of all nightly rates, taxes, and surcharges to be charged for the reservation. This is the total value that must be displayed to the customer and included in the booking request.
surchargeTotal float Total of TaxAndServiceFee and ExtraPersonFee from the Surcharges array. These fees are collected by Expedia upon booking.
nightlyRateTotal float Total of all values in the nightlyRatesPerRoom array contained within this object.
maxNightlyRate float Highest nightly rate of all rates returned
currencyCode string Currency code for the rates returned
commissionableUsdTotal float Do not use this attribute. This value is no longer maintained.
averageRate float Average of all nightly rates with any promo values applied, without surcharges.
averageBaseRate float Average of all nightly rates without any promo values applied, without surcharges. Will return the same as previous value if no promos present.
ChargeableRateInfo.
nightlyRatesPerRoom
array Container for NightlyRate array. Has size attribute to indicate number of nodes in the array, which will correspond to the number of nights in the request. Rates return in sequential order across the duration of the stay.
nightlyRatesPerRoom.NightlyRate n/a

Provides the rate for a single night within the span of the requested stay.

Indicates the presence of a promo rate, the base rate, and the rate after the promo is applied (if applicable). Contains attributes only.

For multi-room requests, this value is the average of the per-night cost across all rooms. EAN recommends using the new per-room ChargeableNightlyRates array for multi-room price display.

For multi-room requests under minorRev=28 and below, this element provides rates for the first room only, instead of an average rate.



Attributes:
promo boolean Indicates if a promo rate is applied for this night's rate.
rate float The nightly rate after the promo, if any, is applied.
baseRate float The nightly rate before the promo, if any, is applied.
RateInfo.promoType string Indicates whether any promos returned are mobile-specific or standard promotions. Returns Mobile for mobile promotions and Standard for all others.
In order to return mobile promotions, you must identify your mobile site or app via the proper customerUserAgent string.
ChargeableRateInfo.Surcharges array

Container for Surcharge array. Details the individual charges that contribute to TaxAndServiceFee and surchargeTotal.

All taxes and fees contained with in this array are charged and collected by Expedia upon booking.

Contains size attribute to indicate number of nodes in the array.

Surcharges.Surcharge n/a

Details a single surcharge's amount and type. Contains attributes only.

TaxAndServiceFee and ExtraPersonFee contribute toward the surchargeTotal. All other values are individual components of the TaxAndServiceFee value:

Attributes:

amount float Amount of the specific surcharge
type string

Name of the surcharge.
Possible values:

Components of surchargeTotal:

  • TaxAndServiceFee
  • ExtraPersonFee

Components of TaxAndServiceFee:

  • Tax
  • ServiceFee
  • SalesTax
  • HotelOccupancyTax
  • PropertyFee

Important Display Rules:

• The SalesTax and HotelOccupancyTax surcharge types must be displayed by state law in New York. Ensure you expect and capture these values to display as "Hotel Occupancy and Sales Tax" in the final price breakdown.

• The PropertyFee surcharge type must be displayed beginning on the initial hotel room selection page, immediately after your hotel search results page. This placement is required by the U.S. Federal Trade Commission (FTC).

Display this surcharge as "Property Fee" on your room selection page, as described above, and in all subsequent price breakdowns for the following Points of Sale:

  • US
  • Canada
  • Brazil
  • LATAM
RateInfo.HotelFees array

Any taxes or fees detailed within this array are charged and collected by the hotel upon check-in or check-out.

These fees are not charged or collected by Expedia – they are completely separate from those detailed in the Surcharges array.

When populated, use this element to meet the rate/tax/fee display format required by major search engines and aggregators.

Contains size attribute to indicate the number of charges contained.

HotelFees.HotelFee none

Contains attributes for the description, amount, and currency of a single fee.

Details the total of any VAT, state/city tax, resort fees, or any other fees collected that cannot be reasonably avoided.

Example: A $10 per-night charge for a 4-night stay will be represented by a value of 40.00

Charges return in the bookable currency indicated by the currencyCode attribute of ChargeableRateInfo.

Attributes:

description string The type of charge. Possible values:
  • MandatoryFee
  • MandatoryTax
  • ResortFee
amount float Value for the charge.
HotelFee.HotelFeeBreakdown none Returns if includeHotelFeeBreakdown was sent in the request. Details how the fee is applied and how often it applies.

Attributes:
unit string How the fee is distributed. Possible values:
  • Per Person
  • Per Room
  • Per acommodation
  • Per house
  • Per apartment
  • Per adult
frequency string Frequency of the fee. Possible values:
  • Per Night
  • Per Day
  • Per Stay
  • Per week

Available with minorRev=24 or higher.

RateInfo.ConvertedRateInfo object Rate information converted to the customer's requested currency. Returned only if the chargeable and converted currencies are different, i.e. if the hotel cannot accept the customer's requested currency. Contains the same attributes as ChargeableRateInfo.