使用地點計數函式查詢資料集

地點計數函式是預先定義的 SQL 查詢，會在 BigQuery 中執行，並直接查詢資料集。直接查詢資料與使用函式的主要差異在於，函式不會強制執行最低計數門檻，而是強制執行最低搜尋區域：

• 地點資料集查詢只能傳回 5 個以上的計數，但不會對搜尋區域的大小設下限制。
• 地點計數函式可以傳回任何計數 (包括 0)，但會強制執行 40.0 公尺 x 40.0 公尺 (1600 公尺²) 的最小搜尋範圍。函式也會傳回地點 ID，可用於查詢個別地點的資訊。

如果想知道查詢何時沒有傳回結果，或需要瞭解低於 5 的地點數量，您可能會想使用地點數量函式。如果您需要取得個別地點資訊來檢查結果，這項功能也相當實用。

地點計數函式只會提供計數，因此如要執行更複雜的查詢 (例如資料聯結)，或取得其他洞察資料 (例如一組地點的平均評分)，請直接查詢資料集。

支援的地點計數函式和國家/地區

地點洞察資料支援下列功能：

• PLACES_COUNT：傳回單一資料列，其中包含地點的計數。
• PLACES_COUNT_PER_TYPE：傳回 BigQuery 資料表，其中包含各類地點的數量。
• PLACES_COUNT_PER_GEO：傳回每個地理區域的場所計數 BigQuery 資料表。
• PLACES_COUNT_PER_H3：傳回每個 H3 儲存格的位置計數 BigQuery 資料表。

除了地點計數外，PLACES_COUNT_PER_TYPE、PLACES_COUNT_PER_GEO 和 PLACES_COUNT_PER_H3 函式也會針對回應的每個元素，傳回最多 250 個地點 ID。查看所有篩選參數。

地點 ID 可用於：

• Places API (新版)
• Geocoding API
• Places UI Kit

注意： 您可以存取您有權存取的城市和國家/地區的場所數量函式。

使用函式撰寫查詢

請使用下列格式呼叫函式：[project name (optional)].[table name].[function name]。

如果您在設定地點洞察時變更了連結的資料集名稱，請使用自訂名稱，不要使用這裡列出的預設資料表名稱。您也可以選擇加入專案名稱。如果未納入，查詢會預設為使用有效專案。

例如：

PROJECT_NAME.places_insights___us.PLACES_COUNT

使用 JSON_OBJECT 將引數傳遞至函式。

注意： 使用地點計數函式時，函式會指定於 FROM 子句，並省略 WITH_AGGREGATION_THRESHOLD。

篩選結果

地點計數函式支援多種篩選條件，可縮小搜尋範圍。這些參數 (例如 price_level 或 types) 會區分大小寫，且必須與參數名稱完全相符。如需完整選項清單，請參閱篩選參數參考資料。

在下一個範例中，您會套用篩選條件，依最低使用者評分、價格等級、商家狀態，以及餐廳是否允許攜帶狗隻，限制搜尋範圍：

SELECT `PROJECT_NAME.places_insights___us.PLACES_COUNT`(
  JSON_OBJECT(
      'geography', ST_GEOGPOINT(-73.9857, 40.7484), -- Empire State Building
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'min_rating', 1.3,
      'price_level', ['PRICE_LEVEL_INEXPENSIVE', 'PRICE_LEVEL_MODERATE'],
      'allows_dogs', TRUE
      )
) as count;

注意： 請加入 business_status 篩選器，確保取得 OPERATIONAL 商家數量。否則，計數會包含已關閉的商家。

地點計數函式範例

以下範例使用 PLACES_COUNT 函式，傳回紐約市帝國大廈方圓 1000 公尺內營業中的餐廳數量：

SELECT `PROJECT_NAME.places_insights___us.PLACES_COUNT`(
  JSON_OBJECT(
      'geography', ST_GEOGPOINT(-73.9857, 40.7484), -- Empire State Building
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"]
      )
) as count;

回覆內容會包含單一計數：

這個範例使用 BigQuery ST_GEOGPOINT 函式，從點傳回 GEOGRAPHY 值，然後將該值傳遞至 geography 參數。此外，系統也會傳遞該點周圍的搜尋半徑和地點類型 "restaurant"，以供搜尋。

注意： 如篩選器所述，每個地點計數函式的必要和選用參數都不同。

每個類型、地理區域或 H3 的地點數量範例

除了地點計數外，PLACES_COUNT_PER_TYPE、PLACES_COUNT_PER_GEO 和 PLACES_COUNT_PER_H3 函式也會傳回最多 250 個地點 ID，這些地點會納入回應中。

舉例來說，PLACES_COUNT_PER_TYPE 函式會傳回每個地點類型的地點數量資料表。回應中會包含與各類型相符的地點 ID 陣列。您可以使用傳回的地點 ID 查詢每個地點的資訊。

下列函式呼叫會傳回類型為 restaurant、cafe 和 bar 的地點數量：

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_PER_TYPE`(
  JSON_OBJECT(
      'geography', ST_GEOGPOINT(-73.9857, 40.7484), -- Empire State Building
      'geography_radius', 1000, -- Radius in meters
      'types', ["restaurant", "cafe", "bar"],
      'business_status', ['OPERATIONAL']
      )
);

這個函式會傳回含有三個資料欄的資料表：type、count 和 sample_place_ids。「count」欄會顯示每個 type 的地點數量，「sample_place_ids」欄則會顯示每個 type 最多 250 個地點 ID。

注意： 如要取得地點資訊，請使用地點 ID 呼叫 Places API 或 Places UI 工具包。使用範例地點 ID 驗證地點洞察資料提供相關範例。

以視覺化方式呈現結果

分析和商業智慧工具對於發掘 BigQuery 資料的洞察資訊至關重要。BigQuery 支援多種 Google 和第三方資料視覺化工具，可用於分析地點洞察資料的函式結果。

如要查看函式結果的視覺化範例，請參閱「將結果視覺化」。如要進一步瞭解如何以視覺化方式呈現地點洞察結果，請參閱「以視覺化方式呈現查詢結果」。

限制與需求

地點計數函式有下列限制和規定：

• 系統僅支援 COUNT 深入分析。
• 搜尋區域至少須為 40.0 公尺 x 40.0 公尺 (1600 公尺²)。
• 地點函式計數參數的輸入大小上限為 1 MB。
• 不支援依地點 ID、品牌、電動車充電選項或地址元件篩選。
• 您只能存取已訂閱城市和國家/地區的場所數量函式。如要存取資料集，請參閱「設定地點洞察」。
• 篩選器參數 (例如 geography 或 types) 區分大小寫，且必須與參數名稱完全相符，否則查詢會失敗。