Premiers pas avec Places Insights

Les fonctions de comptage de lieux sont des requêtes SQL prédéfinies qui s'exécutent dans BigQuery. Elles constituent le moyen recommandé d'interroger l'ensemble de données Places Insights pour récupérer des nombres exacts et des ID de lieu. Bien que vous puissiez également interroger l'ensemble de données directement, les deux méthodes de requête gèrent les seuils de confidentialité et les zones de recherche :

• Les fonctions de comptage de lieux peuvent renvoyer n'importe quel nombre, y compris 0, mais appliquent une zone de recherche minimale de 40,0 mètres sur 40,0 mètres (1 600 m²) (40,0 mètres sur 40,0 mètres / 1 600 m²). Les fonctions renvoient également des ID de lieu, qui peuvent être utilisés pour rechercher des informations sur des lieux individuels, et prennent en charge l'analyse historique des points d'intérêt sur les instantanés mensuels passés à l'aide de filtres de date facultatifs.

• Les requêtes d'ensemble de données de lieux ne peuvent renvoyer que des nombres supérieurs ou égaux à 5 (en omettant les nombres faibles de 0 à 4 pour préserver la confidentialité différentielle), mais n'imposent aucune limite à la taille de la zone de recherche.

Sauf si vous devez effectuer une analyse spatiale complexe, nous vous recommandons de commencer par les fonctions de comptage de lieux telles que PLACES_COUNT_PER_H3. Elle fournit des insights immédiats sur la densité spatiale dans des cellules de grille standardisées, renvoie des ID de lieu pour l'inspection de la vérité terrain et est spécialement conçue pour l'ingénierie des fonctionnalités géospatiales et les modèles de ML.

Sélectionner la fonction de comptage de lieux optimale

Places Insights est compatible avec plusieurs fonctions spatiales. Pour une exécution de requête optimisée, un traitement parallèle et une évolutivité par lot, nous vous recommandons d'utiliser les fonctions suivantes :

• PLACES_COUNT_PER_H3: renvoie une table BigQuery des nombres de lieux par cellule H3. Cette fonction est recommandée pour l'analyse de la densité régionale et la cartographie thermique choroplèthe.
• science PLACES_COUNT_V2: Renvoie une table contenant les nombres de lieux et des exemples d'ID de lieu. Cette fonction accepte un paramètre de table contenant vos zones géographiques d'entrée. En transmettant directement une table entière, le moteur d'exécution BigQuery peut distribuer la charge de travail et traiter les intersections spatiales en parallèle, ce qui permet un traitement par lot très efficace pour l'analyse à grande échelle.
• science PLACES_COUNT_PER_TYPE_V2: Renvoie une table des nombres de lieux et des exemples d'ID de lieu, classés par type de lieu. Comme pour PLACES_COUNT_V2, la transmission de vos zones géographiques d'entrée en tant que paramètre de table permet à BigQuery de paralléliser de manière native les intersections spatiales sur de grands ensembles de données.
• science PLACES_COUNT_CHANGE: renvoie une table des nombres de lieux, ainsi que des ID de lieu ajoutés et supprimés entre deux mois donnés. Comme pour PLACES_COUNT_V2, la transmission de vos zones géographiques d'entrée en tant que paramètre de table permet à BigQuery de paralléliser de manière native les intersections spatiales sur de grands ensembles de données.

En plus des nombres de lieux, ces fonctions renvoient également jusqu'à 250 ID de lieu par élément de la réponse.

Les ID de lieu peuvent être utilisés avec :

• API Places (nouvelle version)
• API Geocoding
• Kit UI pour Places

Exécuter des requêtes avec des fonctions de comptage de lieux

Utilisez le format suivant pour appeler les fonctions : [project name (optional)].[table name].[function name].

Si vous avez modifié le nom de l'ensemble de données associé lors de la configuration de Places Insights, utilisez votre nom personnalisé au lieu des noms de table par défaut. Vous pouvez également inclure votre nom de projet. Si vous n'en incluez pas, la requête est définie par défaut sur le projet actif.

Exemple :

PROJECT_NAME.places_insights___us.PLACES_COUNT_V2

Utilisez un JSON_OBJECT pour transmettre des arguments à la fonction.

Filtrer les résultats de la requête à l'aide de paramètres sensibles à la casse

Les fonctions de comptage de lieux sont compatibles avec de nombreux filtres pour affiner votre recherche. Ces paramètres (par exemple, price_level ou types) sont sensibles à la casse et doivent correspondre exactement aux noms des paramètres. Pour obtenir la liste complète des options, consultez la documentation de référence sur les paramètres de filtre.

Interroger des instantanés historiques avec snapshot_date

