Cette page a été traduite par l'API Cloud Translation.

Recherche à proximité (nouveau)

Une requête Nearby Search (New) prend un ou plusieurs types de lieux et renvoie une liste de lieux correspondants dans la zone spécifiée. Veuillez indiquer un masque de champ spécifiant un ou plusieurs types de données. Nearby Search (New) n'accepte que les requêtes POST.

APIs Explorer vous permet d'envoyer des requêtes actives afin de vous familiariser avec l'API et ses options:

Essayer

Requêtes Nearby Search (nouvelles)

Une requête Nearby Search (New) est une requête HTTP POST adressée à une URL au format suivant:

https://places.googleapis.com/v1/places:searchNearby

Transmettez tous les paramètres dans le corps de la requête JSON ou dans des en-têtes dans la requête POST. Exemple :

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Réponses Nearby Search (New)

Nearby Search (New) renvoie un objet JSON en tant que réponse. Dans la réponse :

Le tableau places contient tous les lieux correspondants.
Chaque lieu du tableau est représenté par un objet Place. L'objet Place contient des informations détaillées sur un seul lieu.
Le paramètre FieldMask transmis dans la requête spécifie la liste des champs renvoyés dans l'objet Place.

L'objet JSON complet se présente sous la forme suivante:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Paramètres obligatoires

FieldMask

Spécifiez la liste des champs à renvoyer dans la réponse en créant un masque de champ de réponse. Transmettez le masque de champ de réponse à la méthode à l'aide du paramètre d'URL $fields ou fields, ou de l'en-tête HTTP X-Goog-FieldMask. Il n'existe pas de liste par défaut des champs renvoyés dans la réponse. Si vous omettez le masque de champ, la méthode renvoie une erreur.

Le masquage de champ est une bonne pratique de conception pour vous assurer de ne pas demander de données inutiles, ce qui permet d'éviter des temps de traitement et des frais facturés inutiles.

