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 :

• Nombre de lieux : déterminez le nombre de lieux qui correspondent à des critères spécifiques, tels que le type de lieu, l'état de fonctionnement, la tranche de prix et les notes.
• Récupérer les détails d'un lieu : obtenez les noms des lieux qui répondent 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. Voici les filtres disponibles :
  • Zone géographique (cercle, région ou polygone personnalisé)
  • Types de lieu
  • Statut
  • Niveaux de prix
  • Plages de classification

Paramètres obligatoires

Cette section décrit les paramètres requis lorsque vous envoyez 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 filtre.
• INSIGHT_PLACES : renvoie les ID de lieux correspondant aux critères de filtrage.

Remarque : Si vous sélectionnez INSIGHT_PLACES, l'API Places Aggregate ne renvoie les ID de lieu que si le count est inférieur ou égal à 100.

Filtres

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

Filtre d'emplacement

Un filtre de localisation peut être de l'un des types suivants :

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

Important : La zone de chaque filtre de localisation doit être comprise entre 1 556,86 mètres carrés (environ la taille d'un petit pâté de maisons) et 2 billions de mètres carrés (environ la taille de l'Alaska). Les requêtes avec des zones en dehors de cette plage renverront une erreur INVALID_ARGUMENT.

Remarque : Pour les entités avec des limites polygonales définies, telles que les parcs ou les aéroports, l'entité est considérée comme se trouvant dans la zone de recherche si une partie de son polygone croise la zone de recherche définie (cercle, région ou polygone personnalisé). Le point central de l'entité n'a pas besoin de se trouver dans la zone de recherche.

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 du 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 du lieu correspondant au 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 pouvant être représentée 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 prise en charge. De plus, pour les régions géographiques complexes, les optimisations de traitement internes peuvent entraîner une légère surestimation de la superficie (jusqu'à 2 à 3 %) représentant la région.

Important : Lorsque vous utilisez le filtre region avec le type d'insight INSIGHT_PLACES, les demandes qui incluent des zones contestées sont automatiquement refusé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 contestées par différents pays ou entités. Les frontières contestées sont représentées par une ligne grise discontinue sur Google Maps.

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

Important : Google n'accepte pas certains ID de lieu qui appartiennent aux types de régions suivants :

• Types de régions si volumineux qu'ils entraînent une latence élevée.
• Types de régions trop petits qui compromettent la conformité en termes de confidentialité.

Pour déterminer si un ID de lieu représente un type de lieu non compatible, transmettez l'ID de lieu dans une requête 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 refusé pour le filtrage par région si l'un de ses types correspond à cette liste.

Voici quelques exemples de 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 de l'établissement, comme un appartement, une unité ou une suite.

Remarque : Même certains lieux non listés ci-dessus peuvent être refusés s'ils ne disposent pas d'une géométrie polygonale bien définie. Cela se produit plus souvent avec des types tels que neighborhood, locality, sublocality et ses variantes numérotées (sublocality_level_1, sublocality_level_2, sublocality_level_3, sublocality_level_4). Dans ce cas, un code d'erreur 400 est renvoyé.

Zone personnalisée

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

Important : Les coordonnées définissant les sommets du polygone doivent être listées dans le sens antihoraire. Cette convention est conforme à la norme du secteur pour la définition des polygones, où l'ordre inverse des aiguilles d'une montre indique que l'intérieur du polygone se trouve à gauche des limites.

Important : Les zones personnalisées ne doivent pas comporter plus de 7 000 sommets.

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 identiques consécutives seront traitées comme une seule coordonnée. Toutefois, les coordonnées en double non consécutives (autres que les coordonnées de début et de fin identiques requises) généreront une erreur.

De plus, les arêtes non adjacentes ne sont pas autorisées à se croiser, et les arêtes de longueur 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 par type

Spécifie les types de lieux à inclure ou à exclure. Pour obtenir la liste des types de lieux principaux 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 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.

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 gammes 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 filtre n'est appliqué (toutes les classifications 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 opérationnel 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 valides pour le niveau de prix 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 lorsque vous filtrez par niveau de prix spécifique.
• Si un ou plusieurs filtres sont fournis : seuls les lieux correspondant au ou aux niveaux 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 incluront par défaut les lieux qui n'ont pas de note.

• minRating : note moyenne minimale des utilisateurs (entre 1 et 5).
• maxRating : note moyenne maximale des utilisateurs (entre 1 et 5).

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.