購物

「購物 API」可讓您存取全球超過 700,000 處住宿的即時房價和供應情況。

簡介

「購物 API」會針對指定旅宿傳回所有房型的房價和供應情況 (每項請求最多 250 家旅宿)。回應包含諸如促銷、房價是否為可退款、是否有取消費用和完整價格明細等房價詳情，以符合您市場的價格顯示規定。

包含多個 occupancy 參數執行個體，即可要求相同房型的多個房間。每回傳送要求時，若同一客房有多次要求預訂，則只會回傳一組該標準房價。一次最多可要求預訂 8 間客房。若需要一次預訂 8 間以上客房，請向您的客戶經理洽詢我們的團體訂房合作相關事宜。

價格顯示變化

由於《加州價格顯示條例》(伯爾曼法) 將於 2024 年 7 月 1 日起生效，請注意即將進行的變更。

法律條文的內容為何？

法律禁止廣告、展示或提供不包含短期住宿所需的所有費用或收費的客房房價，但政府對住宿徵收的稅費除外。該法案還要求短期住宿地點在旅客預訂住宿前，將所有稅費和政府對住宿徵收的費用包含在旅客要支付的總價中。「短期住宿」指的是飯店、汽車旅館、民宿旅館或其他臨時住宿，其中包括短租，或連續出租給旅客 30 晚以內的住宅。如需了解更多資訊，請參閱加州議會法案 537 號。

Expedia Group 正在變更 API，以便讓 API 合作夥伴能夠透過多種方式顯示價格。但最後，使用 Expedia Group API 的每個合作夥伴，都有責任確保自己顯示 Expedia 智遊網旅遊資訊和價格的方式均符合法律規範。

Expedia 智遊網正在加強 Rapid API，藉此新增一個含有總價的新欄位 property_inclusive，而總價包括基本房價，以及整個住宿期間，Expedia 智遊網和飯店收取的所有費用和稅金。新欄位也會含有此總價的刪除線版本 property_inclusive_strikethrough。除了新旅宿的全包顯示欄位外，我們也正在 API 回應中重新調整稅費的細分方式。Expedia 智遊網收取的所有費用都將納入 nightly 和 stay``property_fee 價格明細類型中，而所有 Expedia 智遊網收取的稅費則會納入 nightly 和 stay tax_and_service_fee 價格明細類型。

由於這是針對所有旅宿進行的全球性變更，因此發布日期已重新安排為 2024 年 5 月 29 日，以確保變更順利，且旅宿了解這些變更。如對變更有任何疑問，請聯絡您的客戶經理。

會員點數

商務旅客預訂參與 Expedia 智遊網企業房價計畫且提供會員計畫的飯店，即可在住宿期間獲得飯店會員點數。合作夥伴可利用購物回應的設施服務節點，在擷取旅客的會員資訊前，確認並顯示會員可累積資格。

合作夥伴也可在購物 API 要求中使用 loyalty 值篩選條件，僅搜尋符合會員計畫的企業房價。

**備註：**只有在飯店已有會員計畫的情況下，企業房價才可累積會員點數。

範例：

可累積會員點數的飯店企業房價，會在搜尋回應的 amenities 節點底下出現以下參數

{
  "id": "2096",
  "name": "Eligible for hotel loyalty points"
}

佣金獎勵

作為 Rapid API 合作夥伴，您可以獲得額外的佣金獎勵，在指定的預訂和住宿日期期間為旅宿提供更高的利潤。要找出含有效佣金獎勵的旅宿，只需在 Rapid 購物 API 要求中使用 include 參數的 rooms.rates.marketing_fee_incentives 值即可。針對全部或部分所要求住宿期間的佣金獎勵費率，購物 API 回應中的 marketing_fee_incentives 物件將內含相關的其他詳細資訊，包括獎勵來源和受影響的住宿期間。然後，您可以在庫存排序和選擇過程中考慮此欄位和現有的 marketing_fee 欄位；該欄位是行銷費用的估計值，其中包括所有可用的獎勵措施。

範例

旅宿 19248 為 12 月份的住宿提供更高的利潤。您向旅宿 19248 提出購物 API 要求，以在 12 月 22 日至 1 月 5 日期間入住。在購物 API 回應的 marketing_fee_incentives 物件中，您可以看到有一項獎勵措施適用於所要求住宿期間的其中一段時間；也就是從 12 月 22 日到 12 月 31 日，即 14 晚住宿中的 10 晚。

