Paramètres de requête

Ce document décrit les paramètres de requête de l'API Places Aggregate et inclut des insights et des bonnes pratiques pour utiliser ce service.

L'API Places Aggregate vous permet d'effectuer plusieurs fonctions clés :

Compter les lieux : déterminez le nombre de lieux qui correspondent à des critères spécifiques , tels que le type de lieu, le statut, le niveau de prix et les notes.
Récupérer les informations sur les lieux : obtenez les noms des lieux qui correspondent aux filtres spécifiés, puis récupérez des informations plus détaillées à l'aide de l' API Places.
Filtrage flexible : appliquez des filtres complets pour obtenir des agrégats précis. Les filtres disponibles sont les suivants :
- Zone géographique (cercle, région ou polygone personnalisé)
- Types de lieu
- Statut
- Niveaux de prix
- Plages de notes

Paramètres obligatoires

Cette section couvre les paramètres obligatoires lors de l'envoi d'une requête à l'API Places Aggregate. Chaque requête doit fournir les éléments suivants :

Un type d'insight.
Un filtre d'emplacement et un filtre de type.

Type de statistiques

Spécifie le type d'insight que vous souhaitez calculer. Les types d'insights suivants sont acceptés :

INSIGHT_COUNT : renvoie le nombre de lieux correspondant aux critères de filtre.
INSIGHT_PLACES : renvoie les ID de lieu correspondant aux critères de filtre.

Filtres

Spécifie les critères de filtrage des lieux. Vous devez au minimum spécifier LocationFilter et TypeFilter.

Filtre d'emplacement

Un filtre d'emplacement peut être l'un des types suivants :

circle : définit une zone sous forme de cercle avec un centre et un rayon.
region : définit une zone sous forme de région.
customArea : définit une zone sous forme de polygone personnalisé.

Cercle

Si vous sélectionnez votre zone géographique sous forme de cercle, vous devez fournir un center et un radius. Le center peut être une latitude et une longitude, ou l'ID de lieu du centre du cercle. Cette méthode permet un filtrage précis et exact en fonction de la région circulaire que vous avez définie.

center:
- latLng : latitude et longitude du centre du cercle. Les latitudes doivent être un nombre compris entre -90 et 90 inclus. Les longitudes doivent être un nombre compris entre -180 et 180 inclus.
- place : ID de lieu du centre du cercle. Notez que seuls les lieux ponctuels sont acceptés. Cette chaîne doit commencer par le préfixe places/.
radius : rayon du cercle en mètres. Ce nombre doit être positif.

Région

Définissez votre zone comme une région en transmettant un ID de lieu au paramètre place. L'ID de lieu représente une zone géographique (par exemple, une zone représentable par un polygone). Par exemple, l'ID de lieu de Tampa, en Floride, est places/ChIJ4dG5s4K3wogRY7SWr4kTX6c. Notez que tous les ID de lieu n'ont pas de géométrie bien définie. Dans ce cas, l'API Places Aggregate renvoie un code d'erreur 400 avec un message indiquant que la région n'est pas acceptée. De plus, pour les régions géographiques complexes, les optimisations de traitement interne peuvent entraîner une légère surestimation de la zone (jusqu'à 2 ou 3 %) qui représente la région.

Important : Lorsque vous utilisez le filtre region avec le type d'insight INSIGHT_PLACES, les requêtes qui incluent des zones contestées sont automatiquement rejetées pour garantir l'exactitude et la neutralité des services Google. Les zones contestées sont des régions dont les limites ou les revendications territoriales sont conflictuelles entre différents pays ou entités. Les limites contestées sont affichées sous forme de ligne grise en pointillés sur Google Maps.

Pour en savoir plus sur l'identification des régions contestées, consultez Comprendre les frontières et les noms des pays.

Pour déterminer si un ID de lieu représente un type de lieu non accepté, transmettez l'ID de lieu dans une requête d'API Geocoding. La réponse inclut le tableau type qui liste les types de lieu associés à l'ID de lieu, tels que locality, neighborhood ou country. Un lieu sera rejeté pour le filtrage par région si l'un de ses types correspond à cette liste.

Les types de lieux non acceptés incluent les suivants :

establishment: indique généralement un lieu qui n'a pas encore été classé.
intersection : indique une intersection majeure, généralement sur deux routes principales.
subpremise: indique une entité adressable en dessous du niveau de l'établissement, telle qu'un appartement, un logement ou une suite.

Zone personnalisée

Définit la zone d'un polygone personnalisé à l'aide de coordonnées de latitude et de longitude.

Vous pouvez accéder à https://geojson.io/ pour dessiner un polygone personnalisé et saisir ces coordonnées dans la requête. Un polygone doit comporter au minimum quatre coordonnées, où la première et la dernière sont identiques. Au moins trois des coordonnées fournies doivent être uniques.

Les coordonnées identiques consécutives seront traitées comme une seule coordonnée. Toutefois, les coordonnées dupliquées non consécutives (autres que les première et dernière coordonnées identiques requises) entraîneront une erreur.

De plus, les bords non adjacents ne sont pas autorisés à se croiser, et les bords d'une longueur de 180 degrés ne sont pas autorisés (c'est-à-dire que les sommets adjacents ne peuvent pas être antipodaux).

