按照地點或特定 hotelIds.

清單擷取飯店清單。此方式可用於針對提供的日期範圍傳回有空房的飯店,或傳回在指定地點中的所有刊登中飯店清單,且不顯示任何空房資訊。

此方式支援使用多個篩選條件以及指定所要位置的方式,因此可允許使用多個前端搜尋選項,例如依機場代碼或地圖顯示搜尋。

要求格式
XML/REST URL: GET http://api.ean.com/ean-services/rs/hotel/v3/list?
XML 父項目: <HotelListRequest>

唯一通訊協定要求
REST
要求參數
每筆針對有空房的飯店所進行的搜尋都必須至少有日期範圍、客房計數和成人房客計數,而且還必須有地點或 hotelId 清單。

若要取得「無日期清單」,或位於某地點的所有刊登中飯店清單,且不顯示特定空房資訊,只要省略要求中的 arrivalDatedepartureDateRoomGroup 參數即可。

基本參數
名稱 必要 說明
apiExperience 字串 yes

利用此屬性辨識您的原始要求。請在下方提供的設定中,為每個您送出的要求選擇適當的值。

值:
PARTNER_CALL_CENTER - 來自客戶服務中心服務專員的要求
PARTNER_WEBSITE - 來自旅客服務網站的要求
PARTNER_MOBILE_WEB - 來自行動版網站的要求
PARTNER_MOBILE_APP - 來自行動 App 的要求
PARTNER_BOT_CACHE - 來自快取程式的要求
PARTNER_BOT_REPORTING - 來自報告程式的要求
PARTNER_AFFILIATE - 來自提供您專屬合作夥伴庫之 API/平台的要求

arrivalDate 字串 yes 以顯示空房情況

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

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

departureDate 字串 yes 以顯示空房情況 退房日期 (格式為 MM/DD/YYYY)。

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

總住宿天數不能超過 28 天。
numberOfResults 整數 no 每個回應所能傳回的飯店數量最大值 (優先於 額外結果頁面的需求)。可接受的值範圍為 1200。預設:20

不針對無日期清單要求限制搜尋結果數目。
RoomGroup 物件 yes 以顯示空房情況 定義房客和客房計數的 Room 陣列適用容器應用程式。如為 REST,請參閱下方內容
RoomGroup.Room 陣列 yes 以顯示空房情況 Room 節點的數目可定義要求客房的數目。每個節點都會有其各自的成人/兒童房客計數。

飯店允許每次最多預訂 8 間客房。
Room.numberOfAdults 整數 yes 以顯示空房情況 客房的成人房客計數。

飯店通常允許 4 位房客入住,如果超過便需支付加床費用。

每間客房入住人數請勿超過 8 位房客,因為對大部分飯店而言,如果房客人數超過此計數,系統就不會傳回結果。
Room.numberOfChildren 整數 yes (如果 > 0) 客房的兒童房客計數。所有飯店的必要項目。與 childAges 結合使用以判定空房情況和房價。
Room.childAges 逗號分隔的
清單或整數陣列
yes (如果兒童計數 > 0) 以 XML 和 REST 適用的逗號分隔清單方式以及 SOAP 適用的 childAges 個別值陣列方式傳送客房內兒童的個別年齡。

如果註明了兒童房客,請一律向旅客要求提供此資訊。如果訂房前沒有提供兒童的年齡,則可能會導致非預期的加床費用。
includeDetails 布林值 no

傳回每個房間種類的取消規定、床型和吸菸偏好 (若有提供吸菸房)。

只能與 minorRev=22 以上共同傳回額外元素。

includeHotelFeeBreakdown 布林值 no 傳回元件 HotelFeeBreakdown,包含 HotelFees 陣列更詳細的回應結構,包括套用每種費用的頻率和費用的套用方式。有 minorRev=24 以上參數時即可使用。
REST 的房間格式
REST 格式會將先前元素的值壓縮成逗號分隔清單。若要宣告客房及其入住人數,請使用以下格式:

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


例如,若要宣告一間客房有一名成人和兩名年齡分別是 5 歲和 12 歲的兒童,您就必須傳送 &room1=1,5,12。不需個別宣告兒童人數,系統會假設每個年齡值屬於一名兒童。


