查询和提示 XML 参考

本部分提供了 Google 基于 XML 的 提示请求消息、 提示响应消息和 查询消息的参考文档。

<Hint>（提示响应消息）

Hint 回应消息的根元素。提示响应消息用于指定应重新定价的酒店或行程组合。它们是您对 Google 发送的 提示请求消息 的响应。

Hint 回应消息应仅指定自 Google 上次从您的服务器收到成功的 Hint 回应以来价格发生变化的酒店。

提示响应消息使用以下方法之一来指定 Google 应重新定价的酒店和行程：

  • 确切行程：入住日期和 住宿晚数的组合。

  • 入住日期范围：指定入住日期 范围，从第一个入住日期开始，到最后一个 入住日期结束。

  • 范围住宿 （或范围行程）

每种方法都需要使用不同的语法来编写提示响应消息。

如需了解详情，请参阅提示响应消息。

语法

<Hint> 元素使用不同的语法，具体取决于提示 响应消息的类型：

确切行程

以下展示了提示响应消息中确切行程的语法：

<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>hotel_ID</Property>
    ...
    <Stay>
      <CheckInDate>checkin_date</CheckInDate>
      <LengthOfStay>number_of_nights</LengthOfStay>
    </Stay>
  </Item>
  ...
</Hint>

入住范围

以下展示了提示响应消息中入住范围的语法：

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>hotel_ID</Property>
    [...]

    <!-- Required -->
    <FirstDate>first_checkin_date</FirstDate>
    <!-- Required -->
    <LastDate>last_checkin_date</LastDate>
  </Item>
  ...
</Hint>

范围住宿

以下展示了提示响应消息中范围住宿的语法：

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>1458700</Property>
    <Property>5418701</Property>
    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>2025-04-28</FirstDate>
      <!-- Optional -->
      <LastDate>2025-04-29</LastDate>
    </StaysIncludingRange>
  </Item>
  ...
</Hint>

属性

<Hint> 元素包含一个可选属性：id。如果提供此属性，它将作为 hintId 属性包含在基于此 <Hint> 发送的 <Query> 消息中。

子元素

<Hint> 元素具有以下子元素：

子元素 是否必需？ 类型 提示响应类型 说明
<CheckInDate> Required Date 确切行程 行程的入住日期。
<FirstDate> Required Date 入住范围和范围行程 入住范围或范围住宿 Hint 回应消息的日期范围的第一个日期。开始日期和结束日期都包含在内。
<Item> Required Object 全部 要更新的酒店/行程的容器。
<LastDate> Required* Date 入住范围和范围行程

入住范围或范围住宿 Hint 回应消息的日期范围的最后一个日期。开始日期和结束日期都包含在内。

* 对于范围住宿，此元素是可选的。
<LengthOfStay> Required integer 确切行程 行程的住宿晚数，表示为正 整数。
<Property> Required string 全部

酒店的 ID，与酒店列表中的 ID 相同。您可以在单个 <Item> 代码块中指定的 <Property> 元素的数量取决于提示 响应消息的类型：

  • 确切行程：最多 100 家酒店。
  • 入住范围：如果您在 <QueryControl> 消息中将 <MultipleItineraries> 设置为 "checkin_range" ，则可以指定多个。
  • 范围住宿：如果您在 <QueryControl> 消息中将 <MultipleItineraries> 设置为 "affected_dates" ，则可以指定多个。
<Stay> Required Object 确切行程 确切行程提示响应消息中 <CheckinDate> 和 <LengthOfStay> 元素的容器。每个 <Item> 只能包含一个 <Stay>。
<StaysIncludingRange> Required Object 范围行程 范围住宿提示响应消息中 <FirstDate> 和 <LastDate> 元素的容器。

示例

确切行程

以下示例为单个房源定义了多个行程，并将其包含在提示响应消息中：