Exemple :

"coordinates":[
   {
      "latitude":37.776,
      "longitude":-122.666
   },
   {
      "latitude":37.130,
      "longitude":-121.898
   },
   {
      "latitude":37.326,
      "longitude":-121.598
   },
   {
      "latitude":37.912,
      "longitude":-122.247
   },
   {
      "latitude":37.776,
      "longitude":-122.666
   }
]

Filtre par type

Spécifie les types de lieux à inclure ou à exclure. Pour obtenir la liste des types de lieux primaires et secondaires acceptés par l'API Places Aggregate, consultez le tableau A sous Types de lieux pour l'API Places (nouveau). Vous devez spécifier au moins un type includedTypes ou includedPrimaryTypes.

includedTypes : liste des types de lieux inclus.
excludedTypes : liste des types de lieux exclus.
includedPrimaryTypes : liste des types de lieux primaires inclus.
excludedPrimaryTypes : liste des types de lieux primaires exclus.

Pour en savoir plus sur le fonctionnement des filtres par type et des types de lieux, consultez la section sur les filtres par type.

Remarque : Les filtres par type incluent automatiquement les sous-types des types spécifiés. Par exemple, si vous filtrez par gym, les résultats incluent également les lieux classés dans ses sous-types, tels que yoga_studio.

Paramètres facultatifs

Ces filtres sont facultatifs :

operatingStatus : spécifie les statuts des lieux à inclure ou à exclure. Par défaut, le filtrage s'effectue par operatingStatus: OPERATING_STATUS_OPERATIONAL (une valeur spécifique).
priceLevels : spécifie les niveaux de prix des lieux à inclure. Par défaut, aucun filtrage par niveau de prix n'est appliqué, et tous les lieux (y compris ceux sans informations sur le niveau de prix) sont renvoyés.
ratingFilter : spécifie la plage de notes des lieux. Par défaut, aucun filtrage n'est effectué (toutes les notes sont incluses dans les résultats).

Statut

Avec le filtre operatingStatus, vous pouvez filtrer en fonction du statut tel que OPERATIONAL ou TEMPORARILY_CLOSED. Le comportement du filtre operatingStatus est le suivant :

Si aucun filtre n'a été fourni, seuls les lieux dont le statut est OPERATING_STATUS_OPERATIONAL sont inclus dans les résultats.
Si un ou plusieurs filtres sont fournis, vous devez spécifier des valeurs de statut valides (OPERATING_STATUS_OPERATIONAL, OPERATING_STATUS_PERMANENTLY_CLOSED ou OPERATING_STATUS_TEMPORARILY_CLOSED).

Niveau de prix

Avec le filtre priceLevels, vous pouvez filtrer les lieux en fonction de leur niveau de prix. Les valeurs de niveau de prix valides sont les suivantes : PRICE_LEVEL_FREE, PRICE_LEVEL_INEXPENSIVE, PRICE_LEVEL_MODERATE, PRICE_LEVEL_EXPENSIVE et PRICE_LEVEL_VERY_EXPENSIVE.

Le comportement du filtre priceLevels est le suivant :

Si aucun filtre n'est fourni : tous les lieux sont renvoyés, qu'un niveau de prix leur soit attribué ou non. Cela inclut les lieux sans informations sur le niveau de prix, qui peuvent ne pas être renvoyés lors du filtrage par niveaux de prix spécifiques.
Si un ou plusieurs filtres sont fournis : seuls les lieux correspondant au(x) niveau(x) de prix spécifié(s) sont renvoyés.

Filtre "Note"

Filtre les lieux en fonction de leur note moyenne attribuée par les utilisateurs. Ces deux champs sont facultatifs. S'ils sont omis, ils incluent par défaut les lieux qui n'ont pas de note.

minRating : note moyenne minimale attribuée par les utilisateurs (entre 1,0 et 5,0).
maxRating : note moyenne maximale attribuée par les utilisateurs (entre 1,0 et 5,0).

De plus, la valeur minRating doit toujours être inférieure ou égale à la valeur maxRating. Si minRating est spécifié comme étant supérieur à maxRating, une erreur INVALID_ARGUMENT est renvoyée.