主要搜尋方式
系統共提供五種主要方式,可限制要求所傳回的飯店選擇,這些方式不依特定順序列於下方。
其中有四種方式是利用定義的地點限制選擇,剩下的一種則是允許透過特定的 hotelIds 清單傳回明確的飯店組合。
您一次只能選擇使用其中一種方式。


方式 1:城市/州/省/國家/地區搜尋
名稱 搜尋方式的必要項目 說明
city 字串 yes
在城市內搜尋。只能使用完整的城市名稱。
stateProvinceCode 字串 yes (如為US、
CA、AU)
包含指定城市的州/省代碼 (兩個字元)。如為澳洲,則必須使用下方提供的特殊代碼。

參考資料:
美國代碼
加拿大省份 / 領土代碼
澳洲省份 / 領土代碼
  • 澳洲首都 - AC
  • 新南威爾斯 - NW
  • 北領地 - NO
  • 昆士蘭 - QL
  • 南澳洲 - SA
  • 塔斯馬尼亞 - TS
  • 維多利亞 - VC
  • 西澳洲 - WT
countryCode 字串 yes
包含指定城市的國家/地區的兩字元 ISO-3166 代碼。只能使用如 ISO-3166 解碼表中「官方指派」的國家/地區代碼。


方式 2:使用任意文字目的地字串
名稱 搜尋方式的必要項目 說明
destinationString 字串 yes 包含至少一個城市名稱的字串。您也可以傳送州/省、城市和國家、城市/州/省/國家等。

接受旅客直接輸入時,此類參數為最好的選擇。

模糊輸入內容將傳回錯誤訊息,並且會包含可能要查詢的位置,可能的話也會加入其 destinationId (請參閱下方)。


方式 3:使用 destinationId
名稱 搜尋方式的必要項目 說明
destinationId 字串 yes 特定城市、都會區或地標的唯一十六進位鍵值。

透過地理指令要求,或自 destinationString 空房情況要求傳回的多個位置錯誤取得此值。

可透過地標的地理函數要求取得地標值 (例如建築、主要社區、火車站等)。



方式 4:使用 hotelIds 清單
名稱 搜尋方式的必要項目 說明
hotelIdList 長整數的逗號分隔
清單
yes 以固定飯店組合查看空房情況。使用以逗號分隔的清單傳送所需的 hotelId 值。

如果沒有指定排序順序,則會由 EAN 已最佳化的預設演算法來排序飯店。使用排序選項 NO_SORT 以保持清單的順序。

系統會使用逗號分隔的清單傳回在回應標頭 Invalid-Hotel-Ids 下任何無效的 hotelId 值。

使用較長清單時請注意,在多種要求中與較短清單相較之下,回傳時間可能延長許多。透過 REST 傳送較長清單時,請使用 POST,不要使用 GET。


方式 5:在地理區域內搜尋
注意:您也可以使用此方式搭配機場座標檔案
搜尋機場
名稱 搜尋方式的必要項目 說明
latitude 字串 yes 搜尋的出發地緯度座標格式必須為 DDD.MMmmm。
longitude 字串 yes 搜尋的出發地經度座標格式必須為 DDD.MMmmm。
searchRadius 整數 no 定義圓形搜尋區域的半徑,並利用系統提供的 latitudelongitude 值定義搜尋區域的中心。
最短 1 MI2 KM,最長 50 MI80 KM。若值超過長度上限,該值會在結果傳回前自動縮短。
預設值�� 20 MI
searchRadiusUnit 字串 no 針對搜尋半徑設定距離單位。傳送
MIKM。如果未填寫或未提供,則使用預設值 MI
sort 字串 no 如果要以距出發點距離長度排序搜尋結果,您必須傳送 PROXIMITY 的值。否則,系統將套用預設排序順序,顯示所有在搜尋半徑內的飯店。

請參閱下一節了解此元素所有可用值的完整定義。

不套用到無日期清單要求的結果。
其他搜尋方式
將這些搜尋方式作為次要選項提供給旅客,讓他們透過鄰近地址或特定飯店進行搜尋。


