搜尋點 (POI) 動態饋給

建立及上傳 POI 動態饋給

建立及上傳地標動態饋給時，請按照下列指示操作：

  • 請按照搜尋點動態饋給的規格，準備搜尋點資料檔案。建議您為每次上傳的檔案使用不重複的 POI 資料檔名。在檔案名稱中加入時間戳記，例如 POI_1633621547.json。
  • 每天將動態饋給上傳至本機 POI 安全檔案傳輸通訊協定伺服器，進行完整重新整理。
  • 你可以在合作夥伴入口網站的「設定」>「動態饋給」部分找到 SFTP 伺服器詳細資料。

選取動態饋給伺服器

  • 在合作夥伴入口網站的「攝入」>「記錄」部分，查看動態饋給攝入狀態。

動態饋給規格

欄位規定

VssPoi

代表單一搜尋點實體，例如飯店或餐廳。

欄位名稱類型規定說明
poi_id字串

必填

必填。合作夥伴產生的字串，用於識別特定地點。
nameobject
(Text)

必填

必填。搜尋點名稱。
telephone字串

POI 的聯絡電話號碼 (包含所在國家/地區代碼)，例如 +14567891234。
url字串

地標公開網站的網址。 附註：這項資訊僅用於比對，不會顯示。
locationobject
(GeoCoordinates)

必填

必填。POI 的位置。
display_addressobject
(Text)

使用者介面上顯示的地址。
images物件陣列
(Image)

搜尋點的圖片。 圖片數量上限：5 張。
rating數字

POI 的平均評分。
num_ratings數字

rating 欄位的評分次數。
rating_scale數字

「rating」欄位使用的分級量表。如果最高評分為 5，則 rating_scale 為 5。
categoryenum
(Category)

必填

必填。代表搜尋點的類別。
descriptionobject
(Text)

搜尋點說明。
oneOf
(additional_data)

必填

這個 oneOf 中的欄位只能設定一個。

文字

代表本地化文字。

欄位名稱類型規定說明
localizations物件陣列
(LocalizedString)

本地化字串。
default_locale字串

做為預設語言的語言代碼必須存在於本地化項目中。

LocalizedString

代表本地化字串。

欄位名稱類型規定說明
locale字串

文字的語言標記，例如「en」、「en-US」或「sr-Latn」。
text字串

指定語言的文字。

GeoCoordinates

特定位置的地理資訊，包括經緯度和地址。

欄位名稱類型規定說明
latitude數字

[-90, +90] 度 (含)。 如果已設定經度，則為必要欄位，否則為選填欄位。
longitude數字

[-180, +180] 度 (含首尾)。 如果已設定緯度，則為必填欄位，否則為選填欄位。
oneOf
(addresses)

必填

這個 oneOf 中的欄位只能設定一個。

PostalAddress

地點的郵寄地址。

欄位名稱類型規定說明
country字串

必填

必填。國家/地區，使用 ISO 3166-1 alpha-2 國家/地區代碼，例如「US」。
locality字串

必填

必填。縣市，例如「山景城」。
region字串

區域/州/省，例如「CA」。只有在地址通常包含區域名稱的國家/地區，才需要使用這個欄位。(選填)
postal_code字串

必填

必填。郵遞區號，例如「94043」。
street_address字串

必填

必填。街道地址，例如「八德路二段 1 號」。

圖片

代表搜尋點的圖片。

欄位名稱類型規定說明
url字串

圖片的網址。Google 會檢索透過這個網址代管的媒體。 長度上限：2000 個字元。
alt_textobject
(Text)

無障礙功能使用的替代文字。

HotelData

飯店專用動態饋給資料。

欄位名稱類型規定說明
hotel_star_class數字

官方飯店星級值。 可用於標籤，例如「5 星級飯店」。 這個值應為介於 1 到 5 之間的整數。
brand_ids字串陣列

可顯示這間飯店的品牌。 如果這個欄位空白，飯店可能會顯示在與動態饋給相關聯的任何品牌下。

LocalData

特定機構的動態饋給資料。

欄位名稱類型規定說明
business_hoursobject
(BusinessHours)

機構的正常營業時間。
price_rangeobject
(PriceRange)

商家提供的服務價格範圍。
establishment_categoryobject
(Text)

機構類型。
brand_landing_pages物件陣列
(BrandLandingPages)

品牌到達網頁。

BusinessHours

