要求參數

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

您可以使用 Places Aggregate API 執行下列幾項重要功能：

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

必要參數

本節說明向 Places Aggregate 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 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 錯誤。