擷取滿足所提供房客計數和其他條件的特定飯店之客房資料。

可建構此要求以提供資料作為客房選擇或其他可預先訂房的購物區之用,或在送出訂房資料前,用於確認房價資料。

訂房前必須先執行方式 2,該方式會確認目前的價格,以及要訂房成功所需的空房資料。

方式 1: 傳回所有客房的空房狀況和價格

此方式用於客房選擇頁面或其他購物區,這些區域需要飯店內多間客房的資訊。

除了必要的基本元素外,您也可以傳送指示的選用元素,以要求客房等級圖片或限制回應中所包含的飯店資訊類型。

Name Required
apiExperience
hotelId
arrivalDate
departureDate
RoomGroup
includeRoomImages
includeHotelFeeBreakdown
options

方式 2: 確認所選的客房以付款

在旅客選擇要預訂的特定客房後,才使用此選項。

此要求組態會擷取旅客所選客房的最新房價資料,可降低因房價不符或訂滿錯誤所造成的訂房失敗率。

Name Required
apiExperience
hotelId
arrivalDate
departureDate
RoomGroup
rateCode
roomTypeCode
includeDetails
includeHotelFeeBreakdown
要求格式
XML/REST URL: GET http://api.ean.com/ean-services/rs/hotel/v3/avail?
XML 父項目: <HotelRoomAvailabilityRequest>
唯一通訊協定需求
REST:客房和房客計數的格式與 XML 不同。在飯店清單頁面上檢閱 REST 客房格式

請注意:此服務的必要參數現在分成兩個上述的服務方法

要求參數

基本參數
名稱 於方式中為必要 說明
apiExperience 字串 1&2 利用此屬性辨識您的原始要求。請在下方提供的設定中,為每個您送出的要求選擇適當的值。

值:
PARTNER_CALL_CENTER - 來自客戶服務中心服務專員的要求
PARTNER_WEBSITE - 來自旅客服務網站的要求
PARTNER_MOBILE_WEB - 來自行動版網站的要求
PARTNER_MOBILE_APP - 來自行動 App 的要求
PARTNER_BOT_CACHE - 來自快取程式的要求
PARTNER_BOT_REPORTING - 來自報告程式的要求

hotelId 長整數 1&2 要與之查詢是否有空房的飯店 ID
arrivalDate 字串 1&2

入住日期 (格式為 MM/DD/YYYY)。

加入今天的日期以要求同天的空房情況。最晚可於飯店所在當地時間晚上 11:59 訂房 (如為太平洋標準時間和太平洋島嶼,時間則為晚上 9:59)。

departureDate 字串  1&2 退房日期 (格式為 MM/DD/YYYY)。

搜尋時,空房情況最多可顯示此日期後 500 天以內的資料。

總住宿天數不能超過 28 天。
RoomGroup 物件 1&2 定義房客和客房計數的 Room 陣列適用容器應用程式。如果您在清單要求中使用了 REST,請記得格式要與唯一 REST 格式保持一致。
RoomGroup.Room 陣列 1&2 Room 節點的數目可定義要求客房的數目。每個節點都會有其各自的成人/兒童房客計數。

飯店允許每次最多預訂 8 間客房。
Room.numberOfAdults 整數 1&2 客房的成人房客計數。

將入住率限制為飯店的飯店清單回應中傳回的最高 maxRoomOccupancy (上限為 8)。
Room.numberOfChildren 整數 1 與 2 (如果兒童數 > 0) 客房的兒童房客計數。若為「兒童」時,則為所有飯店的必要項目。與 childAges 結合使用以判定空房情況和房價。
Room.childAges 整數的逗號分隔
清單
1 與 2 (如果兒童數 > 0) 以逗號分隔清單方式傳送客房中每位住宿兒童的個別年齡。

