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

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

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

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

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

支援「地點數量」函式的國家/地區

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

• science PLACES_COUNT_V2：傳回包含地點計數和地點 ID 範例的表格。這個函式接受多個地理位置的輸入內容，並以表格參數的形式傳遞，可有效進行批次處理。相較於 PLACES_COUNT 和 PLACES_COUNT_PER_GEO 函式，這項函式經過高度最佳化，可執行地理空間聯結。
• science PLACES_COUNT_PER_TYPE_V2： 傳回地點數量和範例地點 ID 的表格，並依地點類型分類。與 PLACES_COUNT_V2 類似，這個函式會接受表格參數，同時處理多個輸入地理位置。這個架構支援有效率的批次處理，並提供比 PLACES_COUNT_PER_TYPE 更優化的地理空間聯結。
• PLACES_COUNT_PER_H3：傳回每個 H3 格位中地點數量的 BigQuery 資料表。
• PLACES_COUNT：傳回單一資料列，其中包含地點的計數。
• PLACES_COUNT_PER_TYPE：傳回 BigQuery 資料表，其中包含各類地點的數量。
• PLACES_COUNT_PER_GEO：傳回每個地理區域的場所計數 BigQuery 資料表。

除了地點計數外，除了 PLACES_COUNT 以外的所有函式，也會針對回應的每個元素傳回最多 250 個地點 ID。

地點 ID 可用於：

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

使用函式撰寫查詢

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

如果您在設定地點洞察時變更了連結的資料集名稱，請使用自訂名稱，而非在 BigQuery 中參照地點計數函式列出的預設資料表名稱。您也可以選擇加入專案名稱。如未加入專案，查詢會預設為使用有效專案。

例如：

PROJECT_NAME.places_insights___us.PLACES_COUNT

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

篩選結果

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

在下一個範例中，您將使用 PLACES_COUNT_V2 函式套用篩選器，依最低使用者評分、價格等級、商家狀態，以及餐廳是否允許攜帶狗隻，限制搜尋結果。

首先，請使用輸入地理位置表格，或準備一個包含所選地理位置的表格：

-- Create a table for the input geographies
CREATE TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas` AS (
  SELECT
    '1' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9857, 40.7484) AS geo -- Empire State Building
  UNION ALL
  SELECT
    '2' AS geo_id, -- Unique identifier
    ST_GEOGPOINT(-73.9851, 40.7580) AS geo -- Times Square
);

接著，使用表格和包含篩選器的 JSON 物件呼叫 PLACES_COUNT_V2。搜尋半徑會納入 JSON 篩選器，並套用至 my_search_areas 表格中的每個點。

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters around each point in 'geo'
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"],
      'min_rating', 1.3,
      'price_level', ['PRICE_LEVEL_INEXPENSIVE', 'PRICE_LEVEL_MODERATE'],
      'allows_dogs', TRUE
      )
);

地點計數函式範例

以下範例會搭配自訂輸入地理位置資料表 my_search_area 使用 PLACES_COUNT_V2 函式，傳回紐約市帝國大廈和時代廣場方圓 1000 公尺內的營業餐廳數量：

SELECT * FROM `PROJECT_NAME.places_insights___us.PLACES_COUNT_V2`(
  TABLE `PROJECT_NAME.YOUR_DATASET.my_search_areas`,
  JSON_OBJECT(
      'geography_radius', 1000, -- Radius in meters
      'business_status', ['OPERATIONAL'],
      'types', ["restaurant"]
      )
);

回應是 BigQuery 資料表，內含 geo_id、地理位置、計數和地點 ID 樣本。

以視覺化方式呈現結果

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

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

限制與需求

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

• 系統僅支援 COUNT 深入分析。
• 搜尋區域至少須為 40.0 公尺 x 40.0 公尺 (1600 公尺²)。
• 參數輸入大小限制：傳遞至函式的 JSON 物件大小上限為 1 MB。這項限制造成的影響取決於函式版本：
• 如果是 V2 函式 (PLACES_COUNT_V2、PLACES_COUNT_PER_TYPE_V2)，這項限制只適用於篩選器 JSON 物件。由於地理區域是使用表格參數另外提供，因此這些函式可擴充至更多輸入地理區域，不會達到 JSON 大小限制。
  • 如果是 PLACES_COUNT_PER_H3、PLACES_COUNT、PLACES_COUNT_PER_TYPE 和 PLACES_COUNT_PER_GEO，這項限制適用於整個 JSON 物件，包括所有地理位置定義。這可能會限制單一通話中可處理的地理區域數量。
• 不支援依地點 ID、品牌、電動車充電選項或地址元件篩選。
• 您只能存取已訂閱城市和國家/地區的「地點數量」函式。如要存取資料集，請參閱「設定地點洞察」。
• 篩選器參數 (例如 geography 或 types) 區分大小寫，且必須與參數名稱完全相符，否則查詢會失敗。

在 BigQuery 中參考地點計數函式

樣本資料集中的所有城市，以及完整資料集中的所有國家/地區，都支援地點計數函式。

您可以存取與訂閱的城市和國家/地區資料集相應的「地點數量」函式。如要存取資料集，請參閱「設定 Places Insights」。

這些表格列出可用的城市、國家/地區，以及對應的表格名稱。

範例資料

完整資料