要求範例

curl -X GET "https://test.ean.com/v3/properties/availability\
?checkin=2023-12-22\
&checkout=2024-01-05\
&currency=USD\
&country_code=US\
&language=en-US\
&occupancy=2\
&property_id=19248\
&rate_plan_count=1\
&sales_channel=website\
&sales_environment=hotel_only\
&include=rooms.rates.marketing_fee_incentives\
&travel_purpose=leisure" \
 -H "accept: application/json, application/json"\
 -H "accept-encoding: gzip"\
 -H "authorization: EAN apikey=abcd1234,signature=090a77e7ddd7779980231,timestamp=1697664047"\
 -H "user-agent: TravelNow/3.30.112"

回應範例

[
  {
    "property_id": "19248",
    "rooms": [
      {
        "id": "123abc",
        "room_name": "Fancy Queen Room",
        "rates": [
          {
            "id": "333abc",
            ...
            "marketing_fee_incentives": [
              {
                "source": "property",
                "start": "2023-12-22",
                "end": "2023-12-31"
              }
            ],
            "occupancy_pricing": {
              "2": {
                "nightly": [ ... ],
                "stay": [ ... ],
                "totals": {
                  "inclusive": { ... },
                  "exclusive": { ... },
                  "inclusive_strikethrough": { ... },
                  "strikethrough": { ... },
                  "marketing_fee": {
                    "billable_currency": {
                      "value": "276.36",
                      "currency": "USD"
                    },
                    "request_currency": {
                      "value": "276.36",
                      "currency": "USD"
                    }
                  },
                  "gross_profit": { ... },
                  "minimum_selling_price": { ... },
                  "property_fees": { ... }
                },
                "fees": { ... }
              }
            }
          }
        ]
      }
    ]
  }
]

旅遊目的

travel_purpose 參數允許您將旅行指定為商務旅行或休閒旅行。從 2024 年 4 月 1 日開始，有資格以商務房價購物的合作夥伴，將需要在購物要求中使用 travel_purpose=business，才能在購物回應中接收商務房價。如果要求中未提供 travel_purpose 參數，將假設其為休閒旅行，並且不會回傳商務房價。

範例

要指定旅客的旅遊目的為商務性質，只需在供應情況 API 要求中加入 24 個字元，非常簡單。

&travel_purpose=business

刪除線價格

strikethrough 欄位提供適用任何飯店資助折扣之前的不含稅總價。此欄位應在美國等地區使用，這些地區通常在搜尋結果中顯示不含稅金和其他費用的基本價格。
inclusive_strikethrough 欄位顯示折扣前的總價，包括稅金和其他費用。此欄位旨在讓您更清楚地顯示提供全包價格 (即基本價格、稅金和其他費用) 的區域中適用的折扣。該欄位回傳以計費貨幣和要求貨幣表示的值。

範例

[
  {
    "property_id": "19248",
    "rooms": [
      {
        "id": "123abc",
        "room_name": "Fancy Queen Room",
        "rates": [
          {
            "id": "333abc",
            ...
            "occupancy_pricing": {
              "2": {
                "nightly": [ ... ],
                "stay": [ ... ],
                "totals": {
                  "inclusive": { ... },
                  "exclusive": { ... },
                  "inclusive_strikethrough": {
                    "billable_currency": {
                      "value": "726.63",
                      "currency": "CAD"
                    },
                    "request_currency": {
                      "value": "549.60",
                      "currency": "USD"
                    }
                  },
                  "strikethrough": {
                    "billable_currency": {
                      "value": "650.00",
                      "currency": "CAD"
                    },
                    "request_currency": {
                      "value": "491.64",
                      "currency": "USD"
                    }
                  },
                  "marketing_fee": { ... },
                  "gross_profit": { ... },
                  "minimum_selling_price": { ... },
                  "property_fees": { ... }
                },
                "fees": { ... }
              }
            }
          }
        ]
      }
    ]
  }
]

促銷及折扣價格顯示