部分飯店對於兒童與成人的定義並不相同,因此如果旅客指定有兒童房客,務必請求旅客提供此資訊。例如,某家飯店可能會將年齡為 17 歲的旅客子女視為成人,因此如果客房定義的可入住成人房客人數已達上限,則可能會產生加床費用。
roomTypeCode 字串 僅為 2 只有在已經取得旅客的特定客房選擇時才可使用。此參數將傳回客房的取消政策、床型和吸菸選擇。

傳送時需搭配 rateCode
rateCode 字串 僅為 2 只有在已經取得旅客的特定客房選擇時才可使用。此參數將傳回客房的取消政策、床型和吸菸選擇。

傳送時需搭配 roomTypeCode
includeDetails 布林值 僅為 2 在旅客已選取客房後用於方法 2

作為 true 傳送,以傳回所提供客房與房價代碼的可訂房房價資料。

連同 roomTypeCoderateCode 一起傳送
includeRoomImages 布林值 no 擷取指定的 hotelId 客房等級圖片。

也能以獨立要求方式提供。
includeHotelFeeBreakdown 布林值 no 針對包含每種費用的套用頻率和套用方式的 HotelFees 陣列傳回 更詳細的回應結構。有 minorRev=24 以上參數時即可使用。
options 字串或字串的逗號分隔
清單
no 使用方法 1 填入飯店的客房選項時,請使用此參數取代別的飯店資訊要求。

傳送單一值,或以逗號分隔清單方式傳送值的組合。

值:
HOTEL_DETAILS 只擷取飯店詳情 (飯店說明)
ROOM_TYPES 擷取房型
ROOM_AMENITIES 擷取客房設施清單 (小廚房、電視等)
PROPERTY_AMENITIES 擷取飯店設施清單 (Spa、健身房、會議室)
HOTEL_IMAGES 只擷取飯店圖片網址 (非客房圖片)
numberOfBedRooms 整數 no 此參數僅限假期租賃 / 渡假公寓有效。指定要求的客房數目 - 最高值為 4。
supplierType 字串 no 提供與過去飯店清單回傳中傳回相同的值。

值:
E:Expedia Collect
rateKey 字串 no 決定之前飯店清單回傳中提供之價格的參數索引碼。
飯店客房回應
會傳回在所要求的特定飯店中,可在指定的住宿日期讓指定房客數入住的客房,或確認所提供 roomTypeCoderateCode 的空房與價格。

此回傳也會傳回入住指示、更詳盡的飯店詳細資料、詳細的價格資訊,最重要的是,此回傳還會傳回訂房所需的 rateKey

如果方法 1 要求中包含 options 物件,則也會傳回於物件中指定的詳細資料 (若有的話)。

回應內容
父項目: HotelRoomAvailabilityResponse
屬性: size - 傳回的客房數量

名稱 說明
hotelId 長整數 飯店的 ID。此相同 ID 將於後續訂房要求中使用。
arrivalDate 字串 確認要求中送出的入住日期。
departureDate 字串 確認要求中送出的退房日期。
hotelName 字串 飯店名稱
hotelAddress 字串 飯店街道地址
hotelCity 字串 飯店城市
hotelStateProvince 字串 包含指定城市的州/省代碼 (兩個字元)。只傳回 US、CA 和 AU 國家節點。

參考資料:
美國各州代碼
加拿大省份/地區代碼
澳大利亞省份/領土代碼
  • 澳大利亞首都 - AC
  • 新南威爾斯 - NW
  • 北領地 - NO
  • 昆士蘭 - QL
  • 南澳大利亞 - SA
  • 塔斯馬尼亞 - TS
  • 維多利亞 - VC
  • 西澳大利亞 - WT
hotelCountry 字串 飯店所在國家的 ISO-3166 代碼 (兩個字元)。
numberOfRoomsRequested 整數 確認要求中送出的 Room 節點數目。
checkInInstructions 字串 如果由飯店傳回,則為必要顯示項目。
可能包含入住時衍生的費用、延遲入住的指示等。
HotelRoomResponse 陣列 每個節點都包含飯店個別客房的價格與詳細資料。此陣列的 JSON 回傳格式 可能導致 Axis 中出現問題
HotelRoomResponse.policy 字串 其他政策,例如入住所需的相片 ID。
HotelRoomResponse.rateCode 字串 顯示的房價代碼。
HotelRoomResponse.roomTypeCode 字串 客房的房型代碼。