名稱 需有其他參數 說明
address 字串 yes 以當地街道地址搜尋鄰近地區。回應將包含每家飯店與提供地址之間的距離。

即便是已輸入特定飯店地址,該飯店如果排名不是第一,在預設的排序順序中也不會優先顯示。

必須定義 citycountryCode 參數。
postalCode 字串 yes 可選擇加入地址的郵遞區號。

必須定義 citycountryCode 參數。
propertyName 字串 yes 搜尋空房情況時使用的名稱。值可以是完整名稱或部分名稱,例如「假期」或「最佳」

回應將包含飯店名稱有此參數值的所有飯店。

如果已傳送特定飯店名稱,當提供的住宿日期沒有空房時,系統就可能會傳回空白的回應。

必須定義 citycountryCode 參數。

篩選方式
這些方式會透過設施、房價、星級評等和其他一般訂房條件篩選搜尋結果。這些都可於初始搜尋前與主要方式一起提供,或者可於動態更新現有搜尋結果頁面時使用。這些方式也可用於內部,限制旅客可查看的搜尋結果,例如將顯示的飯店限制為只顯示特定星級以上的飯店。

名稱 必要 說明
includeSurrounding 布林值 no false 傳送時,此參數將排除搜尋參數中定義之區域範圍以外的飯店。
如果要避免其他鄰近城市或偏遠地區的飯店顯示在您的結果中,請使用此方式。
propertyCategory 整數或整數的逗號分隔清單 no

依照飯店類別篩選搜尋結果。傳送單一值或值的清單以傳回飯店類別組合。

注意:
這些值不等同於我們靜態資料庫檔案中的分類,也不等同於其他任何 Expedia 提供的資料。

值:
1:飯店
2:套房
3:渡假區
4:假期租賃 / 渡假公寓
5:民宿
6:全包式

amenities 整數或整數的逗號分隔清單 no

此元素已不推薦使用。 此元素的值不符合 Expedia 的設施,也不符合我們自己設施的資料庫檔案。

您可以改為在透過以下兩種方式中的其中一種收到回應後,套用設施篩選條件:

1. 從結果中的 amenityMask 值解碼位元遮罩,以取得每家飯店獨立的設施。您可以使用此範例公用程式來檢查您的取消遮罩編碼:http://sandbox.ean.so/amenity/amenity.php

2. 本機下載 AttributeList 資料庫檔案,然後使用此檔案來篩選要求位置及有已篩選設施的飯店。

maxStarRating 浮點數 no 依照最高星級評等篩選搜尋結果。
有效值為 1.0 - 5.0 ,每次增加 0.5
minStarRating 浮點數 no 依照最低星級評等篩選搜尋結果。
有效值為 1.0 - 5.0 ,每次增加 0.5
minRate 浮點數 no 依照飯店提供的房價等於或大於提供的值篩選搜尋結果。
averageRate 回應值進行搜尋 (住宿日期期間的平均每晚房價)。只在空房情況搜尋中有效。
maxRate 浮點數 no 依照飯店提供的房價等於或小於提供的值篩選搜尋結果。
averageRate 回應值進行搜尋 (住宿日期期間的平均每晚房價)。只在空房情況搜尋中有效。
numberOfBedRooms 整數 no 此參數僅限假期租賃 / 渡假公寓有效。指定要求的客房數目 - 最高值為 4。
maxRatePlanCount 整數 no 定義要與每家飯店一同傳回的房型數目。

如果設定較高的值,視個別飯店的空房情況而定,系統將在回應中嘗試傳回每家飯店的對應房型數目。

預設設定為 1;如果使用預設設定,系統就只會傳回每家飯店的第一種房型。根據 Expedia 的使用者測試結果我們發現,使用此值可提供最高的訂房率,因此建議不要改變此值,這樣在客房選擇階段期間才能有空間可以顯示其他客房。

排序選項
建議您傳送初始搜尋,而不指定排序順序,因為預設的排序順序已經過計算,可將旅客最有可能選擇,及高訂房率的飯店顯示在頂端。您要做的是允許旅客在系統傳回初始搜尋結果清單後選擇不同的排序順序。
名稱 必要 說明
sort 字串 no 系統傳回飯店排序的偏好選擇。