<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2018-07-03</CheckInDate>
      <LengthOfStay>3</LengthOfStay>
    </Stay>
  </Item>
  <Item>
    <Property>12345</Property>
    <Stay>
      <CheckInDate>2018-07-03</CheckInDate>
      <LengthOfStay>4</LengthOfStay>
    </Stay>
  </Item>
</Hint>

入住范围

以下示例指定了两家酒店，其价格已更改，应重新提取。Google 会获取房源 12345 和 67890 在 7 月 3 日至 7 月 6 日之间的所有行程：

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <Property>12345</Property>
    <Property>67890</Property>
    <FirstDate>2018-07-03</FirstDate>
    <LastDate>2018-07-06</LastDate>
  </Item>
</Hint>

范围住宿

以下示例展示了范围住宿的两种不同用法，一种用于指定住宿晚数范围，另一种用于指定单晚住宿：

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <!-- Google fetches prices for all itineraries (first and last date are set) -->
  <Item>
    <Property>12345</Property>
    <StaysIncludingRange>
      <FirstDate>2018-07-03</FirstDate>
      <LastDate>2018-07-06</LastDate>
    </StaysIncludingRange>
  </Item>

  <!-- Google fetches prices for a single night (first date only) -->
  <Item>
    <Property>67890</Property>
    <StaysIncludingRange>
      <FirstDate>2018-07-03</FirstDate>
    </StaysIncludingRange>
  </Item>
</Hint>

对于每个示例，Google 都会返回 <Query>，然后您应 返回 <Transaction>，其中包含指定酒店/行程的价格更新。

<HintRequest>

Hint 请求消息的根元素。Google 会向您的服务器发送提示请求消息，并期望收到一个响应，其中指定自 Google 上次从您的服务器收到成功的提示响应以来价格发生变化的酒店和行程。

如果价格有任何变化，Google 随后会发送 <Query>，以提取指定酒店和行程的更新价格数据。

如需了解详情，请参阅提示请求消息。

语法

<HintRequest> 元素使用以下语法：

语法

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
  <LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>

属性

<HintRequest> 元素没有属性。

子元素

<HintRequest> 元素具有以下子元素：

子元素 类型 说明
<LastFetchTime> DateTime Google 上次成功获取 Hint 回应消息 以响应 Hint 请求消息的时间。

如果此时间早于您上次在服务器 上更新价格的时间，则您应返回提示 响应消息，指定哪些酒店的价格发生了变化。

如果最近没有成功提取，系统会将此值设置为固定间隔值（以避免因积压大量数据而导致更严重的问题）。当前的固定间隔值为 1000 秒，但可能会发生变化。

如需了解详情， 请参阅 提示响应消息。

示例

以下示例展示了提示请求消息：

提示请求消息

以下示例展示了 Hint 请求消息：

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest id="ABCDEF" timestamp="2018-06-07T16:20:00Z">
  <LastFetchTime>2018-03-25T00:04:09Z</LastFetchTime>
</HintRequest>

<Query>

Query 消息的根元素。Query 消息是 Google 发出的价格或元数据更新请求。它们与 Pull 和价格更改 传送模式一起使用。

价格查询消息

价格查询消息用于指定您提供价格的房源和行程组合。

当您的服务器收到 价格 查询消息时，应返回 <Transaction> 消息，其中包含所请求的价格信息。

如需了解详情，请参阅价格概览。