如果 options 參數在空房要求中傳送,系統就不會傳回此元素。系統會改以 roomCode 物件的 RoomType 屬性傳送此值。
HotelRoomResponse.rateDescription 字串

客房和應收房價的簡短說明,例如:Deluxe Room King - 全包式。

建議作為主要顯示

HotelRoomResponse.roomTypeDescription 字串 房型的簡短說明,例如豪華客房特大雙人床。

如果 options 參數在空房要求中傳送,系統就不會傳回此元素。系統會改以 RoomType 物件內的 description 元素傳送此值。
HotelRoomResponse.supplierType 字串 飯店的合約飯店。此相同的合約飯店將用於處理所有收到的訂房。

值:
E:Expedia Collect
HotelRoomResponse.otherInformation 字串 飯店的其他資訊 (如果可用)。
HotelRoomResponse.propertyId 字串 Expedia 的飯店 ID。使用此值即可在與 Expedia 交互參照時對應至 hotelId 。您也可在資料庫目錄中取得完整的交互參照檔案。
HotelRoomResponse.smokingPreferences 字串的逗號分隔清單 可供選擇的客房吸菸偏好 (如果有的話)。

值:
NS:非吸菸
S:吸菸
E:皆無
HotelRoomResponse.minGuestAge 整數 客房中入住的任何房客最低年齡限制,例如 1821 (如果不允許兒童入住)。將傳回為 0 ,或完全不傳回 (如果沒有最低年齡限制)。
HotelRoomResponse.quotedOccupancy 整數 根據提供的客房價格而得的房客計數。

如果客房價格在此房客計數和 rateOccupancyPerRoom 中提供的房客計數之間沒有改變,則可能低於指定的房客計數。
HotelRoomResponse.rateOccupancyPerRoom 整數 表示針對提供的價格客房可入住的房客人數。

如果要求的房客計數超過此值 (如為多間客房,則為這些值的總計),請提醒使用者有此類不一致的情況,讓使用者在訂房前了解可能需支付加床費用,或者飯店無法針對其總人數需求提供客房。
字串 與您範本上對應的空房頁面做深度連結;此連結會於您建立 混合式網站時使用。

傳回的格式只與舊版範本帳戶相容。如果您有 Chameleon 範本帳戶,網址就會傳回錯誤。請參閱混合式網站頁面上的深度連結格式指南,以建立與您範本相容的深度連結。

此類連結也可能會以 CNAME 遮罩
HotelRoomResponse.BedTypes 陣列 個別客房的床型選擇。可在訂房時傳回單人床型或包含可供選擇的床型。檢閱床型的詳細資料
HotelRoomResponse.ValueAdds ValueAdd 適用的容器應用程式 包含提供的客房與房價 ValueAdd 元素陣列 (如果可用)。有 size 屬性以表示傳回的新增值數。
ValueAdds.ValueAdd 陣列

包括 description 元素,此元素用於提供的客房及價格所供應的免費服務,例如早餐或無線網際網路。

若值為 minorRev=28 以上,則 id 屬性的數值不會傳回,只會提供 description。您必須至少使用 minorRev=28 傳回您行程及訂房回應中新增的值。

使用 minorRev=26 或以下的值時,下列已知 id 屬性將與其 description 值一起傳回。