Spécifiez une liste de types de données de lieu à renvoyer, séparés par une virgule. (par exemple, pour récupérer le nom à afficher et l'adresse du lieu).
```
X-Goog-FieldMask: places.displayName,places.formattedAddress
```
Remarque : Les espaces ne sont pas autorisés dans la liste des champs.

Utilisez * pour récupérer tous les champs.
```
X-Goog-FieldMask: *
```
Le caractère générique "*" sélectionne tous les champs. Toutefois, bien que ce caractère générique puisse être utilisé pour le développement, Google déconseille l'utilisation en production du masque de champ de réponse utilisant le caractère générique (*), en raison de la grande quantité de données pouvant être renvoyées.

Pour en savoir plus sur l'utilisation de places.iconMaskBaseUri et places.iconBackgroundColor, consultez la section Icônes de lieu.

Renseignez un ou plusieurs des champs suivants:
- Les champs suivants déclenchent le SKU Nearby Search (Basic):
  
  places.accessibilityOptions, places.addressComponents, places.adrFormatAddress, places.businessStatus, places.displayName, places.formattedAddress, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name^*, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport
  
  ^* Le champ places.name inclut le nom de ressource du lieu dans le formulaire : places/PLACE_ID. Utilisez places.displayName pour accéder au nom textuel du lieu.
- Les champs suivants déclenchent le SKU Nearby Search (Advanced):
  
  places.currentOpeningHours, places.currentSecondaryOpeningHours, places.internationalPhoneNumber, places.nationalPhoneNumber, places.priceLevel, places.rating, places.regularOpeningHours, places.regularSecondaryOpeningHours, places.userRatingCount, places.websiteUri
- Les champs suivants déclenchent le SKU Nearby Search (Preferred):
  
  places.allowsDogs, places.curbsidePickup, places.delivery, places.dineIn, places.editorialSummary, places.evChargeOptions, places.fuelOptions, places.goodForChildren, places.goodForGroups, places.goodForWatchingSports, places.liveMusic, places.menuForChildren, places.parkingOptions, places.paymentOptions, places.outdoorSeating, places.reservable, places.restroom, places.reviews, places.servesBeer, places.reviews, places.servesBeer, places.servesBreakfast, places.servesBeer,places.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.takeout
locationRestriction

Région à rechercher spécifiée sous la forme d'un cercle, défini par le point central et le rayon en mètres. Le rayon doit être compris entre 0,0 et 50 000,0 inclus. Le rayon par défaut est 0,0. Vous devez la définir dans votre requête sur une valeur supérieure à 0,0.

Par exemple :
```
"locationRestriction": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}
```

Paramètres facultatifs

includePrimaryTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

Permet de spécifier une liste de types à partir des types Tableau A utilisés pour filtrer les résultats de la recherche. Vous pouvez spécifier jusqu'à 50 types dans chaque catégorie de restriction de type.

Remarque : Les valeurs du tableau B ne sont renvoyées que dans la réponse. Vous ne pouvez pas utiliser les valeurs du Tableau B comme filtre.

Un lieu ne peut avoir qu'un seul type principal parmi les types Table A qui lui sont associés. Par exemple, le type principal peut être "mexican_restaurant" ou "steak_house". Utilisez includedPrimaryTypes et excludedPrimaryTypes pour filtrer les résultats en fonction du type principal d'un lieu.

Un lieu peut également avoir plusieurs valeurs de type issues des types Tableau A qui lui sont associés. Par exemple, un restaurant peut présenter les types suivants : "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Utilisez includedTypes et excludedTypes pour filtrer les résultats sur la liste des types associés à un lieu.

Si une recherche est spécifiée avec plusieurs restrictions de type, seuls les lieux qui répondent à toutes les restrictions sont renvoyés. Par exemple, si vous spécifiez {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}, les lieux renvoyés fournissent des services liés à "restaurant", mais ne fonctionnent pas principalement en tant que "steak_house".

Si vous omettez includedTypes, excludedTypes, includedPrimaryTypes et excludedPrimaryTypes dans la requête, la recherche renvoie des lieux pour tous les types à partir des limites de restriction d'emplacement.

includedTypes

Liste des types de lieux à rechercher du Tableau A, séparés par une virgule. Si ce paramètre est omis, les lieux de tous types sont renvoyés.

excludedTypes

Liste de types de lieux séparés par une virgule du Tableau A à exclure d'une recherche.

Si vous spécifiez à la fois les propriétés includedTypes ( par exemple, "school") et excludedTypes (par exemple, "primary_school") dans la requête, la réponse inclut les lieux classés dans la catégorie "school", mais pas dans la catégorie "primary_school". La réponse inclut des lieux correspondant à au moins un des éléments includedTypes et aucun des éléments excludedTypes.

En cas de types conflictuels, tels qu'un type apparaissant à la fois dans includedTypes et excludedTypes, une erreur INVALID_REQUEST est renvoyée.

includedPrimaryTypes

Liste des types de lieux principaux (séparés par une virgule) du Tableau A à inclure dans une recherche.

excludedPrimaryTypes

Liste des types de lieux principaux du Tableau A, séparés par une virgule, à exclure d'une recherche.

En cas de types principaux en conflit, tels qu'un type apparaissant à la fois dans includedPrimaryTypes et excludedPrimaryTypes, une erreur INVALID_ARGUMENT est renvoyée.
languageCode

Langue dans laquelle les résultats doivent être renvoyés.
- Consultez la liste des langues acceptées. Google met régulièrement à jour les langues acceptées. Cette liste n'est donc pas exhaustive.
- Si languageCode n'est pas fourni, l'API est définie par défaut sur en. Si vous spécifiez un code de langue non valide, l'API renvoie une erreur INVALID_ARGUMENT.
- L'API s'efforce de fournir une adresse postale lisible à la fois par l'utilisateur et par les locaux. Pour atteindre cet objectif, elle renvoie les adresses postales dans la langue locale, transcrites en script lisible par l'utilisateur si nécessaire, tout en respectant la langue préférée. Toutes les autres adresses sont affichées dans la langue préférée. Les composants d'adresse sont tous renvoyés dans la même langue, qui est choisie à partir du premier composant.
- Si un nom n'est pas disponible dans la langue préférée, l'API utilise le nom correspondant le plus proche.
- La langue préférée a une petite influence sur l'ensemble de résultats que l'API choisit de renvoyer et sur l'ordre dans lequel ils sont renvoyés. Le geocoder interprète les abréviations différemment selon la langue : par exemple, les abréviations de types de rues ou les synonymes qui peuvent être valides dans une langue, mais pas dans une autre.
maxResultCount

Spécifie le nombre maximal de résultats de lieu à renvoyer. Doit être comprise entre 1 et 20 (par défaut) inclus.
rankPreference

Type de classement à utiliser. Si ce paramètre est omis, les résultats sont classés par popularité. Il peut s'agir de l'un des éléments suivants:
- POPULARITY (par défaut) Trie les résultats en fonction de leur popularité.
- DISTANCE Trie les résultats par ordre croissant en fonction de leur distance par rapport à l'emplacement spécifié.
regionCode

Code de région utilisé pour mettre en forme la réponse, spécifié en tant que valeur de code CLDR à deux caractères. Il n'existe pas de valeur par défaut.

Si le nom du pays du champ formattedAddress dans la réponse correspond à regionCode, le code pays est omis dans formattedAddress. Ce paramètre n'a aucun effet sur adrFormatAddress, qui inclut toujours le nom du pays, ou sur shortFormattedAddress, qui ne l'inclut jamais.

La plupart des codes CLDR sont identiques aux codes ISO 3166-1, à quelques exceptions près. Par exemple, le ccTLD du Royaume-Uni est "uk" (.co.uk), tandis que son code ISO 3166-1 est "gb" (techniquement pour l'entité "Royaume-Uni de Grande-Bretagne et d'Irlande du Nord"). Le paramètre peut avoir une incidence sur les résultats en fonction de la législation applicable.

Exemples Nearby Search (New)

Rechercher des lieux d'un type spécifique

L'exemple suivant montre une requête Nearby Search (New) pour les noms à afficher de tous les restaurants dans un rayon de 500 mètres, défini par circle:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Notez que l'en-tête X-Goog-FieldMask spécifie que la réponse contient les champs de données suivants: places.displayName. La réponse se présente alors sous la forme suivante:

{
  "places": [
    {
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
    {
      "displayName": {
        "text": "Harborview Restaurant & Bar",
        "languageCode": "en"
      }
    },
...
}

Ajoutez d'autres types de données au masque de champ pour renvoyer des informations supplémentaires. Par exemple, ajoutez places.formattedAddress,places.types,places.websiteUri pour inclure l'adresse, le type et l'adresse Web du restaurant dans la réponse:

curl -X POST -d '{
  "includedTypes": ["restaurant"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965},
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \
https://places.googleapis.com/v1/places:searchNearby

La réponse se présente maintenant sous la forme suivante:

{
  "places": [
    {
      "types": [
        "seafood_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA",
      "websiteUri": "http://lamarsf.com/",
      "displayName": {
        "text": "La Mar Cocina Peruana",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "greek_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA",
      "websiteUri": "https://kokkari.com/",
      "displayName": {
        "text": "Kokkari Estiatorio",
        "languageCode": "en"
      }
    },
...
}

Rechercher des lieux de plusieurs types

L'exemple suivant montre une requête Nearby Search (New) pour les noms à afficher de tous les magasins de proximité et de spiritueux dans un rayon de 1 000 mètres autour de l'élément circle spécifié:

curl -X POST -d '{
  "includedTypes": ["liquor_store", "convenience_store"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \
https://places.googleapis.com/v1/places:searchNearby

Cet exemple ajoute places.primaryType et places.types au masque de champ afin que la réponse inclue des informations de type sur chaque lieu, ce qui facilite la sélection du lieu approprié dans les résultats.

Exclure un type de lieu d'une recherche

L'exemple suivant montre une requête Nearby Search (New) pour tous les lieux de type "school", à l'exclusion de tous les lieux de type "primary_school", en classant les résultats par distance:

curl -X POST -d '{
  "includedTypes": ["school"],
  "excludedTypes": ["primary_school"],
  "maxResultCount": 10,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  },
  "rankPreference": "DISTANCE"
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Rechercher tous les lieux à proximité d'une zone en les classant par distance

L'exemple suivant montre une requête Nearby Search (New) pour des lieux à proximité d'un point dans le centre-ville de San Francisco. Dans cet exemple, vous incluez le paramètre rankPreference pour classer les résultats par distance:

curl -X POST -d '{
  "maxResultCount": 10,
  "rankPreference": "DISTANCE",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 1000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName" \
https://places.googleapis.com/v1/places:searchNearby

Essayer

API Explorer vous permet de créer des exemples de requêtes afin de vous familiariser avec l'API et ses options.

Sélectionnez l'icône API sur le côté droit de la page.
Vous pouvez également développer la section Afficher les paramètres standards et définir le paramètre fields sur le masque de champ.
Vous pouvez également modifier le corps de la requête.
Sélectionnez le bouton Execute (Exécuter). Dans la fenêtre pop-up, sélectionnez le compte que vous souhaitez utiliser pour effectuer la demande.
Dans le panneau de l'explorateur d'API, sélectionnez l'icône de développement pour développer la fenêtre de l'explorateur d'API.

Recherche à proximité (nouveau)

Requêtes Nearby Search (nouvelles)

Réponses Nearby Search (New)

Paramètres obligatoires

FieldMask

locationRestriction

Paramètres facultatifs

includePrimaryTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode

Exemples Nearby Search (New)

Rechercher des lieux d'un type spécifique

Rechercher des lieux de plusieurs types

Exclure un type de lieu d'une recherche

Rechercher tous les lieux à proximité d'une zone en les classant par distance

Essayer