值:
BUDGET

依獲利能力排序,以優先顯示每個市場中經濟實惠的飯店。這會根據訪問訂房率,將最具獲利能力的經濟實惠飯店放置於頂端。

CHAMPION

依獲利能力排序,以優先顯示每個市場內中間價格的飯店。這會根據訪問訂房率,將最具獲利能力的中間價格飯店放置於頂端。

PREMIUM

依獲利能力排序,以優先顯示每個市場內價格頂級的飯店。這會根據訪問訂房率,將最具獲利能力的頂級價格飯店放置於頂端。

HIGH_MARGIN

根據 CHAMPION 排序時,HIGH_MARGIN 排序功能會更進一步,優先顯示佣金比例最大的飯店,確保將高訂房率與佣金較高的飯店顯示在靠近頂端處。HIGH_MARGIN 排序功能會優先針對合作夥伴的佣金比例來考量飯店層級的額外成本。

NO_SORT 只能搭配 hotelIdList使用。在要求中完全依照所列順序傳回飯店。
CITY_VALUE 預設排序順序 - 如果 sort 完全省略,則以相同的順序傳回飯店。指定城市中的飯店排序會高於鄰近地區的飯店。
OVERALL_VALUE 將旅客最有可能選擇、訂房率最高的飯店刊登在最頂端。
PROMO 將有促銷價或有額外設施/服務的飯店刊登在沒有促銷活動的飯店之上。
PRICE 以每晚房價由低至高的方式排序飯店。由於套用至由 API 存取飯店清單的商務 / 行銷辦公室演算法的緣故,此排序方式目前尚不完美。在系統收到搜尋結果之後,您自己的代碼範圍內才能有最精確的房價排序方式。
PRICE_REVERSE 以每晚房價由高至低的方式排序飯店。可能會出現如上詳細說明的不完美排序方式。
PRICE_AVERAGE 以平均每晚房價由低至高的方式排序飯店。可能會出現如上詳細說明的不完美排序方式。
QUALITY 以飯店星級評等由高至低的方式排序。
QUALITY_REVERSE 以飯店星級評等由低至高的方式排序。
ALPHA 以英文字母順序排序飯店
PROXIMITY 根據透過 latitudelongitude 參數定義的出發點鄰近距離排序。
POSTAL_CODE 按照郵遞區號英文字母順序由低至高排序。
TRIP_ADVISOR 如果您已核准 TripAdvisor 整合方式,此值將以從高至低房客評等的方式排序結果。
其他資料要求

使用此參數即可將回應限制為特定動態資料類型。通常會與我們的 飯店資料庫 檔案結合使用,做為通常由 API 提供的靜態資訊來源。結合離線資料庫使用此參數的整合方式的回應速度,將比只仰賴 API 回應的方式提高許多。

名稱 必要 說明
options 字串或字串的逗號分隔
清單
no 定義傳回的有限資料類型。以逗號分隔清單方式傳送單一值或組合。

值:
DEFAULT 傳回下列全部三種資料類型。回應將與 options 完全省略時相同。
HOTEL_SUMMARY

將動態飯店資訊與少量辨識靜態資訊 (飯店名稱和地址、地點說明、hotelId 等) 一起傳回。
不包含動態房價資訊。最不可能有空房的回應。

ROOM_RATE_DETAILS 透過 hotelIdroomDescription傳回動態房價資訊及最少靜態資訊。
DEEP_LINKS 只與基本靜態資訊一起傳回範本的深度連結。
更多飯店分頁

如果初始回應傳回 moreResultsAvailabletrue,搜尋結果的下一頁就可透過以下程序要求。

若要顯示更多的搜尋結果分頁,在接下來的空房情況要求中可能只會傳送 supplierTypecacheLocationcacheKey。必須省略所有其他非常用參數。

您必須在要求中包含 supplierType=E 值。如果不包含這個值,當清單耗盡時,moreResultsAvailable 可能會錯誤地傳回 true