Par défaut, les fonctions de comptage de lieux interrogent l'instantané de données le plus récent disponible. Pour analyser les données de lieux telles qu'elles existaient au cours d'un mois passé spécifique, ajoutez le paramètre facultatif snapshot_date à votre JSON_OBJECT.

• Format : YYYY-MM (par exemple, '2026-07').
• Par défaut : si vous l'omettez, la fonction interroge automatiquement le dernier instantané.

L'exemple suivant interroge le nombre de restaurants dans vos zones de recherche, tel qu'il a été enregistré dans l'instantané de juillet 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
  )
);

Dans l'exemple suivant, vous appliquez des filtres pour limiter la recherche par note minimale des utilisateurs, niveau de prix, état de l'établissement et si le restaurant accepte les chiens, à l'aide de la fonction PLACES_COUNT_V2.

Commencez par utiliser votre table de zones géographiques d'entrée ou préparez-en une avec les zones géographiques choisies :

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

Ensuite, appelez PLACES_COUNT_V2 avec la table et l'objet JSON contenant les filtres. Le rayon de recherche est inclus dans les filtres JSON et sera appliqué autour de chaque point de la table 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
      )
);

Exemple : Interroger le nombre de restaurants et les emplacements de marques avec PLACES_COUNT_V2

L'exemple suivant utilise la fonction PLACES_COUNT_V2 avec la table de zones géographiques d'entrée personnalisée my_search_areas pour renvoyer le nombre de restaurants ouverts dans un rayon de 1 000 mètres de l'Empire State Building et de Times Square à New York en juillet 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 réponse est une table BigQuery qui contient le geo_id, la zone géographique, le nombre et un exemple d'ID de lieu.

L'exemple suivant utilise la fonction PLACES_COUNT_V2 pour filtrer par ID de marque spécifiques. Dans cet exemple, nous filtrons les établissements Starbucks à l'aide de l'ID de marque "1413758728321880760".

Pour trouver les ID de marque des marques que vous souhaitez filtrer, interrogez la brands table de votre ensemble de données (par exemple, places_insights___us.brands). Pour en savoir plus sur l'ensemble de données des marques, consultez Écrire une requête à l'aide des données de marques.

Par exemple, pour trouver l'ID de marque de "Starbucks" :

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

Après avoir obtenu les ID de marque, vous pouvez les utiliser dans le filtre brand_ids, comme indiqué dans la requête suivante :

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

Visualiser la sortie de la requête avec les outils Google Cloud

Les outils d'analyse et d'informatique décisionnelle vous aident à découvrir des insights à partir de vos données BigQuery. BigQuery est compatible avec plusieurs outils de visualisation de données Google et tiers que vous pouvez utiliser pour analyser les résultats de vos fonctions sur les données Places Insights.

Pour obtenir un exemple de visualisation des résultats d'une fonction, consultez Visualiser les résultats dans la documentation de référence PLACES_COUNT_PER_H3. Pour en savoir plus sur la visualisation des résultats Places Insights, consultez Visualiser les résultats de la requête.

Limites et exigences des fonctions

Les fonctions de comptage de lieux sont soumises aux limites et exigences suivantes :

• Les fonctions ne sont compatibles qu'avec les insights COUNT.
• Une zone de recherche minimale de 40,0 mètres sur 40,0 mètres (1 600 m²) est requise.
• Limite de taille d'entrée des paramètres : l'objet JSON transmis en tant que paramètre aux fonctions est limité à 1 Mo. L'impact de cette limite dépend de la version de la fonction :
  • Pour les fonctions V2 (PLACES_COUNT_V2, PLACES_COUNT_PER_TYPE_V2, PLACES_COUNT_CHANGE), cette limite ne s'applique qu'à l'objet JSON des filtres. Étant donné que les zones géographiques sont fournies séparément à l'aide d'un paramètre de table, ces fonctions peuvent être mises à l'échelle pour un nombre beaucoup plus important de zones géographiques d'entrée sans atteindre la limite de taille JSON.
  • Pour PLACES_COUNT_PER_H3, PLACES_COUNT, PLACES_COUNT_PER_TYPE, et PLACES_COUNT_PER_GEO, cette limite s'applique à l'ensemble de l'objet JSON, y compris à toutes les définitions de zones géographiques. Cela peut limiter le nombre de zones géographiques pouvant être traitées en un seul appel.
• Aucune prise en charge du filtrage par ID de lieu ou composant d'adresse.
• Vous ne pouvez accéder aux fonctions de comptage de lieux que pour les villes et les pays auxquels vous êtes abonné. Pour savoir comment accéder à l'ensemble de données, consultez Configurer Places Insights pour l'accès aux données.
• Les paramètres de filtre (par exemple, geography ou types) sont sensibles à la casse et doivent correspondre exactement aux noms des paramètres, sinon la requête échouera.