有三种特殊类型的 Query 消息：

  • 实时价格： Google 会响应特定用户请求，要求进行实时价格更新。当合作伙伴收到 Live pricing query 消息时，应返回 <Transaction> 消息，其中 包含 <Result> 元素中请求的价格信息。

  • 基于情境的价格： Google 会根据以往热门的情境更新其价格缓存。当您收到 With Context query 消息时，应返回 <Transaction> 消息，其中包含 请求的价格信息在 <Result> 元素中。

    • 基于情境的单人入住查询

      在响应基于情境的查询时提供价格时，您应仅发送与指定情境对应的价格。基本费率入住人数至少为 2 人，因此，如果在基本费率中传递单人入住，系统会忽略该信息，并仍将其视为双人入住。在这种情况下，您应将基本费率标记为不可用，并在单人入住中使用嵌套价格。请参阅 基于情境的响应示例。 您可以使用基于情境的价格更改 通过将 mergeable属性设置为"true"来合并价格。了解详情。

    • 基于情境的价格更改（以前称为 Pull with Hints）

      当您针对基于情境的价格更改查询发送 <Transaction> 消息响应时，Google 会将其视为对给定酒店或行程的价格和空闲情况信息的完全替换，并且所有特定于情境的价格都会从响应中排除并从缓存中移除。

      为防止覆盖，您应在 <Transaction> 消息的 <Result> 元素中将 mergeable 属性设置为 "true"。 Google 会在响应中将价格附加到所提供情境的现有缓存价格中。如果您不使用可合并属性，则必须在响应中发送所有适用情境的所有价格。

    • 基于情境的实时价格查询

      基于情境的实时价格查询默认具有可合并属性行为，因此无需设置此属性。如果所有其他情境保持不变，您只需发送 Google 请求的特定情境的价格。如果其他情境发生了变化，您必须明确发送这些情境的变化；否则，新价格将不会在 Google 的缓存中更新。

  • 元数据： Google 会请求指定酒店的客房和客房套餐的元数据更新。当您收到 Metadata Query 消息时，您 应返回 <Transaction> 消息，其中在 <PropertyDataSet> 元素中指定客房和客房套餐的相关数据。如需了解更多 信息，请参阅客房套餐元数据。

语法

<Query> 元素使用以下语法：

价格查询

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
</Query>

实时价格

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
  <FirstDate>YYYY-MM-DD</FirstDate>
  <LastDate>YYYY-MM-DD</LastDate>
  <!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
  <AffectedNights>number_of_nights</AffectedNights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
  <!-- See documentation below for <Context> -->
  <Context>
   ...
  </Context>
</Query>

基于情境的查询

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
  <FirstDate>YYYY-MM-DD</FirstDate>
  <LastDate>YYYY-MM-DD</LastDate>
  <!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
  <AffectedNights>number_of_nights</AffectedNights>
  <PropertyContextList>
    <PropertyContext>
      <Property>hotel_id</Property>
      ...
      <!-- See documentation below for <Context> -->
      <Context>
      ...
      </Context>
    </PropertyContext>
  </PropertyContextList>
</Query>

元数据

<HotelInfoProperties>
  <Property>property_ID</Property>
  ...
</HotelInfoProperties>

属性

<Query> 元素可能包含一个属性：latencySensitive。

latencySensitive 属性是可选属性。如果提供此属性并将其设置为 true，则表示该查询是 Live Pricing Query。如需让 Google 发送带有 latencySensitive 属性的查询，请与您的技术支持客户经理 (TAM) 联系。

子元素

<Query> 元素具有以下子元素：

子元素 查询类型 类型 说明
<AffectedNights> Pricing integer 范围住宿的住宿晚数。此元素仅用于与价格更改一起使用的范围住宿价格查询。
<Checkin> Pricing Date 特定价格更改的日期。
<Context> Pricing (Live Pricing Queries only) <Context> 对于实时价格查询，用于指定进行查询时所依据的某些参数 。子元素包括：
  • <Occupancy>：宾客总数
  • <OccupancyDetails>：宾客类型，例如 成人或儿童
  • <UserCountry>：用户所在的国家/地区
  • <UserDevice>：宾客用来搜索酒店的设备的类型，例如 "mobile、"tablet 或 "desktop."

