Comienza a usar las estadísticas de Places

Las funciones de recuento de lugares son consultas en SQL predefinidas que se ejecutan en BigQuery y son la forma recomendada de consultar el conjunto de datos de Places Insights para recuperar recuentos exactos y los IDs de lugar. Si bien también puedes consultar el conjunto de datos directamente, los dos métodos de consulta controlan los umbrales de privacidad y las áreas de búsqueda:

• Las funciones de recuento de lugares pueden devolver cualquier recuento, incluido 0, pero aplican un área de búsqueda mínima de 40.0 metros por 40.0 metros (1,600 m²). Las funciones también devuelven IDs de lugar, que se pueden usar para buscar información sobre lugares individuales, y admiten el análisis histórico de lugares de interés en instantáneas mensuales anteriores con filtros de fecha opcionales.

• Las consultas de conjuntos de datos de lugares solo pueden mostrar recuentos de 5 o más (se omiten los recuentos bajos de 0 a 4 para preservar la privacidad diferencial), pero no imponen limitaciones en el tamaño del área de búsqueda.

A menos que necesites realizar análisis espaciales complejos, te recomendamos que comiences con funciones de recuento de lugares, como PLACES_COUNT_PER_H3. Proporciona estadísticas inmediatas de densidad espacial en celdas de cuadrícula estandarizadas, devuelve IDs de lugar para la inspección de la verdad fundamental y está diseñado específicamente para la ingeniería de atributos geoespaciales y los modelos de AA.

Selecciona la función de recuento de lugares óptima

Places Insights admite varias funciones espaciales. Para optimizar la ejecución de consultas, el procesamiento paralelo y la escalabilidad por lotes, te recomendamos que uses las siguientes funciones:

• PLACES_COUNT_PER_H3: Devuelve una tabla de BigQuery con los recuentos de lugares por celda H3. Esta función se recomienda para el análisis de densidad regional y los mapas de calor de coropletas.
• science PLACES_COUNT_V2: Devuelve una tabla que contiene recuentos de lugares y IDs de lugar de muestra. Esta función acepta un parámetro de tabla que contiene tus ubicaciones geográficas de entrada. Si pasas una tabla completa directamente, el motor de ejecución de BigQuery puede distribuir la carga de trabajo y procesar las intersecciones espaciales en paralelo, lo que permite un procesamiento por lotes muy eficiente para el análisis a gran escala.
• science PLACES_COUNT_PER_TYPE_V2: Devuelve una tabla de recuentos de lugares y de IDs de lugar de muestra, categorizados por tipo de lugar. Al igual que con PLACES_COUNT_V2, pasar tus geografías de entrada como un parámetro de tabla permite que BigQuery paralelice de forma nativa las intersecciones espaciales en conjuntos de datos grandes.
• science PLACES_COUNT_CHANGE: Devuelve una tabla de recuentos de lugares, además de los IDs de lugar agregados y quitados entre dos meses determinados. Al igual que con PLACES_COUNT_V2, pasar tus geografías de entrada como un parámetro de tabla permite que BigQuery paralelice de forma nativa las intersecciones espaciales en conjuntos de datos grandes.

Junto con los recuentos de lugares, estas funciones también devuelven hasta 250 IDs de lugar por elemento de la respuesta.

Los IDs de lugar se pueden usar con lo siguiente:

• API de Places (nueva)
• API de Geocoding
• Kit de IU de Places

Ejecuta consultas con las funciones de Places Count

Usa el siguiente formato para llamar a las funciones: [project name (optional)].[table name].[function name].

Si cambiaste el nombre del conjunto de datos vinculado cuando configuraste Places Insights, usa tu nombre personalizado en lugar de los nombres de tabla predeterminados. También puedes incluir el nombre de tu proyecto de forma opcional. Si no se incluye uno, la consulta se establece de forma predeterminada en el proyecto activo.

Por ejemplo:

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

Usa un JSON_OBJECT para pasar argumentos a la función.

Filtra los resultados de la consulta con parámetros que distinguen mayúsculas de minúsculas

Las funciones de recuento de lugares admiten muchos filtros para definir mejor tu búsqueda. Estos parámetros (por ejemplo, price_level o types) distinguen mayúsculas de minúsculas y deben coincidir exactamente con los nombres de los parámetros. Para obtener una lista completa de las opciones, consulta la referencia de los parámetros de filtro.

Consulta instantáneas históricas con snapshot_date

De forma predeterminada, las funciones de Places Count consultan la instantánea de datos más reciente disponible. Para analizar los datos de lugares tal como existían durante un mes específico del pasado, agrega el parámetro opcional snapshot_date a tu JSON_OBJECT.