代表這個地點的營業時間。 包含 [TimeRange][madden.vss_poi_feed.TimeRange] 執行個體集合。範例：週六營業時間為 09:00 至 12:00 和 13:00 至 17:00： time_ranges { open_day: SATURDAY open_time: { hours: 9, minutes: 0 } close_day: SATURDAY close_time: { hours: 12, minutes: 0 } } time_rages { open_day: SATURDAY open_time: { hours: 13, minutes: 0 } close_day: SATURDAY close_time: { hours: 17, minutes: 0 } } 範例：週六營業時間為 21:00 至週日 02:00： time_ranges { open_day: SATURDAY open_time: { hours: 21, minutes: 0 } close_day: SUNDAY close_time: { hours: 2, minutes: 0 } }

欄位名稱類型規定說明
time_ranges物件陣列
(TimeRange)

這個搜尋點的營業時間集合。每個時間段代表該地點在一週內的營業時間範圍。

TimeRange

代表 POI 的營業時間範圍，從指定的開店日期/時間開始，到指定的打烊日期/時間結束。結束時間必須晚於開始時間，例如當天稍晚或隔天。

欄位名稱類型規定說明
open_dayenum
(DayOfWeek)

時間範圍的開放日。
open_timeobject
(TimeOfDay)

時間範圍的營業時間。
close_dayenum
(DayOfWeek)

時間範圍的結束日期。
close_timeobject
(TimeOfDay)

時間範圍的結束時間。

TimeOfDay

欄位名稱類型規定說明
hours數字

一天中的小時，採用 24 小時制。必須大於或等於 0，且通常必須小於或等於 23。API 可選擇允許使用「24:00:00」這類的值來表示營業打烊時間等情況。
minutes數字

一小時內的分鐘數。必須大於或等於 0，且小於或等於 59。
seconds數字

一分鐘內的秒數。必須大於或等於 0，且通常必須小於或等於 59。如果 API 允許閏秒，則可允許值為 60。
nanos數字

秒數的小數，以奈秒為單位。必須大於或等於 0 ，且小於或等於 999,999,999。

PriceRange

POI 提供的服務價格範圍。

欄位名稱類型規定說明
min_priceobject
(Money)

POI 提供的服務最低價格。
max_priceobject
(Money)

POI 提供的服務最高價格。

金額

代表金額與其貨幣類型。

欄位名稱類型規定說明
currency_code字串

ISO 4217 定義的三碼貨幣代碼。
units數字

金額的整數單位。 舉例來說，如果 currencyCode 為 "USD"，則 1 個單位為 1 美元。
nanos數字

金額的奈米 (10^-9) 單位數量。 這個值必須介於 -999,999,999 和 +999,999,999 (含) 之間。如果 units 為正值，nanos 必須為正值或零。 如果 units 為零，則 nanos 可為正值、零或負值。 如果 units 為負值，nanos 就必須為負值或零。 例如，$-1.75 美元的表式方式為 units=-1 和 nanos=-750,000,000。

BrandLandingPages

單一搜尋點的本地化品牌到達網頁。

欄位名稱類型規定說明
brand_id字串

這項設定適用的品牌。
localized_landing_pages物件陣列
(LocalizedLandingPage)

本地化到達網頁。 所有本地化到達網頁的網址和語言代碼欄位值不得重複。
default_url字串

如果沒有任何本地化到達網頁符合使用者的語言，系統就會使用預設到達網頁網址。

LocalizedLandingPage

搜尋點的本地化到達網頁。

欄位名稱類型規定說明
url字串

到達網頁的網址。 長度上限：2000 個字元。
locales字串陣列

僅限語言偏好設定符合條件的使用者存取這個頁面。 必須包含語言標記，例如「en」、「en-US」或「sr-Latn」。

類別

代表搜尋點的類別。 這個值應與下方的 additional_data oneof 欄位相符。

名稱說明
UNKNOWN_CATEGORY
HOTEL
LOCAL

DayOfWeek

代表星期幾。

名稱說明
DAY_OF_WEEK_UNSPECIFIED未指定星期幾。
MONDAY星期一
TUESDAY週二
WEDNESDAY週三
THURSDAY週四
FRIDAYFriday (週五)
SATURDAYSaturday (週六)
SUNDAY星期日

additional_data

必填。特定類別的欄位。 應與上述 category 欄位相符。

欄位名稱類型規定說明
hotel_dataobject
(HotelData)

與 local_data 互斥

飯店專屬欄位。
local_dataobject
(LocalData)

與 hotel_data 互斥

當地特定欄位。

addresses

必填。地點的地址。

