开始使用地点数据分析

地点数量函数是在 BigQuery 中运行的预定义 SQL 查询，是查询地点数据分析数据集以检索确切数量和地点 ID 的推荐方式。虽然您也可以直接查询数据集，但这两种查询方法会处理隐私保护阈值和搜索区域：

  • 地点计数函数可以返回任何数量（包括 0），但会强制执行 40.0 米 x 40.0 米 (1,600 m2) 的最小搜索区域（40.0 米 x 40.0 米 / 1,600 平方米）。这些函数还会返回地点 ID，可用于查找有关各个地点的信息，并支持使用可选的日期过滤条件对过去每月快照进行历史 POI 分析。

  • 地点数据集查询只能返回 5 及以上的数量（省略 0-4 的低数量以保留差分隐私），但对搜索区域的大小没有任何限制。

除非您需要执行复杂的空间分析，否则我们建议您先使用地点计数函数，例如 PLACES_COUNT_PER_H3。它可提供标准化网格单元的即时空间密度数据分析，返回用于实况检查的地点 ID，并且专为地理空间特征工程和机器学习模型而构建。

选择最佳地点数量函数

地点数据分析支持多种空间函数。为了优化查询执行、并行处理和批处理可扩缩性，我们建议使用以下函数：

  • 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 可用于：

使用地点计数函数执行查询

请使用以下格式调用函数：[project name (optional)].[table name].[function name]。

如果您在设置地点数据分析时更改了关联数据集的名称，请使用自定义名称，而不是默认表名称。您还可以选择性地添加项目名称。如果未包含任何项目，查询将默认为有效项目。

例如：

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

使用 JSON_OBJECT 将实参传递给函数。

使用区分大小写的参数过滤查询结果

Places Count 函数支持多种过滤条件，可用于优化搜索。这些参数（例如 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 函数按最低用户评分、价格水平、商家状态以及餐厅是否允许携带宠物来限制搜索结果。

首先，使用您的输入地理位置表，或准备一个包含所选地理位置的表：

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

示例：使用 PLACES_COUNT_V2 查询餐厅数量和品牌位置

以下示例将 PLACES_COUNT_V2 函数与自定义输入地理位置表 my_search_areas 搭配使用，以返回 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 函数的结果。

以下示例使用 PLACES_COUNT_V2 函数按特定品牌 ID 进行过滤。在此示例中，我们使用品牌 ID "1413758728321880760" 过滤 Starbucks 地点。

如需查找要用作过滤条件的品牌的品牌 ID，请查询数据集的 brands 表（例如 places_insights___us.brands）。如需详细了解品牌数据集，请参阅使用品牌数据编写查询。

例如，如需查找“Starbucks”的品牌 ID，请执行以下操作：

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

获取品牌 ID 后，您可以在 brand_ids 过滤条件中使用它们，如以下查询所示：

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_COUNT_PER_H3 参考中的“直观呈现结果”部分。 如需详细了解如何直观呈现地点数据分析结果，请参阅直观呈现查询结果。

功能限制和要求

地点数函数具有以下限制和要求：

  • 这些函数仅支持 COUNT 洞见。
  • 搜索区域的最小面积为 40.0 米 x 40.0 米（1,600 平方米）。（40.0 米 x 40.0 米/1,600 平方米）。
  • 参数输入大小限制：作为参数传递给函数的 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 或地址组成部分进行过滤。
  • 您只能访问已订阅的城市和国家/地区的“地点数量”函数。如需了解如何访问数据集，请参阅设置地点数据分析。
  • 过滤参数（例如 geography 或 types）区分大小写，必须与参数名称完全一致，否则查询将会失败。