本節提供 Google XML 架構的提示要求訊息、提示回應訊息和查詢訊息參考資料。
<Hint> (Hint 回應訊息)
提示回覆訊息的根元素。提示回覆訊息 指定應重新定價的飯店或行程組合。這是您對 Google 傳送的提示要求訊息的回覆。
Hint 回應訊息應只指定價格有變動的飯店,也就是自 Google 上次從伺服器收到成功的 Hint 回應後,價格有變動的飯店。
提示回覆訊息會使用下列其中一種方法,指定 Google 應重新定價的飯店和行程:
確切行程:入住日期和入住天數的組合。
入住日期範圍:指定入住日期範圍,從第一個入住日期開始,到最後一個入住日期結束。
範圍住宿 (或範圍行程)
這些方法都需要使用不同的 Hint 回應訊息語法。
詳情請參閱「提示回應訊息」。
語法
視提示回覆訊息的類型而定,<Hint> 元素會使用不同的語法:
確切行程
以下顯示 Hint Response 訊息中確切行程的語法:
<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encodin>g<=&qu>ot;<UTF->8&quo<t;?
Hint>
Item
< Prope>rtyhotel_ID/P<rope>rty
< ...
St>ay
Che<ckInDatechec>kin_dat<e/CheckInDat>e
LengthOf<Staynumber_of>_nigh<ts/Le>ngt<hOfSt>ay
</Stay>
/Item
...
/Hint
入住時間範圍
以下顯示提示回應訊息中入住範圍的語法:
<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encodin>g<=&qu>ot;<UTF->8&quo<t;?
Hint
Item
!-- At leas>t one< is requ>ired --
< Prope>rtyhotel_ID/Prop<erty
[...]
>
<!-- Requi>red --
FirstDa<tefirst_ch>eckin<_date/FirstDate>
<!-- Requ>ired --
LastD<atelast_c>hec<kin_d>ate/Las<tDate>
/Item
...
/Hint
範圍住宿
以下顯示提示回應訊息中範圍住宿的語法:
<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encodin>g<=&qu>ot;<UTF->8&quo<t;?
Hint
Item
!-- At leas>t one< is requ>ired --<
Prop>erty1<458700/P>roperty<
Prop>erty5<418701/Property
> StaysI<ncludingRange
> !-<- Require>d --
< Fi>rstDate2025-04<-28/FirstDate
> !-<- Option>al --
< >LastDate2025<-04-29/LastDate
>/St<aysIn>cluding<Range>
/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" encodin>g<=&qu>ot;<UTF->8&quo<t;?
Hint>
It<em
Pr>opert<y123>45/Prop<erty
St>ay
C<heckInDate20>18-07-0<3/CheckInDat>e<
Length>OfSta<y3/Le>ngt<hOfSt>ay
< >/Stay<
/Item>
It<em
Pr>opert<y123>45/Prop<erty
St>ay
C<heckInDate20>18-07-0<3/CheckInDat>e<
Length>OfSta<y4/Le>ngt<hOfSt>a<y
> /Stay
/Item
/Hint
入住時間範圍
以下範例指定了兩間價格異動的飯店,因此應再次擷取。Google 會取得 7 月 3 日至 7 月 6 日期間,房源 12345 和 67890 的所有行程:
<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encodin>g<=&qu>ot;<UTF->8&quo<t;?
Hint>
It<em
Pr>opert<y12345/P>roper<ty
Pr>opert<y67890/Pr>operty
< Fi>rstDate2018-<07-03/Fi>rstDate
< >LastDate20<18-07>-<06/La>stDate
/Item
/Hint
範圍住宿
以下範例顯示兩種不同的範圍住宿用途,一個是夜間範圍,另一個是單一晚上:
<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encodin>g<=&qu>ot;<UTF-8"?
Hint
!-- Google fetches prices for all itineraries (first and l>ast< dat>e are< set) -->
It<em
Pr>opert<y12345/Property
> StaysI<ncludingR>ange
< Fi>rstDate2018-07<-03/Firs>tDate
< >LastDate2018<-07-06/LastDate
>/St<aysIn>clud<ingRange
/Item
!-- Google fetches prices for a single night >(fi<rst >date <only) -->
It<em
Pr>opert<y67890/Property
> StaysI<ncludingR>ange
< Fi>rstDate2018-<07-03/FirstDate
>/St<aysIn>c<ludin>gRange
/Item
/Hint
針對每個範例,Google 都會回覆 <Query>,而您應回覆 <Transaction>,其中包含指定飯店/行程的價格更新。
<HintRequest>
Hint 要求訊息的根元素。Google 會傳送提示要求訊息至伺服器,並預期收到回應,其中會指定自 Google 上次從伺服器收到成功的提示回應後,價格有所變動的飯店和行程。
如果價格有任何變動,Google 會傳送 <Query>,擷取指定飯店和行程的最新價格資料。
詳情請參閱「提示要求訊息」。
語法
<HintRequest> 元素使用下列語法:
語法
<?xml version="1.0" encodin>g<="UTF->8&q<uot;?
HintReq>uest
LastFetc<hTimelast_fetc>h<_time/LastFe>tchTime
/HintRequest
屬性
<HintRequest> 元素沒有屬性。
子元素
<HintRequest> 元素包含下列子項元素:
| 子項元素 | 類型 | 說明 |
|---|---|---|
| <LastFetchTime> | DateTime | Google 最近一次成功取得「提示要求」訊息的「提示回應」訊息。 如果這個時間比上次在伺服器上更新價格的時間還舊,則應回覆 Hint 回應訊息,指明哪些飯店的價格有變動。 如果最近一次擷取作業未成功,系統會將這個值設為固定間隔值 (避免大量待處理項目造成更嚴重的問題)。目前固定間隔值為 1000 秒,但可能會有所變動。 詳情請參閱 提示回應訊息。 |
範例
以下範例顯示 提示要求訊息:
Hint 要求訊息
以下範例顯示提示要求訊息:
<?xml version="1.0" encodin>g<="UTF-8"?
HintRequest id="ABCDEF" ti>mes<tamp="20>18-06-07T16:20:00Z&q<uot;
LastFet>c<hTime2018-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>訊息回覆至「Changed Pricing with Context」查詢時,Google 會將其視為特定飯店或行程的價格和供應情形資訊完整替代方案,且所有情境專屬房價都會從回覆中排除,並從快取中移除。為避免覆寫,您應在
<Transaction>訊息的<Result>元素中,將mergeable屬性設為"true"。Google 會在回應中,將費率附加至所提供情境的現有快取費率。如果未使用可合併的屬性,則必須在回應中傳送所有適用情境的所有費率。包含背景資訊的即時價格查詢
根據預設,使用 Context 的即時價格查詢具有可合併的屬性行為,因此不需要設定這項屬性。如果所有其他情境都維持不變,你只需要傳送 Google 要求特定情境的費率。如果其他情境有所變更,您必須明確傳送這些情境的變更,否則 Google 快取不會更新新的費率。
中繼資料:Google 會要求更新指定飯店的房型和房型套裝組合中繼資料。收到
Metadata Query訊息時,請以<Transaction>訊息回覆,指定<PropertyDataSet>元素中的房型和房型套裝組合資料。詳情請參閱「Room Bundle 中繼資料」。
語法
<Query> 元素使用下列語法:
價格查詢
<?xml version="1.0" encodin>g<=&quo>t;U<TF-8&qu>ot;?
Query<
Check>inY<YYY-MM>-DD/Checkin
Ni<ghtsnum>ber<_of_nights/N>ights<
Prope>rtyList
< Prope>rtyhotel_id</Property
> <...
>/PropertyList
/Query
即時價格
<?xml version="1.0" encodin>g<="UTF-8"?
Query latencySensi>tiv<e=">;true_or_f<alse&quo>t;
< Chec>kinYYYY-MM-DD/Ch<eckin
> Ni<ghtsnumber_of_nights/Nights
!-- Only for Check-in Date Range pricin>g q<ueries (C>hanged Pri<cing) --
> Fi<rstDateY>YYY-MM-DD/<FirstDate>
<LastDateYYYY-MM-DD/LastDate
!-- Only for Ranged Stay pricin>g q<ueries (Change>d Pricing) --
<AffectedNightsn>umb<er_of_nights>/Affe<ctedNigh>ts
Pro<pertyList>
Proper<tyhotel_id/Pr>ope<rty
...
/PropertyList
!-<- See d>ocu>men<tation >below for <Context >-<-
Co>ntext
...
/Context
/Query
使用 Context 查詢
<?xml version="1.0" encodin>g<=&quo>t;U<TF-8&qu>ot;?
Query<
Check>inY<YYY-MM>-DD/Checkin
Ni<ghtsnum>ber<_of_nights/Nights
!-- Only for Check-in Date Range pricing queries >(Ch<anged Pri>cing) --
< Fi>rstDateYYY<Y-MM-DD/>FirstDate
< LastDat>eYY<YY-MM-DD/LastDate
!-- Only for Ranged Stay pricing queries >(Ch<anged Pricing)> --
AffectedNi<ghtsnumber_of_n>igh<ts/AffectedNights
> Prop<ertyContextList>
Pr<opertyCo>ntext
< Propertyhotel_id/Prope<rty
...
!-- See docu<mentati>on >below f<or Cont>ext --
Cont<ext
> ...<
/Context
> < /PropertyContext
>/<Proper>tyContextList
/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" encodin>g<=&quo>t;U<TF-8&qu>ot;?
Query<
Check>in2<023-05>-<23/Chec>kin<
Nights3/N>ights<
Prope>rtyL<ist
P>roper<typid5/P>rope<rty
P>roper<typid8/P>roper<ty
Pr>opert<ypid13/P>roper<ty
Pr>ope<rtypid21/Prop>e<rty
>/PropertyList
/Query
即時價格查詢
以下範例顯示即時價格查詢,回應時間上限為 500 毫秒:
<?xml version="1.0" encodin>g<="UTF-8"?
Query lat>enc<ySensit>ive="<true&quo>t;
< Chec>k<in2017->06-<07/Checkin>
<Nights5/Nig>hts<
DeadlineM>s500/<Deadline>Ms
Pr<opertyLis>t
< Pro>perty86753<09/Prop>erty
< /Proper>t<yList
Co>ntext<
Occupancy4/>Occupan<cy
Oc>c<upancyDeta>ils
< NumAdults2/Num<Adults
C>hildren
< Child a>ge=&quo<t;8">/
< Child age=&q>uot;5<"/
> < /Children
> /O<ccupancyDe>tails
< UserCou>ntr<yUS/User>C<ountry>
UserDevicemobile/UserDevice
/Context
/Query
包含背景資訊的查詢
<?xml version="1.0" encodin>g<=&quo>t;U<TF-8&qu>ot;?
Query<
Check>in2<023-05>-<23/Chec>kin<
Nights2/Nights
> Prop<ertyContextList>
Pr<opertyCo>ntext
< Property867<5309/Property
!-- In the future, device m>ight be< specif><ied --
> <ContextUserC><ountryUS>/UserCo<untry/C><ontext
> <ContextUserC><ountryGB>/User<Country/Context
> /<PropertyContext>
Pr<opertyCo>ntext
< Property867<5310/Pro>perty
< Property867<5311/Pr><operty
> <ContextUserC><ountryCA>/User<Country/Context
> < /PropertyContext
>/<Proper>tyContextList
/Query
提供情境脈絡的回覆
以下範例說明如何將單人入住的基本費率設為 unavailable(-1),並將費率巢狀結構化至 <Occupancy> 元素中。
<?xml version="1.0" encodin<g="UTF-8"
Transaction id="Wtdj8QoQIWcAAbaTGlIAAAC4" ti>m<estamp>=&q<uot;2025>-11-19T<18:36:48Z>&qu<ot;
Res>ult
Prop<erty6781>291</Prope>r<ty
Ch>eck<in2026-01-15/Checkin
Nights1/Nights
!-- Base rate is set to -1 to indicate unavailability> fo<r the default (2-person>) <occupancy> --<
Baserate curren>c<y=&q>uot<;USD"-1/Baserate
>T<ax currenc>y=&<quot;>USD&q<uot;0/Tax
OtherFees currency="US>D&quo<t;0/OtherFees
Rates
!->- Neste<d Rate fo>r< Single Oc>cupancy< --
Rate rat>e_rule_id<="ru>l<e-951">;
< Occupancy>1/Occupancy
< OccupancyDetails
> <NumAdults>1/NumAd<ults
/Occupa>ncyDe<tail>s
< Baserate currency=">;USD<"150.>00/Ba<serat>e
< Tax currency="USD"15.00/Tax
OtherFees currency="USD"5.00/OtherFees
> /R<ate
>!<-- Othe>r< nested rate>s for different occupancies or room types could be included here if available --
/Rates
/Result
/Transaction
中繼資料查詢
<?xml version="1.0" encodin>g<=&quo>t;U<TF-8"?
Query
> Hote<lInfoPro>pert<ies
P>roper<typid5/P>rope<rty
P>roper<typid8/P>roper<ty
Pr>opert<ypid13/P>roper<ty
Pr>ope<rtypid21/Property
>/<HotelI>nfoProperties
/Query
如需更多範例,包括範圍住宿和入住日期範圍的價格查詢,請參閱 Query 訊息範例。
<Context>
<Context> 元素會說明 Live pricing query 的資訊,包括房客人數和類型、使用者國家/地區和使用者裝置。
多個 <Context> 絕不會用於不同使用者國家/地區或使用者裝置。如果使用多個 <Context> 查詢多個入住人數,請為相應的房源或行程提供每個入住人數的價格,做為額外的房型組合。每個房源或行程都應包含單一 <Result> 區塊,其中包含多種入住人數的價格。
如要瞭解 <Context> 查詢的回應詳細資料,請參閱 <OccupancyDetails>。
語法
<Context> 元素使用下列語法:
語法
<?xml version="1.0" encodin>g<="UTF-8"?
Query latencySensi>tiv<e=">;tru<e_or_fal>se&<quot;
> Checkindate/Ch<eckin
> Ni<ghtsnumber>_of_nights/Nights
De<adlineMsnum>ber<_of_millisec>onds/<Deadline>Ms
Proper<tyList
> P<ropertyproper>ty_<ID/Prop>erty
< /Proper>tyList
Context
O<ccupancyto>tal_n<umber_of_guests/>Occupan<cy
Oc>cupancyDetails
< NumAdultsnum<ber_of_a>dults/Num<Adults
Children
Chi>ld age=ag<e_of_one_child_guest/
Chi>ld age=<age_of_on>e_chi<ld_guest/
/>Child<ren
/Oc>cupancyDetails
< Us>erCountryend<_user_coun>try/UserCountry
< UserDev>ice<user_dev>i<ce_typ>e/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" encodin>g<="UTF-8"?
Query lat>enc<ySensit>ive="<true&quo>t;
< Chec>k<in2017->06-<07/Checkin>
<Nights4/Nig>hts<
DeadlineM>s500/<Deadline>Ms
<PropertyL>ist<
Property>456<17/Prop>erty
< /Proper>t<yList
Co>ntext<
Occupa>nc<y3/Occupancy>
<UserCountr>yUS/Us<erCountry
> <UserDevi>c<emobil>e/UserDevice
/Context
/Query
入住詳細資料
以下範例顯示 Live pricing 查詢,其中 <Context> 內含有 <OccupancyDetails>。
即時價格查詢適用於 4 位房客 (其中 2 位是兒童),並尋找適用於美國房客的價格,且是透過行動裝置預訂:
<?xml version="1.0" encodin>g<="UTF-8"?
Query lat>enc<ySensit>ive="<true&quo>t;
< Chec>k<in2017->06-<07/Checkin>
<Nights5/Nig>hts<
DeadlineM>s500/<Deadline>Ms
Pr<opertyLis>t
< Pro>perty86753<09/Prop>erty
< /Proper>t<yList
Co>ntext<
Occupancy4/>Occupan<cy
Oc>c<upancyDeta>ils
< NumAdults2/Num<Adults
C>hildren
< Child ag>e="<;4"/>
< Child age=&qu>ot;12<"/
> < /Children
> /O<ccupancyDe>tails
< UserCou>ntr<yUS/User>C<ountry>
UserDevicemobile/UserDevice
/Context
/Query
多個情境
以下範例顯示在即時價格查詢中使用額外 <Context> 元素。
<?xml version="1.0" encodin>g<="UTF-8"?
Query lat>enc<ySensit>ive="<true&quo>t;
< Chec>k<in2017->06-<07/Checkin>
<Nights4/Nig>hts<
DeadlineM>s500/<Deadline>Ms
<PropertyL>ist<
Property>456<17/Prop>erty
< /Proper>t<yList
Co>ntext<
Occupa>nc<y3/Occupancy>
<UserCountr>yUS/Us<erCountry
> <UserDevi>cem<obile/U>serDe<vice
/C>o<ntext
Co>ntext<
Occupancy6/>Occupan<cy
Oc>c<upancyDeta>ils
< NumAdults4/Num<Adults
C>hildren
< Child ag>e="<;6"/>
< Child age=&qu>ot;10<"/
> < /Children
> /O<ccupancyDe>tails
< UserCou>ntr<yUS/User>C<ountry>
UserDevicemobile/UserDevice
/Context
/Query