Hotel List

Retrieve a list of hotels by location or a list of specific hotelIds.

This method can be used to return hotels with available rooms for a provided date range, or to return a list of all active properties within the specified location without any availability information.

This method supports multiple filters and methods of specifying the desired location to allow a variety of front-end search options, such as searching by airport code or a visualization on a map.

Request Formats
XML/REST URL: GET http://api.ean.com/ean-services/rs/hotel/v3/list?
XML Parent Element: <HotelListRequest>

Unique Protocol Requirements
REST
Request Parameters
Every search for available hotels requires a minimum of a date range, room count and adult guest count, and a location or hotelId list.

To obtain a "dateless list," or a list of all active properties in a location without specific availability information, simply omit the arrivalDate, departureDate, and RoomGroup parameters from your request.

Base Parameters
Name Value Required Description
arrivalDate string yes for availability Check-in date, in MM/DD/YYYY format.
departureDate string yes for availability Check-out date, in MM/DD/YYYY format.

Availability for Expedia Collect properties can be searched up to 500 days in advance of this date.

Hotel Collect availability can be searched up to 320 days in advance of this date.

Total length of stay cannot be greater than 28 nights.
numberOfResults int no Maximum number of hotels to return. Acceptable value range is 1 to 200. Default: 20

Does not limit results for a dateless list request.
RoomGroup object yes for availability Container for the Room arrays that define guest and room count. For REST, please see the section below.
RoomGroup.Room array yes for availability The number of Room nodes defines the number of rooms requested. Each node has its own adult/child guest count.

Expedia Collect properties allow up to 8 rooms per booking, Hotel Collect/Hotel Collect properties allow up to 4.
Room.numberOfAdults int yes for availability Adult guest count for the room.

Expedia Collect properties typically accommodate no more than 4 guests before incurring extra person fees.

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

Hotel Collect guest counts over 2 people are forwarded as direct requests to the hotel, which are not guaranteed.
Room.numberOfChildren int yes if > 0 Child guest count for the room. Required for Expedia Collect properties. Used in combination with childAges to determine availability and rates.
Room.childAges comma-separated
list or array of int
yes if child count > 0 Send the individual ages of the children in the room as a comma-separated list for XML and REST and as an array of individual values for childAges for SOAP.

Always require this info from customers when child guests are specified. Unexpected extra person charges may result if children's ages are not provided prior to booking.
includeDetails boolean yes for two-step booking

Determines whether or not a rate key, cancellation policies, bed types, and smoking preferences should be returned with each room option.

Requesting these values at this level allows you to offer a two-step booking path directly from the list results.

Returns additional elements only with minorRev=22 or above.

V3 Turbo users: please note that including this parameter will prevent you from receiving a V3 Turbo cached response. Only standard, uncached responses will be returned.

includeHotelFeeBreakdown boolean no Returns the element HotelFeeBreakdown, which contains 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.
Room format for REST
The REST format compacts the values from the previous elements into a comma-delimited list. To declare a room and its occupants, use the following format:

&room[room number, starting with 1]=
[number of adults],
[comma-delimited list of children's ages]


For example, to declare that a room has one adult and two children ages 5 and 12, you would send &room1=1,5,12 . There is no separate declaration for the number of children - each age value is assumed to belong to a child.


Primary Search Methods
There are five primary methods available to limit the selection of hotels returned in the request, presented below in no particular order.
Four limit the selection by a defined location, and one allows an explicit set of hotels to be returned via a list of specific hotelIds.
Use only one of these methods at a time.


Method 1: City/state/country search
Name Value Required for search method Description
city string yes
City to search within. Use only full city names.
stateProvinceCode string yes for US,
CA, AU
Two character code for the state/province containing the specified city.

References:
US State Codes
Canadian Province/Territory Codes
Australian Province/Territory Codes
countryCode string yes
Two character ISO-3166 code for the country containing the specified city. Use only country codes designated as "officially assigned" in the ISO-3166 decoding table.


Method 2: Use a free text destination string
Name Value Required for search method Description
destinationString string yes A string containing at least a city name. You can also send city and state, city and country, city/state/country, etc.

This parameter is the best option for taking direct customer input.

Ambiguous entries will return an error containing a list of likely intended locations, including their destinationId (see below) whenever possible.


Method 3: Use a destinationId
Name Value Required for search method Description
destinationId string yes The unique hex key value for a specific city, metropolitan area, or landmark.

Obtain this value via a geo function request, or from a multiple locations error returned by a destinationString availability request.

Values for landmarks such as buildings, major neighborhoods, train stations, etc. can be obtained via a geo function request for landmarks. All available destinationIds can also be obtained via select files in our database catalog.



Method 4: Use a list of hotelIds
Name Value Required for search method Description
hotelIdList comma-separated
list of long
yes

Check for availability against a fixed set of hotels.

Send the hotelId values for the hotels you want to search for as a comma-separated list as a value for this element.

When using long lists, be aware that response times may increase noticably vs. smaller lists across multiple requests. Use POST instead of GET when sending long lists via REST.



Method 5: Search within a geographical area
Note: you can also use this method for searching for airports in conjunction with the airport coordinates file
Name Value Required for search method Description
latitude string yes Latitude coordinate for the search's origin point, in DDD.MMmmm format.
longitude string yes Longitude coordinate for the search's origin point, in DDD.MMmmm format.
searchRadius int no Defines size of a square area to be searched within - not an actual radius of a circle. The value is still treated as a radius in the sense that it is half the width of the search area.
Factor in the added area and maximum distances this creates vs a circular search area when exposing this value directly.
Example
A searchRadius value of 5 will create a 10 mi by 10 mi square search area. This covers an area approximately 20% larger than a circle with a 5 mile radius (π5^2 = 78.5 sq. mi. vs 100 sq. mi.), and allows a 7.1 mile maximum distance from the origin vs. the fixed radius of the circle.

Minimum of 1 MI or 2 KM, maximum of 50 MI or 80 KM.
Defaults to 20 MI.
searchRadiusUnit string no Sets the unit of distance for the search radius. Send
MI or KM. Defaults to MI if empty or not included.
sort string no You must send a value of proximity if you want the results to be sorted by distance from the origin point. Otherwise the default sort order is applied to any hotels that fall within the search radius.

See the full definition of this element in the next section for all available values.
Additional Search Methods
Offer these search methods as secondary options to allow customers to search via a nearby address or specific hotel.


Name Value Requires other parameters Description
address string yes Search nearby a local street address. The response will contain each property's proximity to the given address.

Even if a specific hotel's address is entered, its place in the default sort order will not be overridden if it is not already at the top.

Requires city and countryCode parameters to be defined.
postalCode string yes Optionally include an address' postal code.

Requires city and countryCode parameters to be defined.
propertyName string yes Name to search for availability. Value can be an exact name or part of a name, e.g. "Holiday" or "Best."

The response will contain any properties whose names contain the value included in this parameter.

If a specific property name is sent, an empty response may return if there is no availability for the given dates of stay.

Requires city and countryCode parameters to be defined.

Filtering Methods
These methods filter results via amenities, price, star ratings, and other typical shopping criteria. These can be offered prior to the initial search alongside a primary method, or used to dynamically update an existing search results page. They can also be used internally to limit results available to customers, e.g. restrict properties to a certain star level and above.

Name Value Required Description
includeSurrounding boolean no When sent as false, this parameter will exclude hotels outside of the area defined in your search parameters.
Use if you want to prevent hotels from other nearby cities or outlying areas from appearing in your results.
propertyCategory int or comma-delimited list of int no Filters results by property category. Send either a single value or a list of values to return a combination of property categories.

Values:
1: hotel
2: suite
3: resort
4: vacation rental/condo
5: bed & breakfast
6: all-inclusive
amenities int or comma-delimited list of int no

This element is no longer recommended for use. The values for this element do not match either Expedia's amenities nor our own amenity database files.

Instead, you can apply amenity filtering after receiving a response in one of two ways:

1. Decode the bitmask from the amenityMask value in the results to obtain each property's discrete amenities. You can use this sample utility to check your unmasking code: http://sandbox.ean.so/amenity/amenity.php

2. Download the AttributeList database file locally and use it to filter against hotels that are both in the requested location and that have the filtered amenities.

maxStarRating float no Filters results by a maximum star rating.
Valid values are 1.0 - 5.0 in increments of 0.5.
minStarRating float no Filters results by a minimum star rating.
Valid values are 1.0 - 5.0 in increments of 0.5.
minRate float no Filters results by properties with rates equal to or greater than the provided value.
Searches against the averageRate response value (average of the individual nightly rates during the dates of stay). Valid for availability searches only.
maxRate float no Filters results by properties with rates equal to or less than the provided value.
Searches against the averageRate response value (average of the individual nightly rates during the dates of stay). Valid for availability searches only.
numberOfBedRooms int no This parameter is valid for condos/vacation rentals only. Specifies the number of bedrooms requested - 4 maximum.
supplierType string no Filters results by supplier type. This parameter is typically used to restrict initial searches to Expedia Collect inventory only. If no availability is found, the parameter is omitted to allow Hotel Collect to return in a secondary search.

Values:
E: Expedia Collect
V: Venere (Hotel Collect )
E|V: Expedia Collect and Venere
S: Sabre (Hotel Collect )
W: Worldspan (Hotel Collect )

Only values of E or E|V are recommended.Other values will exclude Expedia Collect inventory and return only Hotel Collect properties that inherently lack reliable availability and commission guarantees.

Avoid using this parameter when requesting specific hotelIds from our database files. Supplier errors are likely to result.
maxRatePlanCount int no Defines the number of room types to return with each property.

Setting a higher value will attempt to return the corresponding number of room types at each property in the response, depending on individual property availabilities.

Defaults to 1, where the only the first room type at each property is returned. Under Expedia user testing, this value has been proven to provide the best conversion rates and is recommended to be left as-is, saving additional rooms for display during the room selection stage.

Sorting Options
We recommend sending initial searches without a specified sort order, as the default sort order is calculated to place the most preferred and best-converting properties at the top. Instead, allow customers to choose a different sort order after the initial list is returned.
Name Value Required Description
sort string no Sorting preference for properties returned.

Values:
NO_SORT Used only in conjunction with hotelIdList. Returns hotels in the exact order listed in the request.
CITY_VALUE The default sort order - returns hotels in the same order as if sort is omitted entirely. Properties within the specified city are ordered above properties in surrounding areas.
OVERALL_VALUE Places preferred, best-converting properties at the top.
PROMO Places properties with a promo rate or value add above properties not running promotions.
PRICE Sorts properties by nightly rate from low to high. The ordering is not perfect due to business/marketing office algorithms applied to property lists accessed by the API. Accurate price sorting is best achieved within your own code after results are received.
PRICE_REVERSE Sorts properties by nightly rate from high to low. Expect imperfect sort as detailed above.
PRICE_AVERAGE Sorts properties by average nightly rate from low to high. Expect imperfect sort as detailed above.
QUALITY Sorts by property star rating from high to low.
QUALITY_REVERSE Sorts by property star rating from low to high.
ALPHA Sorts properties alphabetically
PROXIMITY Sorts based on proximity to the origin point defined via latitude & longitude parameters.
POSTAL_CODE Sorts via postal code, from alphanumerically lower codes to higher codes.
CONFIDENCE Hotel Collect properties only. Sorts via our collections department's assessment of how likely individual properties are to pay commissions and how quickly they pay them. Best-performing properties return first.
MARKETING_CONFIDENCE Places Expedia Collect properties first, but sorts Hotel Collect properties thereafter by their confidence level.
TRIP_ADVISOR If you have an approved TripAdvisor integration, this value will sort results from high to low guest ratings.
Additional Data Request

Use this parameter to limit the response to specific types of dynamic data. Typically used in conjunction with our hotel database files as sources of static information normally supplied by the API. Integrations that use this parameter in conjunction with offline databases will enjoy significantly faster response times than those that rely soley on API responses.

Name Value Required Description
options string or comma-separated
list of string
no Defines the type of limited data to return. Send a single value or a combination in a comma-separated list.

Values:
DEFAULT Returns all three data types below. Response will be the same as if options were omitted entirely.
HOTEL_SUMMARY

Returns dynamic hotel information with a small amount of identifying static information (hotel name and address, location description, hotelId, etc).
Does not contain dynamic rate information. The slimmest possible availability response.

ROOM_RATE_DETAILS Returns dynamic room rate information and a bare minimum of static information via hotelId and roomDescription.
DEEP_LINKS Return deep links for the template with basic static info only.
Cached Responses/Turbo
Cached responses, also known as the Turbo service, can greatly decrease response times. Rather than obtaining all dynamic data directly from the supplier(s), they instead return data that has been cached from previous responses for a short time, if available for the specific request's parameters.

Ensure your integration is running on minorRev=11 or higher and specify the level of caching tolerance via a set of values for the supplierCacheTolerance element, as detailed below. We recommend MED_ENHANCED.


Name Type Required Description
supplierCacheTolerance string no

 

MIN Minimum caching tolerance indicates data has been held for the minimum amount of time.
30 minutes for < 5 available rooms
60 minutes for > 5 available rooms
MIN_ENHANCED Minimum caching tolerance with extrapolated currency and locale. (The results are cached in English and USD from the supplier, but converted to the requested currency and language at the time of request)
30 minutes for < 5 available rooms
60 minutes for > 5 available rooms
MED Medium caching tolerance.
2 hours for < 5 available rooms
4 hours for > 5 available rooms
MED_ENHANCED Default. Medium caching tolerance with extrapolated currency and locale as described above. Always returns a cached response if available. If you specify the MED instead of MED_Enhanced, then no cached response is returned from non-USD queries.
MAX Maximum caching tolerance. Always returns the last cached data regardless of time if available.
MAX_ENHANCED Maximum caching tolerance. Always returns the last cached data regardless of time if available with extrapolated currency and locale.

Paging for More Hotels
If the initial response returns moreResultsAvailable as true, the next page of results can be requested via the below process.

To page for more results, only cacheLocation and cacheKey may be sent in the subsequent availability request. All other non-common parameters must be omitted.

Lastly, if an error stating "cacheLocation cannot be found" returns, the cache has expired and the original search must be requested again. Cached responses have a typical life of 15-30 minutes.

Refer to Paging for More Results for examples.

Name Type Required for method Description
cacheKey string yes The key for the specific cached response requested. Use the value returned in the previous hotel list response.
cacheLocation string yes Defines the EAN server location of the requested cache. Use the value returned in the previous hotel list response.
Hotel List Response
Returns hotels in the specified location with rooms available for the provided guest count and dates of stay.

If a "dateless list" was requested via the omission of arrivalDate, departureDate and RoomGroup, the response contains all active hotels within the specified location without any specific availability information.

Response Content
Parent Element: HotelListResponse


Name Value Description
moreResultsAvailable boolean Indicates if there are more property results available to page.

If true, more results can be obtained via the paging process.
numberOfRoomsRequested int Confirms the number of rooms originally requested (number of Room nodes)
cacheKey string The key to the cache of the current response returned. Use this value in your next paging request.
cacheLocation string Defines the EAN server location of the cache for the current response returned. Use this value in your next paging request.
HotelList container for HotelSummary array

Contains attributes size, to indicate the number of individual properties in the response, and activePropertyCount, to indicate the total number of active (not necessarily available) properties in the specified location.

HotelList.HotelSummary object Array of individual hotels. Info for each hotel result is contained in its own HotelSummary node.
Contains attribute order, which indicates the original numerical order of each hotel to help restore from dynamic re-sorting (sequence starts from 0, not 1).
HotelSummary.hotelId long ID for the property. This same ID will be used in any subsequent room or reservation requests.
HotelSummary.name string Name of the hotel
HotelSummary.address1 string Hotel street address
HotelSummary.city string Hotel city
HotelSummary.stateProvinceCode 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
HotelSummary.countryCode string Two character ISO-3166 code for the country the hotel is located in
HotelSummary.postalCode string Postal code for the hotel
HotelSummary.airportCode string Airport code associated with the hotel
HotelSummary.supplierType string Supplier of the hotel. This same supplier will be used to process any reservations placed.
Use this element to determine proper text for pricing Expedia Collect and Hotel Collect listings.

Values:
E: Expedia Collect
V: Venere (Hotel Collect )
S: Sabre (Hotel Collect )
W: Worldspan (Hotel Collect )
HotelSummary.propertyCategory string The category of the property returned.

Values:
1: hotel
2: suite
3: resort
4: vacation rental/condo
5: bed & breakfast
6: all-inclusive
HotelSummary.hotelRating float Star rating of the hotel. A value of 0.0 or a blank value indicate none is available. For Hotel Collect , this value is determined by translating Sabre diamond ratings, which may not be available.
HotelSummary.confidenceRating int

Returns for Hotel Collect only. Our collections department's assessment of how likely individual properties are to pay commissions and how quickly they pay them.

HotelSummary.amenityMask long See details on hotel amenity masks
HotelSummary.shortDescription string Short description text entered by the property. Truncated if entry exceeds 200 characters.
For better performance, add an ellipsis (…) to the end of this value and set it to link to the property's room availability page.
HotelSummary.locationDescription string General location as entered by the property, e.g. "Near Pike Place Market"
HotelSummary.lowRate string Lowest rate returned by the hotel in recent queries. This is a statistical figure and not necessarily a rate for current availability.
HotelSummary.highRate string Highest rate returned by the hotel in recent queries. This is a statistical figure and not necessarily a rate for current availability.
HotelSummary.rateCurrencyCode string Currency code of the high or low rates returned.
HotelSummary.latitude float Latitude coordinate for the hotel.
HotelSummary.longitude float Longitude coordinate for the hotel.
HotelSummary.proximityDistance float The distance of the hotel from the originally specified origin coordinates, if that search method was used.
HotelSummary.proximityUnit string Unit for the distance provided by proximityDistance. MI or KM.
HotelSummary.hotelInDestination boolean Indicates whether the property is within the originally specified city or in an expanded area, i.e. a major suburb or other nearby city.

Expedia Collect hotels outside of the destination are grouped by distance from the original area, e.g. under 10 miles away, under 20 miles away, etc. Hotel Collect will always appear after any and all Expedia Collect results regardless of proximity.
HotelSummary.thumbNailUrl string URL path of a thumbnail image of the property, if provided.

Full URLs are not returned - append this value with http://images.travelnow.com, or your own image subdomain by setting up a CNAME with origin-images.travelnow.com as the destination. HTTPS with SSL is supported.
string Deep link into the corresponding hotel page on your template, used if you are creating a hybrid site.

Format returned is only compatible with legacy template accounts. If you have a Chameleon template account, the URL will return an error. Refer to the deep link formatting guide on the hybrid sites page to create deep links compatible with your template.

These links can also be masked with a CNAME.
HotelSummary.RoomRateDetailsList container for RoomRate
Details
array
Container only, no attributes. Element and all contents return for Expedia Collect only.
RoomRateDetailsList.RoomRateDetails array Contains the details for the first room returned by the hotel. Additional nodes for each additional room returned if maxRatePlanCount value was sent >1
RoomRateDetails.roomTypeCode string Room type code for the room.
RoomRateDetails.rateCode string Code to the displayed rate. For Hotel Collect listings, special requirements such as AAA or AARP membership are determined via this or the previous element.
RoomRateDetails.maxRoomOccupancy int Maximum number of guests allowed in the room returned.
RoomRateDetails.quotedRoomOccupancy int Confirms the actual occupancy used to calculate the rate.
RoomRateDetails.minGuestAge int Minimum guest age allowed in the room
RoomRateDetails.roomDescription string Description of the room associated with the roomTypeCode returned
RoomRateDetails.promoId string ID for the promo offer returned, if any.
RoomRateDetails.promoDescription string Description for the promo returned, if any. Max of 255 chars will return.
RoomRateDetails.promoDetailText string Extra details for the promo returned, if any.
RoomRateDetails.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.
RoomRateDetails.propertyAvailable boolean For internal inventory reference only.
|Only available inventories will return on standard requests.
RoomRateDetails.propertyRestricted boolean For internal inventory reference only. Refer to cancellation policy for any specific restrictions.
RoomRateDetails.expediaPropertyId string Expedia's ID for the hotel. Use this value to map to a hotelId when cross-referencing to Expedia. A complete cross-reference file is also available in the database catalog.
RoomRateDetails.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
Available with minorRev=22 or higher. Returns only if includeDetails=true was sent in the request.
RoomRateDetails.smokingPreferences comma-separated list of string Available smoking preferences for the room, if any.

Values:
NS: non-smoking
S: smoking
E: either

Available with minorRev=22 or higher. Returns only if includeDetails=true was sent in the request.
RoomRateDetails.rateKey string Key to the rate and parameters determining the rate.

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.

Returns in this location for minorRev=17 and below. If includeDetails=true was sent in the request under minorRev=22 or higher, this value will return within the Room object.
RoomRateDetails.nonRefundable boolean Indicates explicitly if the reservation can be refunded or not after booking. Should also be indicated within the cancellation policy returned.
Returns only with availability and minorRev=10 to 19.
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 Has a numerical ID attribute and contains a description element for a free service offered with the provided room and rate, such as free breakfast or wireless internet.

See knownID attributes and description values
ID description
1 All Meals
2 Continental Breakfast
4 Full Breakfast
8 English Breakfast
16 Free Lunch
32 Free Dinner
64 Food/Beverage Credit
128 Free Parking
256 Free Airport Parking
512 All-Inclusive
1024 Free High-Speed Internet
2048 Free Wireless Internet
4096 Continental Breakfast for 2
8192 Breakfast for 2
16384 Free Valet Parking
32768 Free Airport Shuttle
65536 Free Room Upgrade
131072 Resort Credit Included
262144 Welcome Gift Upon Arrival
524288 Spa Credit
1048576 Golf Credit
2097152 VIP Line Access to Nightclub(s)
4194304 2-for-1 Buffet
8388608 Free Ski Lift Ticket & Rental
16777216 Breakfast Buffet
33554432 Half Board
67108864 Full Board
134217728 Full Kitchen
268435456 Slot Play
536870912 Casino Credit
1073741824 Match Play
RoomRateDetails.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:
priceBreakdownboolean Indicates if a full price breakdown including taxes and total price to be charged is included. Typically only false for Hotel Collect properties, where the total is not known until the end of the actual dates of stay.
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.promoId string ID for the promo offer returned, if any. Returned in RoomRateDetails below minorRev=20
RateInfo.promoDescription string Description for the promo returned, if any. Max of 255 chars will return. Returned in RoomRateDetails below minorRev=20
RateInfo.promoDetailText string Extra details for the promo returned, if any. Returned in RoomRateDetails below minorRev=20
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.
Returned in RoomRateDetails below minorRev=20
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.
Available with minorRev=22 or higher. Returns only if includeDetails=true was sent in the request.
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.
Available with minorRev=22 or higher. Returns only if includeDetails=true was sent in the request.
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.
Available with minorRev=18 or higher. Returned in the main body of the response below minorRev=20
RateInfo.nonRefundable boolean Indicates explicitly if the reservation can be refunded or not after booking. Should also be indicated within the cancellation policy returned.
Returns only with availability and minorRev=20 and above. Returned in RoomRateDetails below minorRev=20
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.
Available with minorRev=21 or higher. You must upgrade to the schema under minorRev=20 in order to use this element.
RateInfo.ChargeableRateInfo object This object's attributes contain the absolute total to be charged for the reservation (for Expedia Collect) 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 for an Expedia Collect property.
surchargeTotal float The value from the TaxAndServiceFee attribute of the Surcharges array.
nightlyRateTotal float Total of all values in the nightlyRatesPerRoom array contained within this object.
maxNightlyRate float Highest nightly rate of all rates returned (important for Hotel Collect )
currencyCode string Currency code for the rates returned
commissionableUsdTotal float Amount used to calculate partner commissions, in USD. Total of nightly rates less surchages.
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 Details 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.

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.
ChargeableRateInfo.Surcharges array Container for Surcharge array. This array itemizes the individual surcharges that make up the value returned for surchargeTotal. Has 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.

Attributes:
amount float Amount of the specific surcharge
type string Name of the surcharge.
Possible values:
  • Tax
  • ServiceFee
  • ExtraPersonFee
  • SalesTax
  • HotelOccupancyTax
  • TaxAndServiceFee

Note: 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.
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.
Available with minorRev=18 or higher.
HotelFees array This element breaks out certain taxes and fees collected by the hotel that are otherwise not specifically 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.
Available with minorRev=19 or higher.

Please note child element HotelFeeBreakdown must be specifically requested and requires minorRev=24 or higher.
HotelFees.HotelFee none Contains attributes for the description, amount, and currency of a single fee. Details any VAT, state/city tax, resort fees, or any other fees collected that cannot be reasonably avoided.
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 Total value for the charge.

Available with minorRev=19 or higher.

HotelFee.HotelFeeBreakdown none Returns if includeHotelFeeBreakdown was sent in the request. Details how the fee provided in HotelFee is applied and how often it applies.

Note: All HotelFee amount values are totals. Do not be multiply them by any frequency provided here.

You may divide by the amount as indicated by frequency to obtain nightly/daily/weekly charges if desired.

Available with minorRev=24 or higher.

Attributes:
unit string How the fee is distributed. Possible values:
  • Per Person
  • Per Room
  • Per accommodation
  • Per house
  • Per apartment
  • Per adult
frequency string Frequency of the fee. Possible values:
  • Per Night
  • Per Day
  • Per Stay
  • Per week
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.
RoomGroup object Confirms the contents of the same RoomGroup object sent in the request as they apply to the rates provided.
For minorRev=22 and higher, rateKey will only return within the Room object if it is requested via includeDetails=true in the request.
CachedSupplierResponse


The CachedSupplierResponse element is returned when a cached hotel list response is provided. Cached responses are always returned when available unless you have configured your integration to use at least minorRev=11.

Attributes for the CachedSupplierResponse element:
Name Value Description
cachedSupplierResponse object Contains information about cached data, internal use. Returned only with cached responses for Expedia Collect under minorRev=11 or higher.
cacheEntryHitNum int Internal
cacheEntryMissNum int Internal
cacheEntryExpiredNum int Internal
cacheRetrievalTime long Cache retrieval time.
supplierRequestNum int Number of results requested from the supplier
supplierResponseNum int Number of results returned from the supplier
supplierResponseTime long How fast the supplier returned the results
candidatePrepTime long Time to determine or prepare the request list of properties.
otherOverheadTime long Time to collect non-cached Hotel Collect results.
tpidUsed int Internal identifier based on currency and locale.
matchedCurrency boolean Returns either matched or converted (extrapolated) data from the cache .
matchedLocale boolean Returns either matched or translated data from the cache.
extrapolatedCurrency boolean Returns either matched or converted (extrapolated) data from the cache. (The results are cached in English and USD from the supplier, but converted to the requested currency and language at the time of request)
extrapolatedLocale boolean Returns either matched or translated data from the cache.