ID description
1 所有餐點
2 歐式早餐
4 標準早餐
8 英式早餐
16 免費午餐
32 免費晚餐
64 餐點/飲料折讓
128 免費停車
256 免費機場停車
512 全包式
1024 免費高速網路
2048 免費無線網路
4096 雙人歐式早餐
8192 雙人早餐
16384 免費代客停車
32768 免費機場接送
65536 免費客房升級
131072 包含渡假區折讓
262144 入住時贈送迎賓禮品
524288 Spa 折讓
1048576 高爾夫球折讓
2097152 夜店 VIP 快速通道
4194304 自助餐 2 人同行 1 人免費
8388608 免費滑雪纜車票劵和租賃
16777216 自助式早餐
33554432 住宿含早、晚餐
67108864 住宿含三餐
134217728 完整廚房配備
268435456 吃角子老虎遊戲
536870912 賭場折讓
1073741824 比賽遊戲
HotelRoomResponse.RoomImages 陣列 任何可用的客房等級圖片網址陣列 (如果透過 includeRoomImages 參數要求)。
HotelRoomResponse.RoomType 物件 options 參數與 ROOM_TYPES 的值和/或 ROOM_AMENITIES 一起傳送時傳回。

屬性:
roomCode:取代 roomTypeCode 元素
roomTypeId
RoomType.description 字串 取代 roomTypeDescription 元素。必須在個別客房頁面以及所有訂房及訂房確認頁面上顯示。
RoomType.descriptionLong 字串 更詳細的客房說明 (如果可用)。
RoomType.roomAmenities 陣列 客房設施 清單,如果可用 (與列於飯店資訊回傳中相同的內容和結構)
RoomType.HotelDetails 物件 飯店說明內容 (與列於飯店資訊回傳中相同的內容和結構)
RoomType.PropertyAmenities 物件 飯店設施資訊 (與列於飯店資訊回傳中相同的內容和結構)
RoomType.HotelImages 物件 飯店圖片資訊 (與列於飯店資訊回傳中相同的內容和結構)
HotelRoomResponse.RateInfos RateInfo 適用的容器應用程式 包含 RateInfo 元素的陣列,可針對個別客房提供詳細的房價資訊。

如果您使用舊版整合方式,且執行 minorRev=6 或較舊參數,RateInfo 將不會與 RateInfos 容器應用程式一起傳回。
RateInfos.RateInfo 物件 包含多種不同物件和個別值以內的單一客房所有房價資訊。

屬性:
priceBreakdown 布林值 表示是否包含完整房價分類,包括稅金和要支付的總費用。
promo 布林值 表示房價是否為促銷價格。
rateChange 布林值 表示住宿期間是否至少有一晚的房價不同。
RateInfo.RoomGroup 物件 確認相同的 RoomGroup 物件內容因適用於提供的房價,所以已於要求中傳送。minorRev=29 以上時,請包含每間房每晚房價的詳細資料。
RoomGroup.Room 物件 物件的兒童元素可確認計算提供房價時使用的特定 numberOfAdultsnumberOfChildrenchildAges
Room.rateKey 物件 搜尋參數和其他值的索引碼,可決定房價

請注意,在幾乎大多數的情況下,此值都會不同於飯店空房回傳中傳回的值 - 總是從此回傳傳遞值至訂房要求。

每次變更搜尋參數時 (房客計數變更、改變住宿日期、增加兒童人數等),就必須送出新要求才能取得此參數的新值。

針對 minorRev=18 以下,此元素將包含於回應本文中傳回。
Room.ChargeableNightlyRates 陣列 客房 NightlyRate 陣列的容器。依住宿期間的順序,傳回個別客房的特定房價。

針對多間客房的每晚平均費用,使用 nightlyRatesPerRoom 提供的值。

minorRev=29 以上時傳回。
ChargeableNightlyRates.NightlyRate 物件 提供要求之住宿期間內住宿一晚的房價。在此地點內傳回時,房價永遠是所包含 Room 的特定值。

表示促銷房價、基本房價及套用促銷後的房價 (若有的話)。僅包含屬性。

minorRev=29 及以上時傳回。

屬性:
promo 布林值 表示此晚住宿房價是否有套用促銷價格。
rate 浮點數 套用促銷 (如果有的話) 後的每晚房價。
baseRate 浮點數 套用促銷 (如果有的話) 前的每晚房價。
ChargeableNightlyRates.NightlyRate 物件

