选购

选购 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 增强了 Rapid API，新增了字段 property_inclusive，其中包含总价，包括基本价格以及整个住宿期间所有 Expedia 和房产收取的费用和税款。该总价的删除线版本也已添加到新字段中property_inclusive_strikethrough。除了新增的包含房产信息的显示字段外，我们还调整了 API 响应中税费的分解方式。所有 Expedia 收取的费用都包含在每晚和住宿 property_fee价格细分类型中，所有 Expedia 收取的税款都包含在每晚和住宿 tax_and_service_fee价格细分类型中。

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

Shop 响应中收集的金额的分组方式可能与 Content 响应中显示的金额分组方式不同。总数应该仍然正确。

这是一项针对所有物业的全局性变更，如有任何关于变更的疑问，请联系您的客户经理。

会员积分

加入 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 月份的入住提供了更高的利润。向 Shopping API 发出请求，预订房源 19248，入住日期为 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参数允许您将旅行者指定为商务旅客或休闲旅客。所有 Rapid 合作伙伴都可以使用 travel_purpose参数，帮助酒店更好地识别和服务商务旅客。

对于有资格享受商业税率的合作伙伴，需要在 Shop 请求中使用 travel_purpose=business才能在 Shop 响应中获得商业税率。如果请求中未提供 travel_purpose 参数，则系统将假定这是休闲旅行，并且不会返回商务价格。

示例

指定旅客出于商务目的旅行非常简单，只需在房态 API 请求中添加 24 个字符即可。

&travel_purpose=business

酒店销售

我们对购物 API 进行了以下更改，以支持商品销售流程，并使您能够无缝集成商品销售 API：

合作伙伴可以使用快速购物可用性端点中提供的新的 deal筛选器，仅接收包含有效促销活动的报价。这使得合作伙伴可以灵活地创建以商品销售为重点的购物请求，并确保返回的所有价格都具有 deal属性。
Rapid 的购物可用性端点上新增了一个名为 Campaign-Id的请求标头，您可以用它来表明您正在进行的特定购物可用性 API 调用并非常规调用，而是由于您的商品促销活动（换句话说，这将表明当旅客进入购物体验时，由于促销活动，发出了购物可用性 API 请求）。每次购物 API 调用我们只接受一个活动 ID。

突破性定价

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 但小于预订总金额。

和/或

停留期间内有 non-refundable 日期范围。

利用 current_refundability 字段与单独使用可退款布尔标志相比有哪些优势？

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

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

合作伙伴需要提出申请current_refundability田野下方includeShop 请求中的参数。

示例

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

账单金额可能与实际金额存在约 0.1% 的轻微偏差（每间客房 × 每人 × 每晚）。PriceCheck为了totals.property_fees和fees与之前的 Shop 回复相比，金额可能会调整为零。房产应缴费用的差异是由于以下原因造成的：request_currency和billable_currencyExpedia 收集费率有所不同。此差异不会影响 API 功能。

保持和继续

部分库存不符合保留和恢复条件。使用暂停和恢复功能的合作伙伴可以通过采用 non-holdable 费率的购物指标来获取这些增量费率。更多详情请见此处。这里。

付款方式

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

重要说明

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

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

选购