最後,如果出現表示 "cacheLocation cannot be found" 回應的錯誤,就表示快取已經過期,且必須再次要求原始搜尋。快取回應通常會保留 15-30 分鐘。

請參閱「更多結果分頁」以查看範例:


名稱 類型 於方式中為必要 說明
supplierType 字串 yes 必須以值 E 傳送,才能讓分頁系統正確地表示其他結果。
cacheKey 字串 yes 要求的特定快取回應使用的索引碼。在過去飯店清單回應中使用傳回的值。
cacheLocation 字串 yes 定義要求快取的 EAN 伺服器位置。在過去飯店清單回應中使用傳回的值。
飯店清單回應
傳回位於指定地點,且針對提供的房客人數和住宿日期有空房的飯店。

如果透過省略 arrivalDatedepartureDateRoomGroup 要求"無日期清單",回應就會包含所有指定地點內的刊登中飯店,而且不會包含任何特定的空房資訊。

回應內容
父項目: HotelListResponse


名稱 說明
moreResultsAvailable 布林值 表示是否有多筆飯店搜尋結果可供顯示。

如果為 true,則系統可透過分頁程序取得更多搜尋結果。
numberOfRoomsRequested 整數 確認原始要求的客房數目 ( Room 節點的數目)
cacheKey 字串 目前傳回的回應快取索引碼。請在您的下一個分頁要求中使用此值。
cacheLocation 字串 針對目前傳回的回應定義快取的 EAN 伺服器位置。請在您的下一個分頁要求中使用此值。
HotelList HotelSummary 陣列適用的容器應用程式

包含可定義回應中個別飯店數目的屬性 size,以及可指出指定位置中已刊登 (不一定有空房) 飯店總數的 activePropertyCount

HotelList.HotelSummary 物件 個別飯店的陣列。每筆飯店搜尋結果的資訊都會包含在其各自��� HotelSummary 節點之中。
包含可指出每家飯店的原始數字排序的屬性 order,以協助自動態重新排序還原 (順序自 0 開始,而不是 1)。
HotelSummary.hotelId 長整數 飯店的 ID。此相同 ID 將於後續任何客房或訂房要求中使用。
HotelSummary.name 字串 飯店名稱
HotelSummary.address1 字串 飯店街道地址
HotelSummary.city 字串 飯店城市
HotelSummary.stateProvinceCode 字串 包含指定城市的州/省代碼 (兩個字元)。只傳回 US、CA 和 AU 國家節點。

參考資料:
美國代碼
加拿大省份 / 領土代碼
澳洲省份 / 領土代碼
HotelSummary.countryCode 字串 飯店所在國家的 ISO-3166 代碼 (兩個字元)
HotelSummary.postalCode 字串 飯店郵遞區號
HotelSummary.airportCode 字串 與飯店關聯的機場代碼
HotelSummary.supplierType 字串 飯店的合約飯店。此相同的合約飯店將用於處理所有收到的訂房。

值:
E:Expedia Collect
HotelSummary.propertyCategory 字串 傳回飯店類別。

值:
1:飯店
2:套房
3:渡假區
4:假期租賃 / 渡假公寓
5:民宿
6:全包式
HotelSummary.hotelRating 浮點數 飯店星級 (0-5)。值如果為 0.0 或空白,則表示皆沒有空房。
HotelSummary.amenityMask 長整數 查看飯店設施遮罩的詳細資料
HotelSummary.shortDescription 字串 由飯店輸入的簡短說明文字。如果輸入的內容超過 200 個字元,內容會被截斷。
如要獲得更好的績效,請在此值的末端加入刪節號 (...),並將值設定為連結至飯店的空房情況頁面。
HotelSummary.locationDescription 字串 如飯店輸入的一般位置,例如「101 大樓附近」
HotelSummary.lowRate 字串 在最近查詢中由飯店傳回的最低房價。此為統計數字,不一定是目前空房的房價。
HotelSummary.highRate 字串 在最近查詢中由飯店傳回的最高房價。此為統計數字,不一定是目前空房的房價。
HotelSummary.rateCurrencyCode 字串 傳回的高房價或低房價貨幣代碼。
HotelSummary.latitude 浮點數 飯店的緯度座標。
HotelSummary.longitude 浮點數 飯店的經度座標。
HotelSummary.proximityDistance 浮點數 飯店與原指定出發地座標之間的距離 (如果使用該搜尋方式)。
HotelSummary.proximityUnit 字串 proximityDistance 提供的距離單位。MIKM
HotelSummary.hotelInDestination 布林值 表示飯店是否位於原指定城市之中,或是位於鄰近地區,也就是主要郊區或其他鄰近城市。

