飯店清單 XML 參考資料

飯店清單是一或多個 XML 檔案，列出你將提供價格資訊的所有飯店。飯店清單檔案本身不含價格資訊。

飯店清單的根元素是 <listings> 元素，其中包含描述房源的 <listing> 元素。

您可以在初始導入時建立飯店清單，然後在定期維護時新增或移除飯店。

確認檔案符合語法規範。 舉例來說，請使用 UTF-8 編碼，並在 XML 標記中加入 encoding 屬性，指定這個編碼架構。

建立飯店清單後，你可以使用 https://support.google.com/hotelprices/手動上傳至 Google， 或在伺服器上代管。

找出並修正資料問題

如要找出並修正飯店清單中的資料問題，請參閱下列文章：

刊登規定

如要放送 Google 飯店廣告，飯店清單中列出的房源必須符合下列條件：

  • 提供付費房客可入住的房間
  • 具有對外開放的實體據點和固定地點
  • 固定牆壁和水管
  • 最短入住天數不超過 7 天

不符合資格的房源常見例子包括郵輪和公寓，這些房源通常都不符合 Listing requirements 條件。

露營小屋和其他設有固定牆壁、水管和氣候控制裝置 (包括燃木爐或丙烷暖爐) 的露營場所均符合資格。不符合資格的戶外住宿包括：

  • 露營區 (房客入住帳篷)
  • 休旅車露營區 (房客自備休旅車)

<listings>

<listings> 是飯店清單的根元素，包含 <language> 元素和至少一個 <listing>。

<listings> 元素會顯示在飯店清單 XML 階層的下列位置：

+ <listings>
    + <language>
    + <datum>
    + <listing>

語法

<listings> 元素使用下列語法：

<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="xsi"
    xsi:noNamespaceSchemaLocation="schema_xsd">
  <language> language_code</language>
  <datum> datum_code </datum>
  <listing> listing</listing>
  ...
</listings>

屬性

<listings> 元素的屬性如下：

屬性 是否必要？ 說明
xmlns:xsi 必填 請設為 http://www.w3.org/2001/XMLSchema-instance。
xsi:noNamespaceSchemaLocation 必填 請設為 http://www.gstatic.com/localfeed/local_feed.xsd。

子元素

<listings> 元素包含下列子項元素：

子項元素 是否必要？ 類型 說明
<language> Required string 動態饋給所用的語言。將這個元素的值設為 雙字母語言代碼。例如，英文為 en。
<datum> Optional enum 這個元素會指定動態饋給中提供的經緯度座標的大地測量基準或參考模型。如未提供基準值，這個元素的預設值為 WGS84，這是大多數新式 GPS 裝置使用的值。東京基準僅適用於日本境內的地址。

這個元素的有效值如下：

  • WGS84
  • wgs84
  • TOKYO
  • tokyo
注意：如要使用 WGS84 的預設值，請勿在飯店清單中加入 <datum> 元素。
<listing> Required <listing> 一或多個項目，說明動態饋給中的每間飯店。請注意，清單中的每間飯店都必須有網站專屬 ID，且這個 ID 絕不能重複使用。

範例

結構化地址

以下範例顯示部分飯店清單，其中包含結構化地址：

<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.gstatic.com/localfeed/local_feed.xsd">
  <language>en</language>
  <listing>
    <!-- The value of <id> must be unique to your site for all time. Do NOT reuse IDs. -->
    <id>123abc</id>
    <name>Belgrave House</name>
    <address format="simple">
      <component name="addr1">6 Acacia Ave</component>
      <component name="addr2">Floor 5</component>
      <component name="city">London</component>
      <component name="province">Greater London</component>
      <component name="postal_code">SW1W 9TQ</component>
    </address>
    <country>GB</country>
    <latitude>35.070374</latitude>
    <longitude>-106.213648</longitude>
    <phone type="main">123-456-7890</phone>
    <category>hotel</category> <!-- You can use whatever property type categories you wish -->
  </listing>
  ...
