本節提供 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 相同。您可以在單一
|
| <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> | 如果是即時價格查詢,則指定查詢時所用的特定參數。子元素包括:
單一要求中可能會重複出現 |
| <FirstDate> | Pricing | Date | 定價適用的行程範圍開始日期。這個元素僅適用於搭配「已變更的價格」使用的「入住日期範圍」價格查詢。 |
| <HotelInfoProperties> | Metadata | string | Google 希望在元資料 Query 訊息中更新一或多個房型和房型組合的元資料。這個元素可以包含一或多個 <Property> 元素,用來指定飯店房源 ID。 |
| <LastDate> | Pricing | Date | 價格適用的行程範圍結束日期。這個元素僅適用於搭配「提取 + 提示」使用的「入住日期範圍」價格查詢。 |
| <Nights> | Pricing | integer | 特定行程的晚數,最多 30 晚。 |
| <PropertyList> | Pricing | Object | 需要更新價格的一或多個飯店 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 | 指定賓客總數。 雖然不是必要做法,但查詢 注意: |
| <OccupancyDetails> | Pricing | Object | 前身為 <Occupancy>。依類型指定訪客,包括:
雖然並非必要,但使用 注意: |
| <UserCountry> | Pricing | string | 依使用者所在國家/地區篩選費率。這個值是 2 個字母的國家/地區代碼,例如美國為 如果查詢定義了 |
| <UserDevice> | Pricing | string | 依使用者搜尋時使用的裝置類型篩選費率。 可能的類型包括:
如果查詢定義了 |
範例
可住人數
以下範例顯示 <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>