酒店列表 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 Feed 所用的语言。将此元素的值设置为 两个字母组成的语言代码。例如，en 表示英语。
<datum> Optional enum 此元素用于指定 Feed 中提供的纬度/经度坐标的大地测量基准或参考模型。如果未提供基准值，此元素的默认值为 WGS84，大多数现代 GPS 设备都使用此值。东京基准仅适用于日本境内的地址。

此元素的有效值包括：

  • WGS84
  • wgs84
  • TOKYO
  • tokyo
注意：如需使用默认值 WGS84，请勿在酒店列表中添加 <datum> 元素。
<listing> Required <listing> 一个或多个条目，用于描述 Feed 中的每家酒店。请注意，列表中的每家酒店都必须具有您网站独有的 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> 元素在酒店列表 Feed 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，因为这可能会导致在尝试解决房源匹配问题时出现问题。
<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 Maps API）生成。
<longitude> Required* float 与商家信息中所列位置对应的经度，例如： 
<longitude>-122.090101</longitude>

此值可以使用地理编码工具（例如 Google Maps 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> 元素在酒店列表 Feed 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 房源的备用标识符。如果您可能需要一个房源标识符用于 Feed 信息，而另一个房源标识符用于预订引擎，那么提供单独的 ID 会非常有用。 任何字符串值
已弃用：任何字符串类型的自定义属性。这些信息不会向用户显示。

重要提示：如果您想使用 CUSTOM 变量，请与您的技术支持客户经理 (TAM) 联系。

 任何字符串值
hotel_brand 此酒店所属品牌，例如，“Marriott”或“Hilton”。此属性不会向用户显示，但可用于对酒店进行分组。 任何字符串值
lodging Lodging proto 中所有可用字段的编码表示形式。 经过 编码的 Lodging proto 的 Base64 编码字符串
num_reviews 相应房源的评价数量。

要点：“num_reviews”仅应针对度假租赁房源 Feed 发送。

 任何非负整数。
rating 表示房源总评分的浮点数。 此数字通常介于 0-5、0-10 或 0-100 之间，但您可以使用任何表示评分系统的范围。例如，如果 rating_scale 为 5，则房源评分应为 3 或 4。

注意：如果未指定，默认 rating_scale 为 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 Image 抓取工具抓取您网站上的图片。

      • 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>
      <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 部分在 Feed 中指定数据值。如果您使用 CDATA 部分，请勿转义特殊字符。

  • 对于不在 CDATA 部分中的数据值（包括网址），请使用转义代码。您可以使用实体代码或字符代码来表示这些特殊字符。 下表列出了您可以使用的常见实体和字符代码：

    字符 实体 字符代码
    和号 (&) &amp; &#38;
    英文单引号 (') &apos; &#39;
    双引号 (") &quot; &#34;
    大于 (>) &gt; &#62;
    小于 (<) &lt; &#60;

  • 省略不包含数据的 XML 元素。例如，如果您没有酒店的纬度和经度，则不应添加空的 <latitude/> 和 <longitude/> 元素。

  • 在任何情况下都不要在 XML 元素中使用 HTML（即使经过转义也是如此）。

  • 如需在上传之前验证 Feed，您可以使用本地 Feed XSD (http://www.gstatic.com/localfeed/local_feed.xsd)。

  • 如需在 Feed 中使用注释，请将注释封装在 <!-- 和 --> 标记中，如下例所示：

    <!-- This is a comment -->