要求參數

本文說明 Places Insights API 的要求參數，並提供這項服務的洞察資料和最佳做法。

Places Insights API 可讓您執行多項重要功能：

  • 計算地點數量：判斷符合特定條件的地點數量，例如地點類型、營業狀態、價格等級和評分。
  • 擷取地點詳細資料：取得符合指定篩選條件的地點名稱，然後使用 Places API 擷取更詳細的資訊。
  • 靈活篩選功能：套用全面的篩選條件，取得精確的洞察資料。可用的篩選器包括：
    • 地理區域 (圓形、區域或自訂多邊形)
    • 地點類型
    • 營業狀態
    • 價格等級
    • 評分範圍

必要參數

本節將說明向 Places Insights API 發出要求時，所需的參數。每個要求都必須提供下列資訊：

  • 洞察類型。
  • 位置篩選器和類型篩選器。

洞察類型

指定要計算的洞察資料類型。支援下列洞察類型：

  • INSIGHT_COUNT：傳回符合篩選條件的地點數量。
  • INSIGHT_PLACES：傳回符合篩選條件的地點 ID。

篩選器

指定篩選地點的條件。您至少必須指定 LocationFilter 和 TypeFilter。

位置篩選器

位置篩選器可以是下列任一類型：

  • circle：將區域定義為具有圓心和半徑的圓形。
  • region：將區域定義為區域。
  • customArea：將區域定義為自訂多邊形。
圓形

如果您選取的地區範圍為圓形，則必須提供 center 和 radius。center 可以是經緯度，也可以是圓形中心的 Place ID。這個方法可根據您定義的圓形區域，精確篩選出所需資料。

  • center：
    • latLng：圓形中心的經緯度。緯度必須是介於 -90 和 90 之間的數字 (含首尾)。經度必須是介於 -180 和 180 之間的數字 (含上下限)。
    • place：圓形中心的 Place ID。請注意，系統僅支援點位。這個字串的開頭必須是 places/ 前置字元。
  • radius：圓形半徑，單位為公尺。這個數字必須為正數。
區域

將地點 ID 傳遞至 place 參數，即可將您的區域定義為區域。地點 ID 代表地理區域 (例如可由多邊形表示的區域)。舉例來說，佛羅里達州坦帕的地點 ID 為 places/ChIJ4dG5s4K3wogRY7SWr4kTX6c。請注意，並非所有地點 ID 都有明確定義的幾何圖形，在這種情況下，Places Insights API 會傳回 400 錯誤代碼，並附上指出不支援該區域的訊息。此外，對於複雜的地理區域，內部處理最佳化作業可能會導致代表該區域的面積略大於實際值 (最多 2-3%)。

如要判斷地點 ID 是否代表不支援的地點類型，請在 Geocoding API 要求中傳遞地點 ID。回應中包含 type 陣列，列出與地點 ID 相關聯的地點類型，例如 city、neighborhood 或 country。

不支援的地點類型包括：

  • establishment：通常表示尚未歸類的地點。
  • street_number：表示精確的門牌號碼。
  • floor：表示建築物地址的樓層。
  • post_box：表示特定郵政信箱。
  • street_address：表示精確的街道地址。
  • room：表示建築物地址的房號。
  • intersection：表示主要的十字路口，通常有兩條主要道路交會。
  • landmark：表示附近地點，做為導航輔助參考。
  • subpremise：表示位於建築物以下的實體，例如公寓、單元或套房。
  • sublocality_level_5：最精確的子區位址組件層級，通常代表城市內的極為局部地區或極為局部區域。
自訂區域

使用經緯度座標定義自訂多邊形的面積。

您可以前往 https://geojson.io/ 繪製自訂多邊形，然後在要求中輸入這些座標。多邊形必須至少有 4 個座標，且第一個和最後一個座標必須相同。至少有 3 個提供的座標必須是唯一的。

連續相同的座標會視為單一座標。不過，如果座標重複但不連續 (除了第一個和最後一個座標必須相同)，系統會產生錯誤。

此外，非相鄰邊不得相交，且邊的長度不得為 180 度 (也就是相鄰頂點不得為對跖點)。

例如：

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

類型篩選器

指定要納入或排除的地點類型。如需 Places Insights API 支援的主要和次要地點類型清單，請參閱 Places API (新版) 的「地點類型」下方的表 A。您必須指定至少一個 includedTypes 或 includedPrimaryTypes 類型。

  • includedTypes：所包含的地點類型清單。
  • excludedTypes：排除的地點類型清單。
  • includedPrimaryTypes：已納入的主要地點類型清單。
  • excludedPrimaryTypes：排除的主要地點類型清單。

如要進一步瞭解類型篩選器和地點類型的運作方式，請參閱「進一步瞭解類型篩選器」一文。

選用參數

以下篩選器為選用項目：

  • operatingStatus：指定要納入或排除的地點狀態。預設為依據 operatingStatus: OPERATING_STATUS_OPERATIONAL 篩選 (一個特定值)。
  • priceLevels：指定地點的價格等級。預設為不篩選 (結果會包含所有價格等級)。
  • ratingFilter：指定地點的評分範圍。預設為不篩選 (結果會包含所有評分)。

營業狀態

您可以使用 operatingStatus 篩選器，根據營業狀態進行篩選 (例如營業中或暫停營業)。如果未設定 operatingStatus 篩選器，結果中只會列出營業狀態為 OPERATING_STATUS_OPERATIONAL 的場所。

價格等級

使用 price_levels 篩選器時，你可以根據價格等級 (例如免費、中等或昂貴) 進行篩選。如果未設定 price_levels 篩選器，結果就會包含所有價格等級。

評分篩選器

根據平均使用者評分篩選地點。這兩個欄位皆為選用欄位，因此如果省略這些欄位，系統預設會一併納入沒有評分的景點。

  • minRating：最低平均使用者評分 (介於 1.0 和 5.0 之間)。
  • maxRating：最高平均使用者評分 (介於 1.0 和 5.0 之間)。

此外，minRating 值一律必須小於或等於 maxRating 值。如果指定的 minRating 大於 maxRating，系統會傳回 INVALID_ARGUMENT 錯誤。