<Context> 元素可以在单个请求中重复使用，从而允许查询不同的入住人数。如需查看子元素列表、语法和示例，请参阅 <Context>。
<FirstDate> Pricing Date 价格适用的行程范围的开始日期 。此元素仅用于与价格更改一起使用的入住日期范围价格 查询。
<HotelInfoProperties> Metadata string Google 希望在元数据 Query 消息中获取更新的 客房和客房套餐元数据的一个或多个属性。此元素可以包含一个或多个 <Property> 元素，用于指定酒店房源 ID。
<LastDate> Pricing Date 价格适用的行程范围的结束日期 。此元素仅用于与 Pull + Hints 一起使用的入住日期范围价格 查询。
<Nights> Pricing integer 特定行程的住宿晚数，最多 30 晚。
<PropertyList> Pricing Object

需要更新价格的一家或多家酒店的 ID。

在 <Property> 元素中定义每家酒店。该值是一个字符串，与您酒店列表中的酒店 ID 匹配。例如： 

<PropertyList>
  <Property>pid1</Property>
  <Property>pid2</Property>
</PropertyList>

示例

价格查询

以下示例展示了一个价格查询消息，该消息请求更新一组酒店的价格，这些酒店可供住宿 3 晚，入住日期为 2023 年 5 月 23 日：

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2023-05-23</Checkin>
  <Nights>3</Nights>
  <PropertyList>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </PropertyList>
</Query>

实时价格查询

以下示例展示了一个实时价格查询，其响应时间限制为 500 毫秒：

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>5</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>8675309</Property>
  </PropertyList>
  <Context>
    <Occupancy>4</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
      <Children>
        <Child age="8"/>
        <Child age="5"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

基于情境的查询

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2023-05-23</Checkin>
  <Nights>2</Nights>
  <PropertyContextList>
    <PropertyContext>
      <Property>8675309</Property>
      <!-- In the future, device might be specified -->
      <Context><UserCountry>US</UserCountry></Context>
      <Context><UserCountry>GB</UserCountry></Context>
    </PropertyContext>
    <PropertyContext>
      <Property>8675310</Property>
      <Property>8675311</Property>
      <Context><UserCountry>CA</UserCountry></Context>
    </PropertyContext>
  </PropertyContextList>
</Query>

基于情境的响应

以下示例介绍了如何将单人入住的基本费率设置为 unavailable(-1) ，并将费率嵌套在 <Occupancy> 元素中。

<?xml version="1.0" encoding="UTF-8"
<Transaction id="Wtdj8QoQIWcAAbaTGlIAAAC4" timestamp="2025-11-19T18:36:48Z">
<Result>
  <Property>6781291</Property>
  <Checkin>2026-01-15</Checkin>
  <Nights>1</Nights>
  <!-- Base rate is set to -1 to indicate unavailability for the default (2-person) occupancy -->
  <Baserate currency="USD">-1</Baserate>
  <Tax currency="USD">0</Tax>
  <OtherFees currency="USD">0</OtherFees>
  <Rates>
    <!-- Nested Rate for Single Occupancy -->
    <Rate rate_rule_id="rule-951">
      <Occupancy>1</Occupancy>
      <OccupancyDetails>
        <NumAdults>1</NumAdults>
      </OccupancyDetails>
      <Baserate currency="USD">150.00</Baserate>
      <Tax currency="USD">15.00</Tax>
      <OtherFees currency="USD">5.00</OtherFees>
    </Rate>
  <!-- Other nested rates for different occupancies or room types could be included here if available -->
  </Rates>
</Result>
</Transaction>

元数据查询

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <HotelInfoProperties>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </HotelInfoProperties>
</Query>

如需查看更多示例，包括范围住宿和入住日期范围 价格查询，请参阅 Query 消息示例。

<Context>

<Context> 元素用于描述 Live pricing query 的信息， 包括宾客人数和类型、用户国家/地区以及用户设备。

多个 <Context> 绝不会与不同的用户国家/地区或 用户设备一起使用。当使用多个 <Context> 查询多个 入住人数时，请为相应房源或行程提供每个入住人数的价格，作为额外的客房套餐 。每个房源或行程都应 有一个 <Result> 代码块，其中包含多个入住人数的价格 。

如需了解 <Context> 查询的响应详情，请参阅 <OccupancyDetails>。

