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 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é.
Cercle

Si vous sélectionnez votre zone géographique en tant que cercle, vous devez fournir un center et un radius. Le centre peut être une latitude et une longitude, ou l'ID de lieu du centre du cercle.

  • 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 404.

Le tableau suivant répertorie les types de régions non compatibles. Pour déterminer si un ID de lieu représente un type de région non pris en charge, transmettez-le dans une requête API Geocoding. La réponse inclut le tableau type qui liste les régions associées à l'ID de lieu, telles que city, neighborhood ou country.

Types de régions non compatibles
establishment place_of_worship
floor post_box
food postal_code_suffix
general_contractor room
geocode street_address
health street_number
intersection sublocality_level_5
landmark subpremise
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 les premières et dernières sont identiques. Au moins trois des coordonnées fournies doivent être uniques. En dehors des premières et dernières coordonnées, il ne doit pas y avoir d'autres coordonnées en double. 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'adresses principaux et secondaires compatibles avec l'API Places Insights, consultez le tableau A sous Types d'adresses 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

Filtrer en fonction de l'état de fonctionnement (par exemple, opérationnel ou fermé temporairement).

Niveau de prix

Filtrez en fonction du niveau de prix (par exemple, "Sans frais", "Modéré" ou "Coûteux").

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).