Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

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 d'établissement, l'état de fonctionnement, le niveau de prix et les notes.
Récupérer des détails sur un lieu : 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 décrit les paramètres requis lors de l'envoi d'une requête à l'API Places Aggregate. Chaque requête doit fournir les éléments suivants :

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 filtrage.
INSIGHT_PLACES : renvoie les ID de lieu correspondant aux critères de filtrage.

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 de l'un des types suivants :

circle : définit une zone sous la forme d'un cercle avec un centre et un rayon.
region : définit une zone en tant que région.
customArea : définit une zone sous la forme d'un polygone personnalisé.

Cercle

Si vous sélectionnez votre zone géographique sous forme de cercle, vous devez fournir un center et un radius. 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. La longitude doit ê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 en tant que 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 une 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 prise en charge. De plus, pour les régions géographiques complexes, les optimisations de traitement interne peuvent entraîner une légère surapproximation de la zone (jusqu'à 2 à 3 %) qui représente la région.

Important : Lorsque vous utilisez le filtre region avec le type d'insight INSIGHT_PLACES, les requêtes incluant 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 frontières ou les revendications territoriales sont contestées par différents pays ou entités. Les frontières contestées sont représentées par une ligne grise en traits interrompus 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 compatible, transmettez-le dans une requête de l'API Geocoding. La réponse inclut le tableau type listant les types de lieux 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.

Types de lieux non acceptés :

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 du bâtiment, comme un appartement, une unité 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 moins quatre coordonnées, dont la première et la dernière sont identiques. Au moins trois des coordonnées fournies doivent être uniques.

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

De plus, les arêtes non adjacentes ne sont pas autorisées à se croiser, et les arêtes d'une longueur de 180 degrés ne sont pas autorisées (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 de type

Spécifie les types de lieux à inclure ou à exclure. Pour obtenir la liste des types de lieux principaux et secondaires compatibles avec l'API Places Aggregate, consultez le tableau A sous Types de lieux pour l'API Places (New). 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 principaux inclus.
excludedPrimaryTypes : liste des types de lieux principaux exclus.

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

Remarque : Les filtres de 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, comme yoga_studio.

Paramètres facultatifs

Ces filtres sont facultatifs :

operatingStatus : spécifie les états 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 appliqué (toutes les notes sont incluses dans les résultats).

Statut

Le filtre operatingStatus vous permet de filtrer les résultats en fonction de l'état de fonctionnement, par exemple OPERATIONAL ou TEMPORARILY_CLOSED. Le comportement du filtre operatingStatus est le suivant :

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

Niveau de prix

Le filtre priceLevels vous permet de filtrer les lieux en fonction de leur niveau de prix. Les valeurs de niveau de prix valides sont : 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 aux niveaux de prix spécifiés sont renvoyés.

Filtre "Note"

Filtre les lieux en fonction de la note moyenne des visiteurs. Ces deux champs sont facultatifs. S'ils sont omis, ils incluront par défaut les lieux qui n'ont pas de note.

minRating : note moyenne minimale des utilisateurs (entre 1,0 et 5,0).
maxRating : note moyenne maximale des 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 supérieur à maxRating, une erreur INVALID_ARGUMENT est renvoyée.