</listings>

任意形式的地址

以下範例顯示部分飯店清單，其中包含任意形式的地址：

<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.gstatic.com/localfeed/local_feed.xsd">
  <language>en</language>
  <listing>
    <!-- The value of <id> must be unique to your site for all time. Do NOT reuse IDs. -->
    <id>123abc</id>
    <name>Belgrave House</name>
    <address>6 Elm Ave Unit 3, Boston, MA, 02472</address>
    <country>US</country>
    <latitude>35.070374</latitude>
    <longitude>-106.213648</longitude>
    <phone type="main">123-456-7890</phone>
    <category>hotel</category> <!-- You can use whatever property type categories you wish -->
  </listing>
  ...
</listings>

選用內容

以下範例顯示部分飯店清單，其中包含選用的 <content>：

<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.gstatic.com/localfeed/local_feed.xsd">
  <language>en</language>
  <listing>
    <id>123456</id>
    <name>My Apartment</name>
    <address format="simple">
      <component name="addr1">1 Sandstone Building</component>
      <component name="city">Los Angeles</component>
      <component name="postal_code">90210</component>
      <component name="province">CA</component>
    </address>
    <country>US</country>
    <latitude>40.730610</latitude>
    <longitude>-73.935242</longitude>
    <phone type="main">12345678</phone>
    <category>hotel</category> <!-- You can use whatever property type categories you wish -->
    <content>
      <text type="description">
        <link>https://examplelisting.com/listings/12345</link>
        <title>3 bedrooms with ocean views</title>
        <body>Stay in this newly renovated 3BR house with ocean views.</body>
        <date month="7" day="23" year="2023"/>
      </text>
      <attributes>
        <website>https://hotel.example.com</website>
        <client_attr name="rating">8.2</client_attr>
      </attributes>
      <image type="photo" url="https://image_url">
        <link>https://image_url</link>
        <title>Main hotel picture</title>
      </image>
    </content>
  </listing>
  ...
</listings>

<listing>

飯店清單 <listings> 元素中的飯店定義。

<listing> 元素會出現在飯店清單動態饋給 XML 階層的下列位置：

+ <listings>
    + <language>
    + <listing>

語法

<listing> 元素使用下列語法：

<?xml version="1.0" encoding="UTF-8"?>
<listings ... >
  <listing>
    <!-- Specify <listing>'s child elements in the order shown below. -->
    <id>hotel_ID</id>
    <name>hotel_name</name>
    <address>
      <component name="addr1">street_address_1</component>
      <component name="addr2">street_address_2</component>
      <component name="city">city_name</component>
      <component name="province">province_name</component>
      <component name="postal_code">postal_code</component>
    </address>
    <!-- You can also define an address freeform, although this is not recommended: -->
    <!-- <address>freeform_address</address> -->

    <country>country_code</country>
    <latitude>hotel_latitude</latitude>
    <longitude>hotel_longitude</longitude>
    <phone type="[fax|main|mobile|tdd|tollfree]">phone_number</phone>
    <category>hotel</category> <!-- You can use whatever property type categories you wish -->
    <content>content</content>
  </listing>
</listings>

屬性

<listing> 元素沒有屬性。

子元素

<listing> 元素包含下列子項元素：

子項元素 是否必要？ 類型 說明
<id> Required string 飯店的專屬 ID。

注意：網站中的這個值不可重複。 請勿重複使用 ID，否則嘗試解決房源比對問題時可能會發生問題。
<name> Required string 飯店的名稱，例如：
<name>Belgrave House</name>
<address> Required Object or string

飯店的完整實際地點。

這個元素會採用單一屬性 format，您必須將這個屬性設為 simple。

