选购

选购 API 向您提供全球 70 万处住宿的实时房价和房态信息的访问权限。

概述

选购 API 返回有关指定住宿所有房型的房价和房态信息（每个请求最多返回 250 家住宿的信息）。响应包含各种房价详细信息（例如促销、房价是否可退款、取消手续费以及完整的价格明细），以符合您所在市场的价格显示要求。

可通过包含 occupancy 参数的多个实例，请求提供同一类型的多间客房。如果在同一个请求中多次请求相同的入住人数，响应将仅包含该入住人数的一组房价。单次请求不得超过 8 间客房。如果您需要一次预订 8 间以上的客房，请联系您的客户经理。我们正在致力于扩大团体预订，分享您的要求将有助于我们找到解决方案。

价格显示更改

请注意当地法规的最新变化：

加州价格展示条例（加州议会法案 537）自 2024-07-01 起生效
明尼苏达州价格展示条例（第 111 章 - H.F.No. 3438）自 2025-01-01 起生效

我们预计会有其他法规出台，因此不会针对每一项法规更新此页面，这只是两个示例。

为何会有这些变化？

某些司法管辖区正在实施法律，规定如何向旅行者显示价格。每项法律都略有不同，但是，我们实施变更的方式将允许个性化遵守。

Expedia Group 对其 API 进行了更改，以使 API 合作伙伴能够以多种方式显示价格。但最终，每个使用 Expedia Group API 的合作伙伴都有责任确保其显示 Expedia 旅行信息和定价的方式符合法律规定。

Expedia 已增强快速 API，添加一个新字段 property_inclusive，其中包含总价，其中包括基本价格以及整个住宿期间 Expedia 和酒店收取的所有费用和税费。新字段中还提供了此总价的删除线版本property_inclusive_strikethrough。除了新的包含属性的显示字段外，我们还重新调整了 API 响应中税费的细分方式。所有 Expedia 收取的费用均属于每晚和住宿property_fee价格明细类型的一部分，所有 Expedia 收取的税费均属于每晚和住宿tax_and_service_fee价格明细类型的一部分。

对于 Expedia Collect 价格，billable_currency 和 property_inclusive 字段的 property_inclusive_strikethrough 将采用 Expedia Group 与供应商签订的合同中指定的货币，通常是酒店的当地货币。这与 request_currency 无关，因为 property_inclusive 和 property_inclusive_strikethrough 字段可能包括以当地货币在酒店收取的费用。此行为与 inclusive 和 inclusive_strikethrough 字段不同，其中 Expedia Collect 费率的 billable_currency 与 request_currency 相同。

商店响应中的财产收集金额分组可能与内容响应中显示的金额不同。总数应该仍然正确匹配。

这是对所有房产实施的全球性变更，如对变更有任何疑问，请联系您的客户经理。

会员积分

加入 Expedia 商务房价计划的住宿提供会员计划，让商务旅客有机会通过其住宿获得酒店会员积分。在获取旅客的会员身份详细信息之前，合作伙伴可以使用选购响应的“amenities”节点来识别和展示会员资格。

合作伙伴可以在其选购 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”。

退款选项

current_refundability 字段使合作伙伴能够显示所有可退款选项，为旅客提供价格透明度和增强的灵活性。

这三个选项是：

refundable
non_refundable
partially_refundable

部分退款是什么意思？

部分退款是指以下情况的房价：

取消罚金大于 0，但小于预订总价值。

和/或

入住期间内有不可退款的日期范围。

利用 current_refundability 字段比单独使用可退款布尔标志有什么好处？

refundable 布尔标志表示价格是否可以全额退款，但对于部分退款的价格，它返回 false 结果，这会误导旅行者。current_refundability 字段提供了更细致的选项，可以提供有关利率可退款性的更准确信息。

合作伙伴如何接收商店响应中的 current_refundability 字段？

合作伙伴需要请求Shop请求中current_refundability参数下的include字段。

示例

"property_id": "23060",
  "status": "available".
  "rates": [
    {
      "id": "201392692",
      "status": "available",
      ...
      ...
      ...
      ...
      "current_refundability": partially_refundable,
      "cancel_penalties":[
        {
          "start": "2024-10-08T23:59:00.000+02:00",
          "end": "2024-10-09T23:59:00.000+02:00",
          "nights":"1",
          "currency": "EUR"
        }
      ]
    }
  ]

不可预订的原因

借助 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

速率限制

通过对合作伙伴应用速率限制来实现流量优化。这些速率限制可确保向合作伙伴持续提供稳定且便于维护的服务，同时也可以保证 Expedia Group 系统的高效使用。对于 Shop 流量，决定负载的重要因素是每个请求中搜索的住宿数量、客房数量和住宿天数。

有关速率限制的更多信息，请参阅此处。

价格检查

确认选购响应返回的价格。使用此 API 可在预订前验证之前选择的房价是否仍然有效。如果价格匹配，响应会返回请求预订的链接。如果价格已变更，响应将返回新价格详细信息和新价格的预订链接。如果无法继续获取该房价，响应将会返回新选购请求链接，以再次搜索不同的房价。

与之前的商店响应相比，PriceCheck 上显示的 totals.property_fees 和 fees 的可计费金额可能会有大约 0.1%（每间房 × 人 × 晚）的细微变化，其中可能包括调整为零的金额。当 request_currency 和 billable_currency 的 Expedia Collect 费率不同时，就会出现酒店应付费用的差异。API 功能不会受到此差异的影响。

保持和继续

某些库存不符合保留和恢复的条件。使用保留和恢复的合作伙伴可以通过采用不可保留费率的购物指标来访问这些增量费率。更多详情请参见此处。

付款方式

返回 Expedia 从最终旅行者 (EPS MOR) 收取付款时接受的付款选项。使用此 API 可向付款页面提供支持并显示有效的付款方式，以确保顺利完成预订。

重要说明

language 仅使用连字符连接的一对两位语言和国家/地区代码。在集成任何代码之前，请查看支持的语言。
由两个字母组成的 country 代码用于设置旅客的销售网站，不会影响已经本地化的内容。
不会返回静态数据（名称、星级、地理信息等）。仅提供与房态和房价有关的数据。
经过一段较短的时间后，标记化请求链接将失效。如果令牌链接返回 HTTP 503 错误，则该链接可能已失效。请从全新的选购响应中获取新的价格检查或押金链接，然后再次尝试。请勿存储链接值以供长期重复使用。
Rapid API 允许住宿随时更新其内容。我们要求您尽量向客户提供最新信息。选购 API 提供有关房态和房价的最新信息。如需获取此响应中未返回的住宿、客房以及房价级别的其他信息，请使用我们的住宿内容 API。
API 只提供一间客房的价格，多间客房的预订需要您自己另行计算。作为上线要求的一部分，您的集成应在预订过程的某些步骤向最终用户展示详细的价格明细。点击此安全文档链接，即可了解价格明细。

如需针对此服务执行测试请求，请参阅测试请求文档。

选购