要求參數

本文件將清楚說明 Places Insights API。以下我們將詳細說明各個項目，提供洞察資訊並做出最佳選擇 導入這項工具的做法，滿足您的地理資料需求。

Places Insights API 可讓您執行以下幾個重要功能：

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

必要參數

本節說明向 Places Insights API。每項要求都必須提供以下資訊：

  • 一種深入分析。
  • 位置篩選器和類型篩選器。

深入分析

指定您要計算的深入分析結果類型。下列洞察類型 支援：

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

注意：如果選取這個選項，Places Insights API 會傳回地點 ID 只有在 count 等於或小於 100 時才能使用。

篩選器

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

位置篩選器

地區篩選器可以是下列其中一種類型：

  • circle：將區域定義為包含中心和半徑的圓形區域。
  • region：將區域定義為區域。
  • custom_area：將區域定義為自訂多邊形。
圓形

如果選取您的地理區域做為圓形，則必須提供 center 以及 radius。中心點可以是經緯度，也可以是地點 圓心的 ID。

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

您可以使用 place 參數，將區域定義為區域。使用地點 ID 代表地理區域 (例如 多邊形)。以 Tampa 為例，佛羅裡達州 places/ChIJ4dG5s4K3wogRY7SWr4kTX6c。

不支援的區域類型
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark subpremise

您可以使用 Geocoding API 呼叫中的 types 欄位來判斷 與地點 ID 相關聯的地點或地址類型，例如地點是否為 城市、社區或國家/地區。

自訂區域

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

您可以前往 https://geojson.io/ 繪製自訂多邊形， 在請求中輸入這些座標多邊形至少要有 4 座標，其中第一個和最後一個座標相同。除 第一個和最後一個座標，不得包含其他重複的座標。 例如：

"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 的地點類型指南 (新功能)。至少須有一個 included_types 或 included_primary_types 類型 包含。

  • included_types：包含的地點類型清單。
  • excluded_types：排除的地點類型清單。
  • included_primary_types：包含的主要地點類型清單。
  • excluded_primary_types：排除的主要地點類型清單。

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

選用參數

其餘三個是選用篩選器：

  • operating_status：指定要納入或排除的地點狀態。 預設為依operating_status: OPERATING_STATUS_OPERATIONAL篩選 (單一特定值)。
  • price_levels：指定地點的價位。預設為否 篩選 (所有價格等級都會納入結果)。
  • rating_filter：指定地點的評分範圍。預設為否 篩選 (結果會包含所有評分)。

營業狀態

依據作業狀態 (例如營運或暫時) 篩選 已關閉)。

價格等級

依價格等級篩選 (例如免費、中等或高價)。

評分篩選器

依使用者平均評分篩選地點。這兩個欄位都是 選擇性。如果沒有的話，系統預設會一併收錄地點。 不會顯示評分資料

  • min_rating：最低平均使用者評分 (介於 1.0 到 5.0 之間)。
  • max_rating：平均使用者評分上限 (介於 1.0 到 5.0 之間)。