欄位名稱類型規定說明
addressobject
(PostalAddress)

地點的郵寄地址。
  • 格式：必須為 JPEG、PNG 或 WebP。
  • 檔案大小上限：每張圖片不得超過 30 MB。
  • 最大尺寸：總像素數不得超過 7,500 萬 (寬 x 高 < 75,000,000)。
  • 網址類型：圖片素材資源的直接路徑 (例如結尾為 .jpg)。
  • 權限：確認代管伺服器允許 Googlebot 或檢索器存取，且沒有 robots.txt 封鎖圖片目錄。

定義

VssPoiFeed 定義

// Represents a Point of Interest (POI) data feed provided by a partner.
export message VssPoiFeed {
  // The POIs in the feed.
  repeated VssPoi data = 1;
}

VssPoi 定義

// Represents a single Point of Interest (POI) entity e.g. a hotel or
// restaurant.
export message VssPoi {
  // Required. A string generated by the partner that identifies a POI.
  string poi_id = 1;

  // The entity name, telephone, url and location are used to support
  // matching partner inventory with entities already present on Google.

  // Required. The name of the POI.
  Text name = 2;

  // The contact telephone number of the POI including its country and
  // area codes, e.g. +14567891234.
  string telephone = 3 [(datapol.semantic_type) = ST_PHONE_NUMBER];

  // The url of the POI's public website.
  // Note: This will be used just for matching purposes, not for display.
  string url = 4;

  // Required. The location of the POI.
  GeoCoordinates location = 5;

  // The address displayed on the UI.
  Text display_address = 17;

  // Images of the POI.
  // Max number of images: 5.
  repeated Image images = 6;

  // Average rating for the POI.
  float rating = 12;

  // The number of contributing ratings for the `rating` field.
  int64 num_ratings = 13;

  // The rating scale used for the `rating` field. If max rating is 5, then
  // rating_scale is 5.
  int32 rating_scale = 14;

  // Represents the category of the POI.
  // It should match the `additional_data` oneof field below.
  export enum Category {


    LOCAL = 4;
  }

  // Required. Represents the category of the POI.
  Category category = 9;

  // A description of the POI.
  Text description = 16;

  // Required. Category specific fields.
  // It should match the `category` field above.
  oneof additional_data {


    // Local specific fields.
    LocalData local_data = 15;
  }

}

Text 定義

// Represents a text with localizations.
message Text {
  // Represents a localized string.
  message LocalizedString {
    // The text's language tag, such as "en", "en-US" or "sr-Latn".
    string locale = 1;

    // The text in the specified locale.
    string text = 2;
  }

  // The localized strings.
  repeated LocalizedString localizations = 1;

  // The locale to use as the default language it must be present in the
  // localizations.
  string default_locale = 2;
}

GeoCoordinates 定義

// The Geo data of a location, including latitude, longitude, and address.
message GeoCoordinates {
  option (datapol.msg_semantic_type) = ST_LOCATION;

  // [-90, +90] degrees (inclusive).
  // Required if longitude is set, otherwise nice to have.
  double latitude = 1;

  // [-180, +180] degrees (inclusive).
  // Required if latitude is set, otherwise nice to have.
  double longitude = 2;

  // Required. Address for a location.
  oneof addresses {
    // Postal address of the location.
    PostalAddress address = 3;

  }
}

PostalAddress 定義

// The postal address for the location.
message PostalAddress {
  option (datapol.msg_semantic_type) = ST_LOCATION;

  // Required. The country, using ISO 3166-1 alpha-2 country code, e.g. "US".
  string country = 1;

  // Required. The locality/city, e.g. "Mountain View".
  string locality = 2;

  // The region/state/province, e.g. "CA". This field is only required in
  // countries where region is commonly a part of the address. (optional)
  string region = 3;

  // Required. The postal code, e.g. "94043".
  string postal_code = 4;

  // Required. The street address, e.g. "1600 Amphitheatre Pkwy".
  string street_address = 5;
}

圖片定義

// Represents an image of the Point of Interest (POI).
export message Image {
  // The url of the image. Google will crawl the media hosted at this URL.
  // Max length: 2000.
  string url = 1;

  // The alternative text to be used for accessibility.
  Text alt_text = 2;
}

LocalData 定義

// Establishment specific feed data.
message LocalData {
  // The regular business hours of the establishment.
  BusinessHours business_hours = 1;

  // Price range of the services offered by the establishment.
  PriceRange price_range = 2;

  // The type of establishment.
  Text establishment_category = 3;

  // The brand landing pages.
  repeated BrandLandingPages brand_landing_pages = 4;
}