轉換成旅客要求的貨幣價格資訊。僅在飯店或旅客市場地區無法以要求的貨幣計費時傳回。包含與 ChargeableNightyRates 相同的屬性。 minorRev=29 以上時傳回。

ChargeableNightlyRates.
ConvertedNightlyRates
物件 轉換成旅客要求的貨幣價格資訊。僅在飯店或旅客市場地區無法以要求的貨幣計費時傳回。包含與 ChargeableNightyRates 相同的屬性。 minorRev=29 以上時傳回。
RateInfo.promoId 字串 傳回的促銷折扣 ID (如果有的話)。以 minorRev=20以下回傳 HotelRoomResponse
RateInfo.promoDescription 字串 傳回的促銷說明 (如果有的話)。系統將傳回最多 255 個字元。以 minorRev=20以下回傳 HotelRoomResponse
RateInfo.promoDetailText 字串 傳回的促銷額外詳細資料 (如果有的話)。以 minorRev=20 以下回傳 HotelRoomResponse
RateInfo.nonRefundable 布林值 表示訂房是否為不可退款。如果傳回就必須顯示 - 成功訂房後,所有價格即為最終價格。以 minorRev=20以下回傳 HotelRoomResponse
RateInfo.depositRequired 布林值 如為 Expedia Collect,請務必以 true 傳回。
RateInfo.rateType 字串 表示傳回的房價是否已透過 EAN 於線上付款或之後將於飯店付款。與線上付款的空房情況 MerchantStandard 值一起傳回,或針對之後於飯店付款完全不傳回。
若是 minorRev=20 以上,會將元素包含在此地點傳回。若是 minorRev=1819,則會包含在回應本文中傳回。
RateInfo.currentAllotment 整數 飯店剩餘的可訂房客房數目。使用此值,即可建立緊急訊息的規則,提醒使用者在旺季期間或熱門飯店空房數目不多。

如果傳回的值為 0,並不表示飯店沒有客房。這只是代表不符合計算值所需的規則 - 此值並不表示絕對的空房情況。以 minorRev=20以下回傳 HotelRoomResponse
RateInfo.cancellationPolicy 字串 此客房的飯店取消政策。必須在個別客房頁面以及所有訂房及訂房確認頁面上顯示。以 minorRev=20以下回傳 HotelRoomResponse
RateInfo.CancelPolicyInfoList Cancel
PolicyInfo
適用的容器應用程式
取消政策的特定詳細資料,通常是決定懲罰期和取消所產生的懲罰時間。針對 minorRev=20 以下,包含在 HotelRoomResponse 中傳回。
檢閱 CancelPolicyInfo 陣列詳細資料
RateInfo.ChargeableRateInfo 物件 此物件的屬性包含訂房應支付的絕對總金額以及平均房價和總價。物件內的節點提供每晚房價和附加費的詳細資料。

屬性:
total 浮點數 訂房應支付的所有每晚房價、稅金和附加費總金額。此為必須顯示讓旅客查看,且需包含在訂房要求中的總值。
surchargeTotal 浮點數 TaxAndServiceFeeExtraPersonFee 的總值,來自 Surcharges 陣列。
nightlyRateTotal 浮點數 此物件中包含的 nightlyRatesPerRoom 陣列內所有值的總值。
maxNightlyRate 浮點數 所有傳回的房價中最高的每晚房價
currencyCode 字串 傳回房價的貨幣代碼
commissionableUsdTotal 浮點數 計算合作夥伴佣金使用的金額,以美金 (USD) 為單位。附加費較低的每晚房價總金額。
averageRate 浮點數 所有每晚房價平均值,包含適用的促銷值且不含附加費。
averageBaseRate 浮點數 所有每晚房價平均值,不含適用的促銷值且不含附加費。如果沒有促銷,則會傳回與之前相同的值。
ChargeableRateInfo.
nightlyRatesPerRoom
陣列 NightlyRate 陣列適用的容器應用程式。有 size 屬性以表示陣列中的節點數目,此數目將與要求中的住宿天數相對應。依住宿期間的順序傳回房價。
nightlyRatesPerRoom.NightlyRate