不在目的地範圍內的飯店會依照與原始地區之間的距離分組,例如 10 英哩以內、20 英哩以內等。
HotelSummary.thumbNailUrl 字串 飯店的縮圖圖片網址路徑 (如果提供)。

系統不會傳回完整的網址 - 請以 http://images.travelnow.com,或使用 origin-images.travelnow.com 設定 CNAME,以您自己的子網域做為目的地附加此值。系統支援使用有 SSL 的 HTTPS。
字串 與您範本上對應的飯店頁面做深度連結;此連結會於您建立 混合式網站時使用。

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

此類連結也可能會以 CNAME 遮罩
HotelSummary.RoomRateDetailsList RoomRate
Details
陣列適用的容器應用程式
限容器應用程式,沒有屬性。保留所有客房限定元件資料
RoomRateDetailsList.RoomRateDetails 陣列 包含飯店傳回的第一筆客房詳細資料。如果 maxRatePlanCount 值已送出,則針對每間額外的客房傳回額外的節點 >1
RoomRateDetails.roomTypeCode 字串 客房的房型代碼。
RoomRateDetails.rateCode 字串 顯示的房價代碼。
RoomRateDetails.maxRoomOccupancy 整數 傳回的客房所允許的房客人數上限。
RoomRateDetails.quotedRoomOccupancy 整數 確認房價計算使用的實際入住人數。
RoomRateDetails.minGuestAge 整數 客房內允許的房客最小年齡
RoomRateDetails.roomDescription 字串 與傳回的 roomTypeCode 相關聯的客房說明
RoomRateDetails.promoId 字串 傳回的促銷折扣 ID (如果有的話)。此值在 REST 底下會以整數傳回。
RoomRateDetails.promoDescription 字串 傳回的促銷說明 (如果有的話)。系統將傳回最多 255 個字元。
RoomRateDetails.promoDetailText 字串 傳回的促銷額外詳細資料 (如果有的話)。
RoomRateDetails.currentAllotment 整數 飯店剩餘的可訂房客房數目。使用此值,即可建立緊急訊息的規則,提醒使用者在旺季期間或熱門飯店空房數目不多。

如果傳回的值為 0,並不表示飯店沒有客房。這只是代表不符合計算值所需的規則 - 此值並不表示絕對的空房情況。
RoomRateDetails.propertyAvailable 布林值 僅供內部保留房參考。
|只有可供預訂的保留房會於收到標準要求時傳回。
RoomRateDetails.propertyRestricted 布林值 僅供內部保留房參考。請參閱取消政策以深入瞭解任何特定限制。
RoomRateDetails.expediaPropertyId 字串 Expedia 的飯店 ID。使用此值即可在與 Expedia 交互參照時對應至 hotelId
RoomRateDetails.BedTypes 陣列 個別客房的床型選擇。可在訂房時傳回單人床型或包含可供選擇的床型。檢閱床型詳細資料
minorRev=22 以上參數時即可使用。只有在 includeDetails=true 已於要求中傳送時才會傳回。
RoomRateDetails.smokingPreferences 字串的逗號分隔清單 可供選擇的客房吸菸偏好 (如果有的話)。

值:
NS:非吸菸
S:吸菸
E:皆無

minorRev=22 以上參數時即可使用。只有在 includeDetails=true 已於要求中傳送時才會傳回。
RoomRateDetails.nonRefundable 布林值 明確表示訂房後是否可以退款。也應於傳回的取消政策中說明。
此地點只在 minorRev=1019的情況下才會傳回。
RoomRateDetails.ValueAdds ValueAdd 適用的容器應用程式 包含提供的客房與房價 ValueAdd 元素陣列 (如果可用)。有 size 屬性以表示傳回的新增值數。
ValueAdds.ValueAdd 陣列

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