你至少須提供飯店的街道地址、城市、州/省或區域，以及郵遞區號。使用 <component> 子元素描述地址的各個部分，包括：

  • addr1：飯店的主要街道地址。
  • addr2：次要街道地址 (如有需要)。
  • addr3：街道地址的第三個部分 (如有必要)。
  • city：飯店所在城市的名稱。
  • province：飯店所在的州、區域或省名。
  • postal_code：飯店的郵遞區號。

例如：

<address format="simple">
  <component name="addr1">6 Acacia Ave</component>
  <component name="addr2">Floor 5</component>
  <component name="city">London</component>
  <component name="province">Greater London</component>
  <component name="postal_code">SW1W 9TQ</component>
</address>

或者，您也可以提供「任意格式」的地址，但我們不建議這麼做。例如：

<address>6 Elm Ave Unit 3, Boston, MA, 02472</address>

請注意，郵政信箱或其他僅供郵寄的地址都不算是完整的實際地址。
<country> Required string 這項房源所在的國家/地區。值必須是雙字母國家/地區代碼。例如美國是「US」，加拿大是「CA」。例如：
<country>US</country>
<latitude> Required* float 與商家資訊中列出的所在位置對應的緯度，例如：
<latitude>37.423738</latitude>

這個值可使用 Google 地圖 API 等地理編碼工具產生。
<longitude> Required* float 與商家資訊中列出的所在位置對應的經度，例如：
<longitude>-122.090101</longitude>

這個值可使用 Google 地圖 API 等地理編碼工具產生。
<location_precision> Optional integer 當屬性緯度和經度遭到模糊處理時，以公尺為單位傳送的屬性位置精確度。零 (0) 表示沒有模糊處理，是確切位置。注意： 這項元素僅適用於度假民宿。
<phone> Required* string

飯店的一或多個聯絡電話號碼。如果商家資訊是分店，請提供分店專用的電話號碼 (而非總部的電話號碼)。

type 屬性可以是下列其中一項：

  • fax：傳真電話號碼。
  • main：主要語音電話號碼。
  • mobile：手機號碼。
  • tdd：失聰人士專用的電信裝置 (TDD) 電話號碼。
  • tollfree：免付費電話號碼。

例如：

<!-- Singapore (country code +65) -->
<phone type="main">+65 6722-2323</phone>
<!-- U.S. (country code +1) -->
<phone type="fax">+1 408-555-1111</phone>

至少應提供 main 類型。
<category> Optional string 房源類型，例如飯店。合作夥伴可使用任何內部類別來描述房源，例如「商務飯店」、「度假村」、「汽車旅館」等。
<content> Optional <content> 房源的選用詳細資料，例如說明、評分和特色。

* 必須輸入電話號碼「或」緯度/經度，建議您同時定義這兩者。

範例

結構化地址

以下範例顯示部分飯店清單，其中包含結構化地址：

<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.gstatic.com/localfeed/local_feed.xsd">
  <language>en</language>
  <listing>
    <!-- The value of <id> must be unique to your site for all time. Do NOT reuse IDs. -->
    <id>123abc</id>
    <name>Belgrave House</name>
    <address format="simple">
      <component name="addr1">6 Acacia Ave</component>
      <component name="addr2">Floor 5</component>
      <component name="city">London</component>
      <component name="province">Greater London</component>
      <component name="postal_code">SW1W 9TQ</component>
    </address>
    <country>GB</country>
    <latitude>35.070374</latitude>
    <longitude>-106.213648</longitude>
    <phone type="main">123-456-7890</phone>
    <category>hotel</category> <!-- You can use whatever property type categories you wish -->
  </listing>
  ...
</listings>

任意形式的地址

以下範例顯示部分飯店清單，其中包含任意形式的地址：

<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.gstatic.com/localfeed/local_feed.xsd">
  <language>en</language>
  <listing>
    <!-- The value of <id> must be unique to your site for all time. Do NOT reuse IDs. -->
    <id>123abc</id>
    <name>Belgrave House</name>
    <address>6 Elm Ave Unit 3, Boston, MA, 02472</address>
    <country>US</country>
    <latitude>35.070374</latitude>
    <longitude>-106.213648</longitude>
    <phone type="main">123-456-7890</phone>
    <category>hotel</category> <!-- You can use whatever property type categories you wish -->
  </listing>
  ...
