Interroger l'ensemble de données à l'aide des fonctions Places Count

Les fonctions de dénombrement des lieux sont des requêtes SQL prédéfinies qui s'exécutent dans BigQuery et qui sont complémentaires à l'interrogation directe de l'ensemble de données. La principale différence entre l'interrogation directe des données et l'utilisation d'une fonction est que les fonctions n'appliquent pas de seuil de nombre minimal, mais plutôt une zone de recherche minimale :

• Les requêtes sur les ensembles de données de lieux ne peuvent renvoyer que des nombres supérieurs ou égaux à 5, mais n'imposent aucune limite à la taille de la zone de recherche.
• Les fonctions Places Count peuvent renvoyer n'importe quel nombre, y compris 0, mais imposent une zone de recherche minimale de 40 mètres sur 40 mètres (1 600 m²). Les fonctions peuvent également renvoyer des ID de lieux, qui peuvent être utilisés pour rechercher des informations sur des lieux spécifiques.

Vous pouvez utiliser les fonctions de nombre de lieux si vous avez besoin de savoir quand une requête ne renvoie aucun résultat ou si vous avez besoin de connaître les nombres de lieux inférieurs à 5. Il est également utile si vous avez besoin d'obtenir des informations sur un lieu spécifique pour vérifier vos résultats.

Les fonctions de nombre de lieux ne fournissent que des nombres. Si vous devez effectuer des requêtes plus complexes, comme des jointures de données, ou obtenir des insights supplémentaires, comme la note moyenne d'un groupe de lieux, interrogez directement l'ensemble de données.

Fonctions et pays acceptés pour le nombre de lieux

Places Insights est compatible avec les fonctions suivantes :

• science PLACES_COUNT_V2 : renvoie un tableau contenant le nombre de lieux et des exemples d'ID de lieux. Cette fonction accepte un paramètre de table pour les entrées multirégionales, ce qui permet un traitement par lot efficace. Elle est fortement optimisée pour les jointures géospatiales par rapport aux fonctions PLACES_COUNT et PLACES_COUNT_PER_GEO.
• science PLACES_COUNT_PER_TYPE_V2 : Renvoie un tableau des nombres de lieux et des exemples d'ID de lieux, classés par type de lieu. Comme PLACES_COUNT_V2, cette fonction accepte un paramètre de tableau pour traiter plusieurs zones géographiques d'entrée simultanément. Cette architecture permet un traitement par lot efficace et fournit une jointure géospatiale optimisée par rapport à PLACES_COUNT_PER_TYPE.
• PLACES_COUNT_PER_H3 : renvoie une table BigQuery du nombre de lieux par cellule H3.
• PLACES_COUNT : renvoie une seule ligne contenant le nombre de lieux.
• PLACES_COUNT_PER_TYPE : renvoie une table BigQuery du nombre de lieux par type de lieu.
• PLACES_COUNT_PER_GEO : renvoie une table BigQuery du nombre de lieux par zone géographique.

En plus du nombre de lieux, toutes les fonctions, à l'exception de PLACES_COUNT, renvoient également jusqu'à 250 ID de lieux par élément de la réponse.

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

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

Écrire des requêtes avec des fonctions

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 tables par défaut listés dans Fonctions de référence pour le nombre de lieux dans BigQuery. Vous pouvez également inclure le nom de votre projet (facultatif). Si aucun n'est inclus, la requête sera définie par défaut sur le projet actif.

Exemple :

PROJECT_NAME.places_insights___us.PLACES_COUNT

Utilisez JSON_OBJECT pour transmettre des arguments à la fonction.

Filtrer vos résultats

Les fonctions "Nombre de lieux" sont compatibles avec de nombreux filtres permettant d'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. Consultez la documentation de référence sur les paramètres de filtre pour obtenir la liste complète des options.

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 autorise les chiens, à l'aide de la fonction PLACES_COUNT_V2.

Commencez par utiliser votre tableau de géographie d'entrée ou préparez-en un 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
);

Appelez ensuite PLACES_COUNT_V2 avec le tableau et l'objet JSON contenant les filtres. Le rayon de recherche est inclus dans les filtres JSON et sera appliqué autour de chaque point du tableau 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 de la fonction "Nombre de lieux"

L'exemple suivant utilise la fonction PLACES_COUNT_V2 avec la table de géographie d'entrée personnalisée my_search_area pour renvoyer le nombre de restaurants opérationnels situés à moins de 1 000 mètres de l'Empire State Building et de Times Square à New York :

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

La réponse est une table BigQuery qui contient geo_id, la zone géographique, le nombre et un échantillon d'ID de lieux.

Visualiser les résultats

Les outils d'analyse et d'informatique décisionnelle sont essentiels pour vous aider à découvrir des insights à partir de vos données BigQuery. BigQuery est compatible avec plusieurs outils de visualisation des 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. Pour en savoir plus et obtenir un exemple de visualisation des résultats Places Insights, consultez Visualiser les résultats de requête.

Limites et exigences

Les fonctions de comptage des lieux présentent les limites et exigences suivantes :

• Seuls les insights COUNT sont acceptés.
• Une zone de recherche minimale de 40 mètres sur 40 mètres (1 600 m²) est requise.
• Taille limite des paramètres d'entrée : 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), cette limite s'applique uniquement à 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 s'adapter à 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 géographiques. Cela peut limiter le nombre de zones géographiques pouvant être traitées en un seul appel.
• Le filtrage par ID de lieu, marques, options de recharge de véhicules électriques ou composant d'adresse n'est pas disponible.
• Vous ne pouvez accéder aux fonctions de décompte des lieux que pour les villes et les pays auxquels vous êtes abonné. Pour accéder aux ensembles de données, consultez Configurer Places Insights.
• Les paramètres de filtre (par exemple, geography ou types) sont sensibles à la casse et doivent correspondre exactement aux noms des paramètres, sous peine de voir la requête échouer.

Fonctions de comptage des lieux de référence dans BigQuery

Toutes les villes de l'ensemble de données échantillon et tous les pays de l'ensemble de données complet sont compatibles avec les fonctions de décompte des lieux.

Vous avez accès aux fonctions "Nombre de lieux" correspondant aux ensembles de données sur les villes et les pays auxquels vous êtes abonné. Pour accéder aux ensembles de données, consultez Configurer Places Insights.

Ces tableaux listent les villes et pays disponibles, ainsi que les noms de tables correspondants.

Exemple de données

Données complètes