若值為 minorRev=2829,則 id 屬性的數值不會傳回,只會提供 description

若為 minorRev=30,則數值 id 屬性會連同等於 26 以下時傳回值的另一組值一起傳回。這 2 組值都在我們的額外設施/服務參照頁面上。

RoomRateDetails.RateInfos RateInfo 適用的容器應用程式 包含 RateInfo 元素的陣列,可針對個別客房提供詳細的房價資訊。

如果您使用舊版整合方式,且執行 minorRev=6 或較舊參數,RateInfo 將不會與 RateInfos 容器應用程式一起傳回。

RateInfos.RateInfo 物件 包含多種不同物件和個別值以內的單一客房所有房價資訊。

屬性:
priceBreakdown布林值 表示是否包含完整房價分類,包括稅金和要支付的總費用。
promo 布林值 表示房價是否為促銷價格。
rateChange 布林值 表示住宿期間是否至少有一晚的房價不同。
RateInfo.promoId 字串 傳回的促銷折扣 ID (如果有的話)。以 RoomRateDetails 傳回,低於 minorRev=20
RateInfo.promoDescription 字串 傳回的促銷說明 (如果有的話)。系統將傳回最多 255 個字元。以 RoomRateDetails 傳回,低於 minorRev=20
RateInfo.promoDetailText 字串 傳回的促銷額外詳細資料 (如果有的話)。以 RoomRateDetails 傳回,低於 minorRev=20
RateInfo.currentAllotment 整數 飯店剩餘的可訂房客房數目。使用此值,即可建立緊急訊息的規則,提醒使用者在旺季期間或熱門飯店空房數目不多。

如果傳回的值為 0,並不表示飯店沒有客房。這只是代表不符合計算值所需的規則 - 此值並不表示絕對的空房情況。
RoomRateDetails 傳回,低於 minorRev=20
RateInfo.cancellationPolicy 字串 此客房的飯店取消政策。必須在個別客房頁面以及所有訂房及訂房確認頁面上顯示。
minorRev=22 以上參數時即可使用。只有在 includeDetails=true 已於要求中傳送時才會傳回。
RateInfo.CancelPolicyInfoList Cancel
PolicyInfo
適用的容器應用程式
取消政策的特定詳細資料,通常是決定懲罰期和取消所產生的懲罰時間。
minorRev=22 以上參數時即可使用。只有在 includeDetails=true 已於要求中傳送時才會傳回。
RateInfo.rateType 字串 表示傳回的房價是否已透過 EAN 於線上付款或之後將於飯店付款。與線上付款的空房情況 MerchantStandard 值一起傳回,或針對之後於飯店付款完全不傳回。
minorRev=18 以上參數時即可使用。以低於 minorRev=20 的回應本文傳回
RateInfo.nonRefundable 布林值 明確表示訂房後是否可以退款。也應於傳回的取消政策中說明。
只傳回空房情況及 minorRev=20 以上參數。以 RoomRateDetails 傳回,低於 minorRev=20
RateInfo.promoType 字串 表示傳回的任何促銷是否為行動版特定或標準促銷傳回行動版促銷的 Mobile 和所有其他的 Standard
如果要傳回行動版促銷,您必須透過合適的 customerUserAgent 字串辨識您的行動網站或 App。
minorRev=21 以上參數時即可使用。您必須升級至 minorRev=20 的結構描述,才能使用此元素。
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 字串 套用促銷 (如果有的話) 前的每晚房價。
ChargeableRateInfo.Surcharges 陣列 Surcharge 陣列適用的容器應用程式。此陣列會逐項列出組成 surchargeTotal傳回值的個別附加費。有 size 屬性以表示陣列中的節點數目。
Surcharges.Surcharge 詳細列出單一附加費的金額與類型。僅包含屬性。

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

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


