要求參數

本文說明 Places Aggregate API 的要求參數，並提供使用這項服務的深入分析和最佳做法。

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

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

必要參數

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

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

洞察類型

指定要計算的洞察類型。支援的洞察類型如下：

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

篩選器

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

位置篩選器

位置篩選器可分為下列類型：

  • circle：定義圓形區域，包含圓心和半徑。
  • region：將某個區域定義為區域。
  • customArea：將區域定義為自訂多邊形。
圓形

如果選取圓形做為地理區域，則必須提供 center 和 radius。center 可以是經緯度，也可以是圓心的地點 ID。這種方法可根據您定義的圓形區域，精準篩選資料。

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

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

如要判斷地點 ID 是否代表不支援的地點類型，請在 Geocoding API 要求中傳遞地點 ID。回應包含 type 陣列，列出與地點 ID 相關聯的地點類型，例如 locality、neighborhood 或 country。如果地點的任一類型與這份清單相符，就會遭到區域篩選器拒絕。

不支援的地點類型包括：

  • establishment：通常表示尚未歸類的地點。
  • intersection：表示主要的十字路口，通常有兩條主要道路交會。
  • subpremise：表示建築物層級以下的定址實體，例如公寓、單位或套房。
自訂區域

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

您可以前往 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 Aggregate API 支援的主要和次要地點類型清單，請參閱 Places API (新版) 的「地點類型」下方的表 A。您必須指定至少一個 includedTypes 或 includedPrimaryTypes 類型。

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

如要進一步瞭解類型篩選器和地點類型的運作方式，請參閱類型篩選器的詳細說明。

選用參數

這些篩選器為選用項目：

  • operatingStatus：指定要納入或排除的地點狀態。預設為依 operatingStatus: OPERATING_STATUS_OPERATIONAL (一個特定值) 篩選。
  • priceLevels：指定要納入的地點價格等級。根據預設，系統不會套用任何價格等級篩選條件，並會傳回所有地點 (包括沒有價格等級資訊的地點)。
  • ratingFilter：指定地點的評分範圍。預設為不篩選 (結果會包含所有分級)。

營業狀態

使用 operatingStatus 篩選器，即可根據營業狀態 (例如 OPERATIONAL 或 TEMPORARILY_CLOSED) 進行篩選。operatingStatus 篩選器的運作方式如下：

  • 如果未提供篩選條件，結果只會包含營業狀態為 OPERATING_STATUS_OPERATIONAL 的地點。
  • 如要提供一或多個篩選器，請務必指定有效的營業狀態值 (OPERATING_STATUS_OPERATIONAL、OPERATING_STATUS_PERMANENTLY_CLOSED 或 OPERATING_STATUS_TEMPORARILY_CLOSED)。

價格等級

您可以使用 priceLevels 篩選器，根據價格等級篩選地點。有效的價格等級值為：PRICE_LEVEL_FREE、PRICE_LEVEL_INEXPENSIVE、PRICE_LEVEL_MODERATE、PRICE_LEVEL_EXPENSIVE 和 PRICE_LEVEL_VERY_EXPENSIVE。

priceLevels 篩選器的行為如下：

  • 如未提供篩選條件：無論是否已指派價格等級，系統都會傳回所有地點。包括沒有價位資訊的地點，依特定價位篩選時，可能不會傳回這類地點。
  • 如果提供一或多個篩選條件：只會傳回符合指定價格等級的地點。

評分篩選器

根據平均使用者評分篩選地點。這兩個欄位都是選填，如果省略，預設也會納入沒有評分的場所。

  • minRating：使用者平均評分下限 (介於 1.0 和 5.0 之間)。
  • maxRating：使用者平均評分上限 (介於 1.0 和 5.0 之間)。

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