语法

<Context> 元素使用以下语法：

语法

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
  <Checkin>date</Checkin>
  <Nights>number_of_nights</Nights>
  <DeadlineMs>number_of_milliseconds</DeadlineMs>
  <PropertyList>
    <Property>property_ID</Property>
  </PropertyList>
  <Context>
    <Occupancy>total_number_of_guests</Occupancy>
    <OccupancyDetails>
      <NumAdults>number_of_adults</NumAdults>
      <Children>
        <Child age=age_of_one_child_guest/>
        <Child age=age_of_one_child_guest/>
      </Children>
    </OccupancyDetails>
    <UserCountry>end_user_country</UserCountry>
    <UserDevice>user_device_type</UserDevice>
  </Context>
</Query>

子元素

<Context> 元素具有以下子元素：

子元素 查询类型 类型 说明
<Occupancy> Pricing integer 指定宾客总数。

虽然不是强制性的，但使用 <Occupancy> 的查询应 生成一个交易消息，其中为每个 <Occupancy> 定义了相应的客房套餐；但如果 客房套餐不可用，建议您指定 <Occupancy> 元素。

注意：<Occupancy> 不一定始终显示 在查询中。在这种情况下，您应返回所有 入住人数的价格。
<OccupancyDetails> Pricing Object 前面是 <Occupancy>。按类型指定宾客，包括：
  • <NumAdults>：成人宾客人数
  • <Children> 和 <Child="age">: 指定哪些宾客是儿童（通常为 0-17 岁），并 可选择包含每个儿童的年龄。

虽然不是强制性的，但使用 <OccupancyDetails> 的查询应生成一个交易消息，其中为每个 <Occupancy> 定义了相应的客室 套餐；但如果 客室套餐不可用，建议您 指定 <OccupancyDetails> 元素。

注意： <OccupancyDetails> 不一定始终 显示在查询中。在这种情况下，您应假定所有宾客 都是成人。
<UserCountry> Pricing string

按用户所在的国家/地区过滤价格。该值是一个 双字母国家/地区代码，例如 "US" 表示美国，或一个 区域代码，例如 "EU" 表示“欧洲”。

使用 <UserCountry> 定义的查询应生成一个交易消息，其中为查询的国家/地区定义了相应的 <Rates> 代码块。
<UserDevice> Pricing string

按用户搜索时使用的设备类型过滤价格。 可能的值：

  • mobile
  • desktop
  • tablet

使用 <UserDevice> 定义的查询应生成一个 交易消息，其中为查询的设备类型定义了相应的 <Rates> 代码块。

示例

入住人数

以下示例展示了 <Context> 中 <Occupancy> 的实时价格查询。实时价格查询适用于 3 位成人宾客。

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>4</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>45617</Property>
  </PropertyList>
  <Context>
    <Occupancy>3</Occupancy>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

入住人数详情

以下示例展示了一个实时价格查询，其中<Context>中包含 <OccupancyDetails>。 实时价格查询适用于 4 位宾客，其中 2 位是儿童，并寻求适用于美国宾客通过移动设备预订的价格：

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>5</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>8675309</Property>
  </PropertyList>
  <Context>
    <Occupancy>4</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
      <Children>
        <Child age="4"/>
        <Child age="12"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

多个情境

以下示例展示了在实时价格查询中使用额外的 <Context> 元素 。

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
  <Checkin>2017-06-07</Checkin>
  <Nights>4</Nights>
  <DeadlineMs>500</DeadlineMs>
  <PropertyList>
    <Property>45617</Property>
  </PropertyList>
  <Context>
    <Occupancy>3</Occupancy>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
  <Context>
    <Occupancy>6</Occupancy>
    <OccupancyDetails>
      <NumAdults>4</NumAdults>
      <Children>
        <Child age="6"/>
        <Child age="10"/>
      </Children>
    </OccupancyDetails>
    <UserCountry>US</UserCountry>
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>