注意:根據紐約州法律規定,必須顯示 SalesTaxHotelOccupancyTax 附加費類型。確保您期望和擷取這些值,以在最終房價分類中顯示為 "飯店住宿與銷售稅" 。
RateInfo.rateType 字串 表示傳回的房價是否已透過 EAN 於線上付款或之後將於飯店付款。與線上付款的空房情況 MerchantStandard 值一起傳回,或針對之後於飯店付款完全不傳回。
minorRev=18 以上參數時即可使用。
RateInfo.HotelFees 陣列

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

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

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

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

請注意,兒童元素 HotelFeeBreakdown 必須為特別要求,且必須高於 minorRev=24

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

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

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

HotelFee.HotelFeeBreakdown 只有在 includeHotelFeeBreakdown 已於要求中傳送時才會傳回。詳述在 HotelFee 中提供的費用將如何進行套用,以及套用的頻率。

注意:所有 HotelFee amount 值為 總計。請勿以此處提供的任何 frequency 相乘。

如果需要,您可以依照 frequency 指示除以 amount,以取得每晚/每天/每週的費用。

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

屬性:
unit 字串 費用分配的方式。可能的值:
  • Per Person
  • Per Room
  • Per accommodation
  • Per house
  • Per apartment
  • Per adult
frequency 字串 費用的頻率。可能的值:
  • Per Night
  • Per Day
  • Per Stay
  • Per week
ConvertedRateInfo 物件 轉換成旅客要求的貨幣價格資訊。僅在飯店或旅客市場地區無法以要求的貨幣計費時傳回。包含與 ChargeableRateInfo 相同的屬性。
RoomGroup 物件 確認相同的 RoomGroup 物件內容因適用於提供的房價,所以已於要求中傳送。

minorRev=29 以上時,請包含每間房每晚房價的詳細資料。
RoomGroup.Room 陣列 確認原始要求中所提供之 numberOfAdultsnumberOfChildrenchildAges 的客房值。
Room.rateKey 字串 房價的索引碼和參數會決定房價。

每次變更搜尋參數時 (房客計數變更、改變住宿日期、增加兒童人數等),就必須傳送新要求才能取得此參數的新值。
Room.ChargeableNightlyRates 陣列 客房 NightlyRate 陣列的容器。依住宿期間的順序,傳回個別客房的特定房價。

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

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

表示促銷價格、基本價格及套用促銷後的價格 (如果適用)。僅包含屬性。

minorRev=29 及以上時傳回。

屬性:
promo 布林值 表示此晚住宿房價是否有套用促銷價格。
rate 字串 套用促銷 (如果有的話) 後的每晚房價。
baseRate 字串 套用促銷 (如果有的話) 前的每晚房價。
ChargeableNightlyRates.
ConvertedNightlyRates
物件 轉換成旅客要求的貨幣價格資訊。僅在飯店或旅客市場地區無法以要求的貨幣計費時傳回。包含與 ChargeableNightyRates 相同的屬性。 minorRev=29 以上時傳回。
CachedSupplierResponse


CachedSupplierResponse 元素會於提供快取的飯店清單回應時傳回。

用於 CachedSupplierResponse 元素的屬性:
名稱 說明
cachedSupplierResponse 物件 包含快取資料相關資訊,限內部使用。只會與快取回應一起傳回。
cacheEntryHitNum 整數 內部
cacheEntryMissNum 整數 內部
cacheEntryExpiredNum 整數 內部
cacheRetrievalTime 長整數 快取擷取時間。
supplierRequestNum 整數 從合約飯店要求的搜尋結果數目
supplierResponseNum 整數 從合約飯店傳回的搜尋結果數目
supplierResponseTime 長整數 合約飯店傳回搜尋結果的速度
candidatePrepTime 長整數 決定或準備物業要求清單的時間。
tpidUsed 整數 根據貨幣和地區設定的內部識別碼。
matchedCurrency 布林值 從快取傳回相符或轉換 (推算) 的資料。
matchedLocale 布林值 從快取傳回相符或編譯的資料。
extrapolatedCurrency 布林值 從快取傳回相符或轉換 (推算) 的資料。(搜尋結果會以英文和美金自合約飯店快取而得,然後在要求時轉換成要求的貨幣和語言)
extrapolatedLocale 布林值 從快取傳回相符或編譯的資料。