提供要求之住宿期間內住宿一晚的房價。

表示促銷房價、基本房價及套用促銷後的房價 (若有的話)。僅包含屬性。

若要求多間客房,則此值為所有客房的每晚平均費用。EAN 建議顯示多間客房的房價時,使用新的每房 ChargeableNightlyRates 陣列。

針對 minorRev=28 以下的多間客房要求,此元素僅會提供第一間客房的房價,而不會提供平均房價。



屬性:
promo 布林值 表示此晚住宿房價是否有套用促銷價格。
rate 浮點數 套用促銷 (如果有的話) 後的每晚房價。
baseRate 浮點數 套用促銷 (如果有的話) 前的每晚房價。
RateInfo.promoType 字串 表示傳回的任何促銷是否為行動版特定或標準促銷傳回行動版促銷的 Mobile 和所有其他的 Standard
如果要傳回行動版促銷,您必須透過合適的 customerUserAgent 字串辨識您的行動網站或 App。
minorRev=21 以上參數時即可使用。
ChargeableRateInfo.Surcharges 陣列 Surcharge 陣列適用的容器應用程式。此陣列會逐項列出組成 surchargeTotal傳回值的個別附加費。有 size 屬性以表示陣列中的節點數目。
Surcharges.Surcharge 詳細列出單一附加費的金額與類型。僅包含屬性。

屬性:
amount 浮點數 特定附加費的金額
type 字串 附加費名稱。
可能的值:
  • TaxAndServiceFee
  • ExtraPersonFee
  • Tax
  • ServiceFee
  • SalesTax
  • HotelOccupancyTax

TaxAndServiceFeeExtraPersonFee 可計入 surchargeTotal。所有其他值都是 TaxAndServiceFee 值的個別元件。


注意:根據紐約州法律規定,必須顯示 SalesTaxHotelOccupancyTax 附加費類型。確保您期望和擷取這些值,以在最終房價分類中顯示為「飯店入住與銷售稅」。

RateInfo.HotelFees 陣列

此元素會顯示由飯店收取的特定稅金與費用明細,如果不顯示,則不會在附加費陣列中特別詳細列出。

此元素中所有值都會由飯店在旅客入住或退房時收取。這些值不屬於訂房時收取的任何費用。

產生時,使用此元素即可符合主要搜尋引擎和彙總工具所需的價格 / 稅金 / 費用顯示格式。

包含 size 屬性以表示包含費用的數目。
minorRev=19 以上參數時即可使用。

HotelFees.HotelFee 包含單一費用的說明、金額和貨幣屬性。詳細列出任何營業稅、州 / 省 / 城市稅、渡假區費用,或任何其他必須收取的費用。
於可訂房貨幣中傳回的費用會以 ChargeableRateInfocurrencyCode 屬性表示。

屬性:
description 字串 收費的類型。可能的值:
  • MandatoryFee
  • MandatoryTax
  • ResortFee
amount 浮點數 費用值。

minorRev=19 以上參數時即可使用。

HotelFee.HotelFeeBreakdown 只有在 includeHotelFeeBreakdown 已於要求中傳送時才會傳回。詳述費用的套用方式和套用頻率。

屬性:
unit 字串 費用分配的方式。可能的值:
  • Per Person
  • Per Room
  • Per accommodation
  • Per house
  • Per apartment
  • Per adult
frequency 字串 費用的頻率。可能的值:
  • Per Night
  • Per Day
  • Per Stay
  • Per week

minorRev=24 以上參數時即可使用。

RateInfo.ConvertedRateInfo 物件 轉換成旅客要求的貨幣價格資訊。只有在付款使用和轉換的貨幣不同時才會傳回,也就是說,當飯店無法接受旅客要求的貨幣時。包含與 ChargeableRateInfo 相同的屬性。