</listings>

選用內容

以下範例顯示部分飯店清單，其中包含選用的 <content>：

<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.gstatic.com/localfeed/local_feed.xsd">
  <language>en</language>
  <listing>
    <id>123456</id>
    <name>My Apartment</name>
    <address format="simple">
      <component name="addr1">1 Sandstone Building</component>
      <component name="city">Los Angeles</component>
      <component name="postal_code">90210</component>
      <component name="province">CA</component>
    </address>
    <country>US</country>
    <latitude>40.730610</latitude>
    <longitude>-73.935242</longitude>
    <phone type="main">12345678</phone>
    <category>hotel</category> <!-- You can use whatever property type categories you wish -->
    <content>
      <text type="description">
        <link>https://examplelisting.com/listings/12345</link>
        <title>3 bedrooms with ocean views</title>
        <body>Stay in this newly renovated 3BR house with ocean views.</body>
        <date month="7" day="23" year="2023"/>
      </text>
      <attributes>
        <website>https://hotel.example.com</website>
        <client_attr name="rating">8.2</client_attr>
      </attributes>
      <image type="photo" url="https://image_url">
        <link>https://image_url</link>
        <title>Main hotel picture</title>
      </image>
    </content>
  </listing>
  ...
</listings>

<content>

新增房源資訊，例如評分、設施和其他詳細資料。<content> 元素為選用項目。在 <content> 中，所有子項元素皆為選填。

<content> 元素會出現在飯店清單動態饋給 XML 階層的下列位置：

+ <listings>
    + <language>
    + <listing>
        + <content>

語法

<content> 元素使用下列語法：

<?xml version="1.0" encoding="UTF-8"?>
<listings ... >
  <listing>
    <content>
      <!-- Specify <text>'s child elements in the order shown below. -->
      <text type="description">
        <link>listing_link</link>
        <title>listing_title</title>
        <author>listing_author</author>
        <body>listing_description</body>
        <date month="MM" day="DD" year="YYYY"/>
      </text>
      <!-- 0 or more attributes: -->
      <attributes>
        <website>https://hotel.example.com</website>
        <client_attr name="alternate_hotel_id">alternate_hotel_id</client_attr>
        <client_attr name="hotel_brand">hotel_brand</client_attr>
        <client_attr name="rating">aggregate_rating</client_attr>
      </attributes>
      <!-- a picture of the hotel or property-->
      <image type="photo" url="https://image_url">
        <link>https://image_url</link>
        <title>Main Hotel Picture</title>
      </image>
    </content>
  </listing>
  ...
</listings>

屬性

<content> 元素沒有屬性。

子元素

<content> 元素包含下列子項元素：

子項元素 是否必要？ 類型 說明
<text type="description"> Optional Object

供應商提供的商家資訊相關網頁。 具有下列子元素：

  • <link>：說明連結。在這個元素中加入「http://」或「https://」(選用)。
  • <title>：說明的標題 (選填)。
  • <author>：說明的作者 (選填)。
  • <body>：說明內文 (必要)。
  • <date>：說明日期 (選填)。

    • 注意：這些元素必須按照上述順序顯示。
<review type="[editorial|user]"> Optional <review>

內含商家資訊的使用者評論或編輯評論。你的商家資訊可以有任意數量的評論，不限類型。

您不必在 <listing> 元素中加入資源的所有評論，這個元素是用來加入精選評論，說明這個房源的特色或品質。

重要事項： <review> 僅適用於度假民宿帳戶。如需詳細資訊，請與技術客戶經理 (TAM) 聯絡。
<attributes> Optional Object

