查询和提示 XML 参考

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

<Hint>（提示响应消息）

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

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

提示响应消息使用以下方法之一来指定 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。如果提供，则会作为 <Hint> 消息中的 hintId 属性包含在基于此 <Hint> 发送的 <Query> 消息中。

子元素

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

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

入住范围或范围型住宿提示响应消息的日期范围的结束日期。包含相应日期。

* 对于范围型住宿，此元素是可选的。
<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>

提示请求消息的根元素。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 Response 消息进行响应，并指定哪些酒店的价格发生了变化。

如果最近没有成功提取，则此值将设置为固定间隔值（以避免出现更严重的积压问题）。当前的固定间隔值为 1000 秒，但可能会发生变化。

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

示例

以下示例展示了 Hint Request 消息：

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 发出的价格或元数据更新请求。它们可与“拉取”和“价格更改”这两种传送模式搭配使用。

价格查询消息

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

当服务器收到 pricing 查询消息时，应使用包含所请求价格信息的 <Transaction> 消息进行响应。

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

Query 消息有三种特殊类型：

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

  • 采用情境定价：Google 会根据以往热门的情境更新价格缓存。当您收到 With Context query 消息时，应使用 <Transaction> 消息进行回复，该消息包含 <Result> 元素中请求的价格信息。

    • 使用情境查询功能进行单人入住

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

    • 带上下文的价格更改（以前称为 Pull with Hints）

      当您针对“价格已更改（含背景信息）”查询发送 <Transaction> 消息响应时，Google 会将其视为对指定酒店或行程的价格和房态信息的完全替换，并且所有特定于背景信息的房价都会从响应中排除并从缓存中移除。

      为防止覆盖，您应在 <Transaction> 消息的 <Result> 元素中将 mergeable 属性设置为 "true"。Google 会将汇率附加到响应中提供的上下文的现有缓存汇率中。如果您不使用 mergeable 属性，则必须在响应中针对所有适用的上下文发送所有费率。

    • 基于上下文的实时价格查询

      具有上下文的实时价格查询默认具有可合并属性行为，因此无需设置此属性。如果所有其他情境保持不变，您只需发送 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 消息中更新的一个或多个房源的客房和客房套装元数据。 此元素可以包含一个或多个用于指定酒店房源 ID 的 <Property> 元素。
<LastDate> Pricing Date 价格适用的行程范围的结束日期。此元素仅用于与“拉取 + 提示”搭配使用的“入住日期范围”价格查询。
<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

按用户所在的国家/地区过滤费率。该值是 2 个字母的国家/地区代码，例如 "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>