查詢 &；提示 XML 參考資料

本節提供 Google 以 XML 為基礎的提示要求訊息、提示回應訊息和查詢訊息的參考資料。

<Hint> (Hint 回應訊息)

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。提供後，系統會將其納入 <Query> 訊息的 hintId 屬性，並以此 <Hint> 傳送。

子元素

<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 上次成功取得提示回應訊息的時間，該訊息是回應提示要求訊息。

如果這段時間比你上次在伺服器上更新價格的時間還久，那麼你應該回覆提示回覆訊息，指出哪些飯店有變動。

如果最近沒有成功擷取，則會將此值設為固定間隔值 (以免大量待處理項目造成更嚴重的問題)。目前的固定間隔值為 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 要求更新價格或中繼資料的請求。這些參數可用於拉取和價格變更放送模式。

價格查詢訊息

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

當伺服器收到價格查詢訊息時，應回覆包含要求價格資訊的 <Transaction> 訊息。

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

Query 訊息有三種特殊類型：

  • 即時價格：Google 回應特定使用者要求，要求即時更新價格。合作夥伴收到 Live pricing query 訊息時，應回覆 <Transaction> 訊息，並在 <Result> 元素中加入要求的價格資訊。

  • 使用脈絡定價：Google 會根據過往熱門的脈絡更新價格快取。收到 With context query 訊息時，請回覆 <Transaction> 訊息，其中包含 <Result> 元素中要求的價格資訊。

  • 中繼資料：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 適用價格的一系列行程的開始日期。這個元素僅用於與「價格異動」搭配使用的「Check-in Date Range」價格查詢。
<HotelInfoProperties> Metadata string 一或多個屬性，Google 希望在中繼資料 Query 訊息中更新房間和房間套裝組合中繼資料。這個元素可包含一或多個 <Property> 元素，用來指定飯店資源 ID。
<LastDate> Pricing Date 價格適用範圍的行程結束日期。這個元素僅用於與 Pull + Hints 搭配使用的 Check-in Date Range 價格查詢。
<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>

中繼資料查詢

<?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> 定義的適當 Room 套裝組合，但如果無法使用 Room 套裝組合，建議您指定 <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>

入住詳細資料

以下範例顯示含有 <OccupancyDetails> 的即時價格查詢，<Context> 內含 <Context>。這項即時價格查詢適用於 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>