BrandLandingPages 定義

// The Localized brand landing pages for a single Point of Interest (POI).
message BrandLandingPages {
  // The brand this configuration applies to.
  string brand_id = 1 [(datapol.semantic_type) = ST_PARTNER_ID];

  // Localized landing page for the Point of Interest (POI).
  message LocalizedLandingPage {

    // The url of the landing page.
    // Max length: 2000.
    string url = 1;

    // Restricts this page to users with the specified language preference.
    // Must contain language tags, such as "en", "en-US" or "sr-Latn".
    repeated string locales = 3;
  }

  // The localized landing pages.
  // The url and locales fields values must be unique across all the localized
  // landing pages.
  repeated LocalizedLandingPage localized_landing_pages = 2;

  // The default landing page url to be used when none of the localized
  // landing pages matches the user's language.
  string default_url = 3;
}

範例

搜尋點動態消息

檔案名稱：poi_1707240000.json

{
  "data": [
    {
      "poi_id": "test_restaurant_1",
      "name": {
        "localizations": [
          {
            "locale": "en",
            "text": "Tasty Bites Test Restaurant"
          }
        ],
        "default_locale": "en"
      },
      "telephone": "+1234567890",
      "url": "https://www.tastybitestest.com",
      "location": {
        "latitude": 37.422,
        "longitude": -122.084,
        "address": {
          "country": "US",
          "locality": "Mountain View",
          "postal_code": "94043",
          "street_address": "1600 Amphitheatre Pkwy"
        }
      },
      "display_address": {
        "localizations": [
          {
            "locale": "en",
            "text": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"
          }
        ],
        "default_locale": "en"
      },
      "images": [
        {
          "url": "https://www.tastybitestest.com/images/interior.jpg",
          "alt_text": {
            "localizations": [
              {
                "locale": "en",
                "text": "Cozy dining area of Tasty Bites"
              }
            ],
            "default_locale": "en"
          }
        }
      ],
      "rating": 4.7,
      "num_ratings": 150,
      "rating_scale": 5,
      "category": "LOCAL",
      "description": {
        "localizations": [
          {
            "locale": "en",
            "text": "A mock restaurant for testing the POI feed ingestion."
          }
        ],
        "default_locale": "en"
      },
      "local_data": {
        "establishment_category": {
           "localizations": [
             {
               "locale": "en",
               "text": "Restaurant"
             }
           ],
           "default_locale": "en"
        },
        "price_range": {
          "min_price": {
            "currency_code": "USD",
            "units": 15,
            "nanos": 0
          },
          "max_price": {
            "currency_code": "USD",
            "units": 45,
            "nanos": 0
          }
        },
        "business_hours": {
          "time_ranges": [
            {
              "open_day": "MONDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "MONDAY",
              "close_time": { "hours": 21, "minutes": 0 }
            },
            {
              "open_day": "TUESDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "TUESDAY",
              "close_time": { "hours": 21, "minutes": 0 }
            },
            {
              "open_day": "WEDNESDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "WEDNESDAY",
              "close_time": { "hours": 21, "minutes": 0 }
            },
            {
              "open_day": "THURSDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "THURSDAY",
              "close_time": { "hours": 22, "minutes": 0 }
            },
            {
              "open_day": "FRIDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "FRIDAY",
              "close_time": { "hours": 23, "minutes": 0 }
            },
            {
              "open_day": "SATURDAY",
              "open_time": { "hours": 10, "minutes": 0 },
              "close_day": "SATURDAY",
              "close_time": { "hours": 23, "minutes": 0 }
            },
            {
              "open_day": "SUNDAY",
              "open_time": { "hours": 10, "minutes": 0 },
              "close_day": "SUNDAY",
              "close_time": { "hours": 20, "minutes": 0 }
            }
          ]
        },
        "brand_landing_pages": [
          {
            "brand_id": "tasty_bites_brand",
            "localized_landing_pages": [
              {
                "url": "https://www.tastybitestest.com/en",
                "locales": ["en-US", "en-GB"]
              }
            ],
            "default_url": "https://www.tastybitestest.com"
          },
          {
            "brand_id": "delicious_eats_brand",
            "localized_landing_pages": [
              {
                "url": "https://www.deliciouseats.com/en",
                "locales": ["en-US", "en-GB"]
              }
            ],
            "default_url": "https://www.deliciouseats.com"
          }
        ]
      }
    }
  ]
}