• Formato: YYYY-MM (por ejemplo, '2026-07').
• Predeterminado: Si se omite, la función consulta automáticamente la instantánea más reciente.

En el siguiente ejemplo, se consultan los recuentos de restaurantes alrededor de tus áreas de búsqueda, según se registraron en la instantánea de julio de 2026:

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

En el siguiente ejemplo, aplicarás filtros para limitar la búsqueda por calificación mínima de los usuarios, nivel de precios, estado de la empresa y si el restaurante admite perros, con la función PLACES_COUNT_V2.

Primero, usa tu tabla de datos geográficos de entrada o prepara una con las ubicaciones geográficas elegidas:

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

Luego, llama a PLACES_COUNT_V2 con la tabla y el objeto JSON que contiene los filtros. El radio de búsqueda se incluye en los filtros JSON y se aplicará alrededor de cada punto de la tabla 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
      )
);

Ejemplo: Consulta los recuentos de restaurantes y las ubicaciones de marcas con PLACES_COUNT_V2

En el siguiente ejemplo, se usa la función PLACES_COUNT_V2 con la tabla de geografía de entrada personalizada my_search_areas para devolver la cantidad de restaurantes operativos en un radio de 1,000 metros del Empire State Building y Times Square en la ciudad de Nueva York en julio de 2026:

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

La respuesta es una tabla de BigQuery que contiene el geo_id, la ubicación geográfica, el recuento y una muestra de IDs de lugar.

En el siguiente ejemplo, se usa la función PLACES_COUNT_V2 para filtrar por IDs de marca específicos. En este ejemplo, filtramos las ubicaciones de Starbucks con el ID de marca "1413758728321880760".

Para encontrar los IDs de las marcas por las que deseas filtrar, consulta la tabla brands de tu conjunto de datos (por ejemplo, places_insights___us.brands). Para obtener más información sobre el conjunto de datos de marcas, consulta Escribe una consulta con datos de marcas.

Por ejemplo, para encontrar el ID de marca de "Starbucks", haz lo siguiente:

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

Después de obtener los IDs de marca, puedes usarlos en el filtro brand_ids, como se muestra en la siguiente consulta:

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

Visualiza el resultado de la consulta con las herramientas de Google Cloud

Las herramientas de análisis y de inteligencia empresarial te ayudan a descubrir estadísticas de tus datos de BigQuery. BigQuery admite varias herramientas de visualización de datos de Google y de terceros que puedes usar para analizar los resultados de tus funciones en los datos de Places Insights.

Para ver un ejemplo de cómo visualizar los resultados de una función, consulta Visualiza los resultados en la referencia de PLACES_COUNT_PER_H3. Para obtener más información sobre cómo visualizar los resultados de Places Insights, consulta Visualiza los resultados de las consultas.

Limitaciones y requisitos de las funciones

Las funciones de recuento de lugares tienen las siguientes limitaciones y requisitos:

• Las funciones solo admiten estadísticas de COUNT.
• Se requiere un área de búsqueda mínima de 40.0 metros por 40.0 metros (1,600 m²).
• Límite de tamaño de entrada de parámetros: El objeto JSON que se pasa como parámetro a las funciones está limitado a 1 MB. El impacto de este límite depende de la versión de la función:
  • Para las funciones de la versión 2 (PLACES_COUNT_V2, PLACES_COUNT_PER_TYPE_V2 y PLACES_COUNT_CHANGE), este límite solo se aplica al objeto JSON de filtros. Dado que las zonas geográficas se proporcionan por separado con un parámetro de tabla, estas funciones pueden escalar a una cantidad mucho mayor de zonas geográficas de entrada sin alcanzar el límite de tamaño de JSON.
  • Para PLACES_COUNT_PER_H3, PLACES_COUNT, PLACES_COUNT_PER_TYPE y PLACES_COUNT_PER_GEO, este límite se aplica a todo el objeto JSON, incluidas todas las definiciones de ubicación geográfica. Esto puede limitar la cantidad de ubicaciones geográficas que se pueden procesar en una sola llamada.
• No se admite el filtrado por ID de lugar ni por componente de dirección.
• Solo puedes acceder a las funciones de Places Count para las ciudades y los países a los que te suscribiste. Consulta Configura Places Insights para obtener acceso al conjunto de datos.
• Los parámetros de filtro (por ejemplo, geography o types) distinguen mayúsculas de minúsculas y deben coincidir exactamente con los nombres de los parámetros; de lo contrario, la consulta fallará.