顯示根據促銷活動提供的折扣優惠金額，或是供應情況與價格檢查 API 所提供的原價與優惠價比較金額時，特定銷售點會要求提供標準房價的詳細資訊 (也就是用來計算折扣的價格基礎)。有關用詞使用規定，請參閱下方說明。

**歐盟：**請提供標準房價的清楚詳細資訊 (例如：「此為根據您的搜尋，旅宿所提供的標準房價」)。

**義大利：**請使用以下文字敘述：「Questo prezzo è basato sulla tariffa generalmente applicabile fornita dalla struttura per questa camera e per queste date.」

無法提供的原因

unavailable_reason 功能可讓您查詢旅宿在特定住宿條件下 (住宿日期和入住人數) 完全無法提供入住的原因，並提供可採取的行動資訊。購物時，必須包含可選的要求參數 include=unavailable_reason，才能在回應中接收此資訊。然而，並非所有無法提供的旅宿都有不可預訂的可訴理由。這些旅宿不會在回應中回傳。

「購物」回應可能包括可提供和無法提供的旅宿混合。無法提供的旅宿將包括 property_id、score 和 unavailable_reason 部分，其中包含 code 和對該旅宿無法提供的簡短說明 (以英文提供)，以及 data 以獲得可在要求中調整的其他資訊來提供旅宿/客房/房價計畫。例如，如果 unavailable_reason code 為 adults_exceed_threshold，則 data 中的 2 表示該客房/房價允許的最大人數為 2 名成人，任何大於 2 的入住人數都會回傳錯誤。

**注意：**旅宿可以套用多個限制，但只會回傳一個 unavailable_reason。

範例

[
  {
    "property_id": "824739",
    "score": 12345,
    "unavailable_reason": {
      "code": "adults_exceed_threshold",
      "data": "2"
    }
  }
]

請參閱此處以取得回傳代碼的完整清單。

設施服務篩選條件

或者，您可以使用 amenity_category 要求參數以及一項或多項特定設施服務來篩選在 Rapid 購物回應中回傳的旅宿。

請參閱此處「內容參考清單」所列的「設施服務類別」一節，了解可用於篩選回應的設施服務清單。

範例

單一設施服務篩選條件：

&amenity_category=free_breakfast

多項設施服務篩選條件：

&amenity_category=free_breakfast&amenity_category=free_airport_transfer&amenity_category=casino

language 僅使用兩位數的語言與國家/地區代碼連字號配對。整合任何代碼前，請檢查我們的支援語言。
此兩位數 country 代碼會設定旅客的銷售點，但不會影響已本地化的內容。
不會傳回任何靜態資料 (名稱、星級評等、地理資訊等等)。僅提供供應情況與房價相關資料。
記號化連結會在短時間內到期。若記號傳回 HTTP 503 錯誤，表示連結可能已到期。透過更新的「購物」回應取得新價格檢查或訂金連結，然後再試一次。請勿儲存連結值供長期重覆使用。
Rapid API 允許旅宿隨時更新其內容。我們要求您致力向旅客提供最新的資訊。「購物 API」提供可預訂的房型和房價最新資訊。若要取得此回應未傳回的額外旅宿層級、客房層級和房價等級資訊，請使用我們的「旅宿內容 API」。
API 提供的價格僅限一間客房，若要預訂多個房間，需另自行計算。啟動條件也要求您的整合在預訂過程的某些特定步驟，向使用者顯示詳細價格明細。您可在此「安全文件連結」後找到明細。

若要針對此服務執行測試要求，請參閱我們的「測試要求」說明文件。

API 詳細資料

在這個頁面上探索購物相關端點的定義，然後使用 API Explorer 或其他測試軟體，了解範例和結構描述定義與實際輸出的比較。

其他資源

無論您是想嘗試所有 Rapid API 端點，還是下載其 OpenAPI 規格或我們的 Postman Collection，我們都可協助您完成。

購物

「購物 API」可讓您存取全球超過 700,000 處住宿的即時房價和供應情況。

簡介

價格顯示變化

法律條文的內容為何？

即將進行哪些變更？

會員點數

佣金獎勵

旅遊目的

刪除線價格

促銷及折扣價格顯示

無法提供的原因

設施服務篩選條件

速率限制

價格檢查

付款選項

API 詳細資料

其他資源

其他參考文件

旅客評論

COVID-19 Rapid 更新

EPS 通知測試

簽章產生器