包含 0 個以上的 <client_attr> 子項元素，提供房源詳細資料。子項元素使用下列語法：

<client_attr name="attribute_name">attribute_value<client_attr>

如需子項元素的清單和說明，請參閱 <attributes>。

所有 <client_attr> 元素皆為選填。

如有 <website> 子項元素，必須位於所有 <client_attr> 元素之前。
<image> Optional Object 重複的標記，包含詳細的圖片資訊。

範例

以下範例顯示部分飯店清單，其中包含 <content> 元素：

<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.gstatic.com/localfeed/local_feed.xsd">
  <language>en</language>
  <listing>
    <id>123456</id>
    <name>My Apartment</name>
    <address format="simple">
      <component name="addr1">1 Sandstone Building</component>
      <component name="city">Los Angeles</component>
      <component name="postal_code">90210</component>
      <component name="province">CA</component>
    </address>
    <country>US</country>
    <latitude>40.730610</latitude>
    <longitude>-73.935242</longitude>
    <phone type="main">12345678</phone>
    <category>hotel</category> <!-- You can use whatever property type categories you wish -->
    <content>
      <text type="description">
        <link>https://examplelisting.com/listings/12345</link>
        <title>3 bedrooms with ocean views</title>
        <body>Stay in this newly renovated 3BR house with ocean views.</body>
        <date month="7" day="23" year="2023"/>
      </text>
      <attributes>
        <website>https://hotel.example.com</website>
        <client_attr name="rating">8.2</client_attr>
      </attributes>
      <image type="photo" url="https://image_url">
        <link>https://image_url</link>
        <title>Main hotel picture</title>
      </image>
    </content>
  </listing>
  ...
</listings>

<attributes>

<attributes> 標記可用於描述房源設施，以及分類房源的評分。

+ <listings>
    + <language>
    + <listing>
        + <content>
            + <attributes>

子元素

子項元素 是否必要？ 說明
<website> Optional 飯店的主要網站，如果存在，則必須位於第一個 <client_attr> 元素之前。範例： 
<website>https://hotel.example.com</website>
<client_attr name="attribute_name"> Optional 房源的其他特徵或「屬性」，可使用支援的 attribute_name或 attribute_name指定度假民宿。

attribute_name 預留位置的值

下表列出 <client_attr name="attribute_name"> 元素中 attribute_name 的有效值。

attribute_name 的值 說明 有效內容值
alternate_hotel_id 房源的備用 ID。如果動態饋給資訊與預訂引擎需要不同的房源 ID，採用各不相同的專屬 ID 會有所幫助。 任何字串值
已淘汰：任何字串類型的自訂屬性。這些資訊不會向使用者顯示。

重要事項：如要使用 CUSTOM 變數，請與客戶技術顧問 (TAM) 聯絡。

 任何字串值
hotel_brand 這間飯店隸屬的品牌，例如「萬豪國際」或「希爾頓」。這項資訊不會向使用者顯示，但可用於將飯店分組。 任何字串值
lodging Lodging proto 中所有可用欄位的編碼表示法。 Base64 編碼的字串，代表 encoded Lodging proto
num_reviews 商家資訊的評論數。

重點：「num_reviews」只應針對度假民宿動態饋給傳送。

 任何非負整數。
rating 代表房源整體評分的浮點數。 這個數字通常介於 0 到 5、0 到 10 或 0 到 100 之間，但您可以使用任何代表評分系統的範圍。舉例來說，如果 rating_scale 為 5，則房源評等應為 3 或 4。

注意：如未指定，預設的評分範圍為 0 到 10。

度假民宿的 attribute_name 預留位置值

請參閱度假民宿專用屬性和 XML 範例。

<image>

+ <listings>
    + <language>
    + <listing>
        + <content>
            <!-- <review> is allowed in Vacation Rentals only -->
            + <review>
            + <attributes>
            + <image>

