開始使用 Places Insights

地點計數函式是在 BigQuery 中執行的預先定義 SQL 查詢，建議您使用這類函式查詢 Places Insights 資料集，以擷取確切的計數和地點 ID。您也可以直接查詢資料集，但這兩種查詢方法會處理隱私權門檻和搜尋區域：

• Places Count 函式可傳回任何數量 (包括 0)，但會強制執行 40.0 公尺 x 40.0 公尺 (1600 m²) 的最小搜尋區域 (40.0 公尺 x 40.0 公尺 / 1,600 m²)。函式也會傳回地點 ID，可用於查詢個別地點的資訊，並支援使用選用日期篩選器，分析過去每月快照中的歷史搜尋點。

• 地點資料集查詢只會傳回 5 以上的計數 (為維護差異化隱私，會省略 0 到 4 的低計數)，但不會對搜尋區域大小強制設限。

除非您需要執行複雜的空間分析，否則建議先使用地點計數函式，例如 PLACES_COUNT_PER_H3。這項服務可針對標準化格狀單元提供即時空間密度洞察資料、傳回地點 ID 以供真值檢查，並專為地理空間特徵工程和機器學習模型而設計。

這項產品或功能目前處於預先發布階段，也就是正式發布前的版本。我們對於正式發布前的產品和功能僅提供有限度的支援。此外，這類產品和功能的變更可能與其他正式發布前版本不相容。正式發布前產品/功能受到《Google 地圖平台服務專屬條款》規範，詳情請參閱推出階段說明。

選取最佳的「地點數量」函式

Places Insights 支援多種空間函式。為提升查詢執行作業、平行處理和批次可擴充性，建議使用下列函式：

• PLACES_COUNT_PER_H3： 傳回每個 H3 格位地點數量的 BigQuery 資料表。建議使用此函式進行區域密度分析和等值線熱度圖。
• PLACES_COUNT_V2：傳回包含地點計數和地點 ID 範例的資料表。這個函式會接受包含輸入地理區域的表格參數。直接傳遞整個資料表後，BigQuery 執行引擎就能分配工作負載，並行處理空間交集，進而對大規模分析作業進行高效率的批次處理。
• PLACES_COUNT_PER_TYPE_V2： 傳回地點數量和範例地點 ID 的表格，並依地點類型分類。與 PLACES_COUNT_V2 類似，將輸入地理位置做為資料表參數傳遞，可讓 BigQuery 在大型資料集之間，以原生方式平行處理空間交集。
• PLACES_COUNT_CHANGE： 傳回地點數量表，以及兩個指定月份之間新增和移除的地點 ID。與 PLACES_COUNT_V2 類似，將輸入地理區域做為資料表參數傳遞，可讓 BigQuery 在大型資料集之間，以原生方式平行處理空間交集。

除了地點計數，這些函式也會針對回應的每個元素，傳回最多 250 個地點 ID。

地點 ID 可用於：

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

注意： 您可以存取您有權存取的相同城市和國家/地區的「地點數量」函式。

使用地點計數函式執行查詢

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

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

例如：

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

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

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

使用區分大小寫的參數篩選查詢結果

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

使用 snapshot_date 查詢歷史快照

根據預設，地點計數函式會查詢可用的最新資料快照。 如要分析特定月份的商家資料，請在 JSON_OBJECT 中加入選用的 snapshot_date 參數。

• 格式： YYYY-MM (例如 '2026-07')。
• 預設：如果省略，函式會自動查詢最新快照。

以下範例會查詢 2026 年 7 月快照中記錄的搜尋區域附近餐廳數量：

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"],
      'snapshot_date', '2026-07' -- Optional historical snapshot month
  )
);

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

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

重要事項： 您必須在與已連結的 Places Insights 資料集相同的區域中，建立包含輸入地理區域資料表的資料集。如果位置不相符，BigQuery 會傳回錯誤。

-- 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
      )
);

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

範例：使用 PLACES_COUNT_V2 查詢餐廳數量和品牌位置

以下範例會搭配自訂輸入地理位置資料表 my_search_areas 使用 PLACES_COUNT_V2 函式，傳回 2026 年 7 月在紐約市帝國大廈和時代廣場 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"],
      'snapshot_date', '2026-07'
      )
);

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

下列範例使用 PLACES_COUNT_V2 函式，依特定品牌 ID 進行篩選。在本範例中，我們使用品牌 ID "1413758728321880760" 篩選星巴克門市。

如要找出要篩選的品牌 ID，請查詢資料集的 brands 資料表 (例如 places_insights___us.brands)。如要進一步瞭解品牌資料集，請參閱「使用品牌資料編寫查詢」。

舉例來說，如要找出「Starbucks」的品牌 ID，請按照下列步驟操作：

SELECT id, name
FROM `PROJECT_NAME.places_insights___us.brands`
WHERE name = "Starbucks"

取得品牌 ID 後，您可以在 brand_ids 篩選器中使用這些 ID，如下列查詢所示：

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'],
      'brand_ids', ["1413758728321880760"]
      )
);

注意： 每個地點計數函式的必要和選用參數都不同，詳情請參閱篩選器。

使用 Google Cloud 工具以視覺化方式呈現查詢輸出內容

分析和商業智慧工具可協助您從 BigQuery 資料發掘洞察資訊。BigQuery 支援多種 Google 和第三方資料視覺化工具，可用於分析 Places Insights 資料的函式結果。

如要查看函式結果的視覺化範例，請參閱「在 PLACES_COUNT_PER_H3 參照中顯示結果」。如要進一步瞭解如何以圖表呈現 Places Insights 結果，請參閱以圖表呈現查詢結果。

功能限制和需求

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

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