多語言搜尋點動態饋給

檔案名稱：poi_multilingual.json

{
  "data": [
    {
      "poi_id": "test_restaurant_1",
      "name": {
        "localizations": [
          {
            "locale": "en",
            "text": "Tasty Bites Test Restaurant"
          },
          {
            "locale": "fr",
            "text": "Restaurant de test Tasty Bites"
          }
        ],
        "default_locale": "en"
      },
      "telephone": "+1234567890",
      "url": "https://www.tastybitestest.com",
      "location": {
        "latitude": 37.422,
        "longitude": -122.084,
        "address": {
          "country": "US",
          "locality": "Mountain View",
          "postal_code": "94043",
          "street_address": "1600 Amphitheatre Pkwy"
        }
      },
      "display_address": {
        "localizations": [
          {
            "locale": "en",
            "text": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"
          },
          {
            "locale": "fr",
            "text": "1600 Amphitheatre Pkwy, Mountain View, CA 94043"
          }
        ],
        "default_locale": "en"
      },
      "images": [
        {
          "url": "https://www.tastybitestest.com/images/interior.jpg",
          "alt_text": {
            "localizations": [
              {
                "locale": "en",
                "text": "Cozy dining area of Tasty Bites"
              },
              {
                "locale": "fr",
                "text": "Espace salle à manger accueillant de Tasty Bites"
              }
            ],
            "default_locale": "en"
          }
        }
      ],
      "rating": 4.7,
      "num_ratings": 150,
      "rating_scale": 5,
      "category": "LOCAL",
      "description": {
        "localizations": [
          {
            "locale": "en",
            "text": "A mock restaurant for testing the POI feed ingestion."
          },
          {
            "locale": "fr",
            "text": "Un faux restaurant pour tester l'ingestion de flux de points d'intérêt."
          }
        ],
        "default_locale": "en"
      },
      "local_data": {
        "establishment_category": {
           "localizations": [
             {
               "locale": "en",
               "text": "Restaurant"
             },
             {
               "locale": "fr",
               "text": "Restaurant"
             }
           ],
           "default_locale": "en"
        },
        "price_range": {
          "min_price": {
            "currency_code": "USD",
            "units": 15,
            "nanos": 0
          },
          "max_price": {
            "currency_code": "USD",
            "units": 45,
            "nanos": 0
          }
        },
        "business_hours": {
          "time_ranges": [
            {
              "open_day": "MONDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "MONDAY",
              "close_time": { "hours": 21, "minutes": 0 }
            },
            {
              "open_day": "TUESDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "TUESDAY",
              "close_time": { "hours": 21, "minutes": 0 }
            },
            {
              "open_day": "WEDNESDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "WEDNESDAY",
              "close_time": { "hours": 21, "minutes": 0 }
            },
            {
              "open_day": "THURSDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "THURSDAY",
              "close_time": { "hours": 22, "minutes": 0 }
            },
            {
              "open_day": "FRIDAY",
              "open_time": { "hours": 11, "minutes": 0 },
              "close_day": "FRIDAY",
              "close_time": { "hours": 23, "minutes": 0 }
            },
            {
              "open_day": "SATURDAY",
              "open_time": { "hours": 10, "minutes": 0 },
              "close_day": "SATURDAY",
              "close_time": { "hours": 23, "minutes": 0 }
            },
            {
              "open_day": "SUNDAY",
              "open_time": { "hours": 10, "minutes": 0 },
              "close_day": "SUNDAY",
              "close_time": { "hours": 20, "minutes": 0 }
            }
          ]
        },
        "brand_landing_pages": [
          {
            "brand_id": "tasty_bites_brand",
            "localized_landing_pages": [
              {
                "url": "https://www.tastybitestest.com/fr",
                "locales": ["fr-FR", "fr-CA"]
              },
              {
                "url": "https://www.tastybitestest.com/en",
                "locales": ["en-US", "en-GB"]
              }
            ],
            "default_url": "https://www.tastybitestest.com"
          },
          {
            "brand_id": "delicious_eats_brand",
            "localized_landing_pages": [
              {
                "url": "https://www.deliciouseats.com/fr",
                "locales": ["fr-FR", "fr-CA"]
              },
              {
                "url": "https://www.deliciouseats.com/en",
                "locales": ["en-US", "en-GB"]
              }
            ],
            "default_url": "https://www.deliciouseats.com"
          }
        ]
      }
    }
  ]
}