圖片會用於在房源 ID 中顯示房源。使用的所有圖片都必須遵守下列規範：

  • 建議的圖片顯示比例為 4:3。
  • 圖片網址必須可讓 Googlebot 圖片檢索器存取。

  • 如果網站根層級包含 robots.txt，請確認其中包含下列任一選項：

    1. 允許 Googlebot 檢索器檢索網站內容，包括圖片。

      • User-agent: Googlebot
      • Allow: /

    2. 允許 Googlebot 圖片檢索器檢索網站上的圖片。

      • User-agent: Googlebot-Image
      • Allow: /

  • 請勿提供圖片或網站的螢幕截圖。圖片必須是原創的實際圖片或相片。

屬性

  • "ad" 圖片為廣告
  • "menu" (如果圖片是餐廳菜單)
  • "photo" 如果圖片是商家相片
屬性名稱 是否必要？ 格式 說明
type Required Text

圖片必須符合下列其中一項條件：
url Required Text 完整尺寸圖片的網址。使用 url 屬性指定要在該頁面上使用的圖片。
width Required A non-negative integer 圖片寬度 (以像素為單位，建議大於 720 像素)
height Required A non-negative integer 圖片高度 (以像素為單位，建議大於 720 像素)

子元素

子項元素 是否必要？ 說明
<link> 這是建議屬性，但店面相片資訊必須提供這項屬性。 這個標記包含網站上相關圖片所在網頁的有效最新網址。不含圖片本身的網址。 範例：
<link><http://www.example.com/magic_pizza/></link>
<title> 已要求 這個標記包含圖片的標題。範例： 
<title>"Luxury Apartment"</title>
<author> 非必要 內容作者的名稱。值可以是使用者名稱，也可以是「名字 姓氏」格式的全名。
<date> 必填

這個標記會指明內容項目的建立日期。您必須輸入年、月和日，如下例所示：

<date month="6" day="7" year="2023"/>

範例

以下範例顯示部分飯店清單，其中包含圖片標記：

<?xml version="1.0" encoding="UTF-8"?>
<listings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="http://www.gstatic.com/localfeed/local_feed.xsd">
  <language>en</language>
  <listing>
    <content>
      <review>
      </review>
      <attributes>
      </attributes>
      <image type="photo" url="https://image_url" width="400" height="300">
        <link>https://image_url</link>
        <title>Apartment at Sandstone</title>
        <author>Jessica Landlord</author>
        <date month="6" day="7" year="2023"/>
      </image>
    </content>
  </listing>
  ...
</listings>

語法規範

建立 XML 格式的飯店清單時，請遵守下列規範：

  • 使用 Google 的 XSD 架構驗證飯店清單 XML 檔案。

  • 使用 UTF-8 編碼。如要指定這個編碼架構，請在 XML 標記中加入 encoding 屬性，如下列範例所示。

  • 你可以在動態饋給中指定 CDATA 區段的資料值。如果使用 CDATA 區段，請勿逸出特殊字元。

  • 針對不在 CDATA 區段中的資料值 (包括網址) 使用逸出碼。您可以使用實體碼或字元碼來表示這些特殊字元。下表列出可使用的常見實體和字元代碼：

    字元 實體 字元代碼
    連字符號 (&) &amp; &#38;
    單引號 (') &apos; &#39;
    雙引號 (") &quot; &#34;
    大於 (>) &gt; &#62;
    小於 (<) &lt; &#60;

  • 省略不含資料的 XML 元素。舉例來說，如果沒有飯店的經緯度，就不應加入空白的 <latitude/> 和 <longitude/> 元素。

  • 請勿在 XML 元素中使用 HTML (即使是逸出也一樣)。

  • 如要在上傳前驗證動態饋給，可以使用本機動態饋給 XSD http://www.gstatic.com/localfeed/local_feed.xsd。

  • 如要在動態消息中使用註解，請將註解納入 <!-- 和 --> 標記中，如下列範例所示：

    <!-- This is a comment -->