Paramètres de requête

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

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

• Compter les lieux: déterminez le nombre de lieux correspondant à des critères spécifiques, tels que le type d'emplacement, l'état de fonctionnement, le niveau de prix et les avis.
• Récupérer des informations sur 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 insights précis. Voici les différents filtres disponibles :
  • Zone géographique (cercle, région ou polygone personnalisé)
  • Types de lieu
  • Statut
  • Niveaux de prix
  • Échelles de classification

Paramètres obligatoires

Cette section décrit les paramètres requis lorsque vous envoyez une requête à l'API Places Insights. Chaque requête doit fournir les éléments suivants:

• Type d'insight.
• Filtre d'emplacement et de type.

Type de statistiques

Spécifie le type d'insights 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.

Remarque :Si vous sélectionnez INSIGHT_PLACES, l'API Places Insights ne renvoie des ID de lieu que si la valeur de count est inférieure ou égale à 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 zone géographique peut être de l'un des types suivants:

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

Important :La superficie de tout filtre de zone géographique doit être comprise entre 1 556,86 m² (environ la taille d'un petit pâté de maisons) et 2 billions de m² (environ la taille de l'Alaska). Les requêtes dont les zones se trouvent en dehors de cette plage renvoient une erreur INVALID_ARGUMENT.

Remarque :Pour les entités dont les limites polygonales sont définies, comme les parcs ou les aéroports, l'entité est considérée comme située dans la zone de recherche si une partie de son polygone intersecte 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 en tant que 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 pouvant être représentée par un polygone). Par exemple, l'ID de lieu de Tampa (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 Insights 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 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 en litige sont automatiquement refusées pour garantir l'exactitude et la neutralité des services Google. Les zones en litige sont des régions dont les frontières ou les revendications territoriales sont en conflit entre différents pays ou entités. Les frontières en litige sont représentées par une ligne grise en pointillés sur Google Maps.

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

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

• Types de régions tellement volumineux qu'ils entraînent une latence élevée.
• Types de régions si petits qu'ils compromettent la conformité aux règles de confidentialité

Pour déterminer si un ID de lieu représente un type de lieu non pris en charge, 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 city, neighborhood ou country.

Voici les types de lieux non acceptés:

• establishment: indique généralement un lieu qui n'a pas encore été classé.
• street_number: indique un numéro de rue précis.
• floor: indique l'étage d'une adresse d'immeuble.
• post_box: indique une boîte postale spécifique.
• street_address: indique une adresse postale précise.
• room: indique une salle associée à l'adresse d'un bâtiment.
• intersection: indique une intersection majeure, généralement entre deux routes principales.
• landmark: indique un lieu à proximité qui sert de référence pour faciliter la navigation.
• subpremise: indique une entité adressable au niveau inférieur à celui des locaux, comme un appartement, une unité ou une suite.
• sublocality_level_5: niveau de précision le plus spécifique des composants d'adresse de la sous-localité, représentant généralement une très petite subdivision de quartier ou une zone hyperlocale dans une ville.

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 l'ordre antihoraire. Cela suit la convention standard du secteur pour définir les polygones, où l'ordre antihoraire indique que l'intérieur du polygone se trouve à gauche des bordures.

Important :Les zones personnalisées doivent comporter 7 000 sommets ou moins.

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 les premières et dernières sont identiques. Au moins trois des coordonnées fournies doivent être uniques.

Les coordonnées consécutives identiques seront traitées comme une seule coordonnée. Toutefois, les coordonnées en double non consécutives (à l'exception des coordonnées de début et de fin identiques requises) entraînent 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 d'établissements principaux et secondaires compatibles avec l'API Places Insights, consultez le tableau A sous Types d'établissements pour l'API Places (nouvelle). Vous devez spécifier au moins un type includedTypes ou includedPrimaryTypes.

• includedTypes: liste des types d'établissements inclus.
• excludedTypes: liste des types d'établissements exclus.
• includedPrimaryTypes: liste des types d'établissements 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 cet article 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 est effectué par operatingStatus: OPERATING_STATUS_OPERATIONAL (une valeur spécifique).
• priceLevels: spécifie les niveaux de prix des lieux. Par défaut, aucun filtrage n'est appliqué (tous les niveaux de prix sont inclus dans les résultats).
• 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

Avec le filtre operatingStatus, vous pouvez filtrer en fonction de l'état de fonctionnement (par exemple, "en service" ou "fermé temporairement"). Si le filtre operatingStatus n'est pas défini, seuls les lieux dont l'état de fonctionnement est OPERATING_STATUS_OPERATIONAL sont inclus dans les résultats.

Niveau de prix

Avec le filtre price_levels, vous pouvez filtrer en fonction du niveau de prix (par exemple, "Sans frais", "Modéré" ou "Coûteux"). Si le filtre price_levels n'est pas défini, tous les niveaux de prix sont inclus dans les résultats.

Filtre "Note"

Filtre les lieux en fonction de leur note moyenne. Ces deux champs sont facultatifs. Par défaut, s'ils sont omis, ils incluent également 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 spécifié comme étant supérieur à maxRating, une erreur INVALID_ARGUMENT est renvoyée.