查詢 &;提示 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。如果提供這項資訊,系統會將其納入根據這項 <Hint> 傳送的 <Query> 訊息中,做為 hintId 屬性。

子元素

<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 會取得 7 月 3 日至 7 月 6 日期間,房源 12345 和 67890 的所有行程:

<!-- 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 回應訊息,指明哪些飯店的價格有變動。

如果最近沒有成功擷取資料,系統會將這個值設為固定間隔值 (避免大量待處理項目造成更嚴重的問題)。目前固定間隔值為 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 要求更新價格或中繼資料的訊息。這些訊息可用於「提取」和「價格變更」放送模式

查詢價格訊息

價格查詢訊息會指定您提供價格的房源和行程組合。

伺服器收到 pricing 查詢訊息時,應回覆 <Transaction> 訊息,其中包含所要求的價格資訊。

詳情請參閱「定價總覽」。

Query 訊息有三種特殊類型:

  • 即時價格:Google 會回應特定使用者要求,要求即時更新價格。合作夥伴收到 Live pricing query 訊息後,應以 <Transaction> 訊息回覆,其中包含 <Result> 元素中要求的價格資訊。

  • 採用情境定價:Google 會根據歷來熱門的情境更新價格快取。收到 With Context query 訊息後,請回覆 <Transaction> 訊息,其中包含 <Result> 元素中要求的價格資訊。

    • 單人入住的背景資訊查詢

      在回覆「有脈絡」查詢時,請只傳送與指定脈絡相應的費率。基本費率入住人數至少須為 2 人,因此如果基本費率中傳入單人入住人數,系統會忽略該值,並視為雙人入住。在這種情況下,你應該將基本費率設為無法使用,並在單人入住費率中加入巢狀費率。請參閱含情境的回應範例。您可以透過根據情境變更價格,將 mergeable 屬性設為 "true",合併費率。瞭解詳情

    • 價格變更 (先前稱為「搭配提示提取」) (含指定條件)

      當你傳送 <Transaction> 訊息回應給「價格變更 (含情境)」查詢時,Google 會將其視為特定飯店或行程的價格和供應情形資訊完整替代方案,且所有情境專屬房價都會從回應中排除,並從快取中移除。

      為避免覆寫,您應在 <Transaction> 訊息的 <Result> 元素中,將 mergeable 屬性設為 "true"。Google 會在回應中,將費率附加至所提供情境的現有快取費率。如果未使用可合併的屬性,則必須在回應中傳送所有適用情境的所有費率。

    • 包含背景資訊的即時價格查詢

      根據預設,使用 Context 的即時價格查詢具有可合併的屬性行為,因此不需要設定這項屬性。如果所有其他情境都維持不變,您只需要傳送 Google 要求特定情境的費率。如果其他情境有所變更,您必須明確傳送這些情境的變更,否則 Google 快取不會更新新的費率。

  • 中繼資料:Google 會要求更新指定飯店的房型和房型套裝組合中繼資料。收到 Metadata Query 訊息時,請以 <Transaction> 訊息回覆,並在 <PropertyDataSet> 元素中指定房型和房型套裝組合的資料。詳情請參閱「Room Bundle 中繼資料」。

語法

<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 價格適用的行程範圍結束日期。這個元素僅適用於搭配「提取 + 提示」使用的「入住日期範圍」價格查詢。
<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>