Bibliothèque Places

Présentation

Les fonctions de la bibliothèque Places, API Maps JavaScript permettent à votre application de rechercher des lieux (définis dans cette API comme des établissements, des emplacements géographiques ou des points d'intérêt importants) dans une zone définie, comme les limites d'une carte ou la surface autour d'un point fixe.

L'API Places propose une fonctionnalité de saisie semi-automatique qui vous permet de donner à vos applications le comportement de recherche anticipée du champ de recherche Google Maps. Lorsqu'un utilisateur commence à saisir une adresse, la fonction de saisie semi-automatique la complète. Pour en savoir plus, consultez la documentation sur la saisie semi-automatique.

Premiers pas

Si vous ne connaissez pas l'API Maps JavaScript ou JavaScript, nous vous recommandons de vous familiariser avec ces éléments, et d'obtenir une clé API avant de commencer.

Charger la bibliothèque

Le service Places est une bibliothèque autonome, distincte du code principal de l'API Maps JavaScript. Pour utiliser la fonctionnalité contenue dans cette bibliothèque, vous devez d'abord la charger à l'aide du paramètre libraries dans l'URL d'amorçage de l'API Google Maps :

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>

Pour en savoir plus, consultez la Présentation des bibliothèques.

Ajouter l'API Places à la liste des restrictions d'API de la clé API

1. Accédez à Google Cloud Console.
2. Cliquez sur la liste déroulante du projet, puis sélectionnez le projet contenant la clé API que vous souhaitez sécuriser.
3. Cliquez sur le bouton Menu , puis sélectionnez Google Maps Platform > Identifiants.
4. Sur la page Identifiants, cliquez sur le nom de la clé API que vous souhaitez sécuriser.
5. Sur la page Restreindre et renommer la clé API, définissez les restrictions :
   
   • Restrictions relatives aux API
   • Sélectionnez Restreindre la clé.
   • Cliquez sur Sélectionner des API, puis sélectionnez API Maps JavaScript et API Places.
     Si l'une des API n'est pas listée, vous devez l'activer.
6. Cliquez sur ENREGISTRER.

Limites d'utilisation et règles

Quotas

La Bibliothèque Places partage un quota d'utilisation avec l'API Places, comme décrit dans sa documentation sur les limites d'utilisation.

Règles

L'utilisation de la bibliothèque Places et de l'API Maps JavaScript doit être conforme aux Règles décrites pour l'API Places.

Recherches de lieux

Avec le service Places, vous pouvez effectuer les types de recherches suivants :

• Find Place from Query : renvoie un lieu en fonction d'une requête textuelle (par exemple, le nom ou l'adresse d'un lieu).
• Find Place from Phone Number : renvoie un lieu à partir d'un numéro de téléphone.
• Nearby Search : renvoie une liste de lieux à proximité en fonction de la position de l'utilisateur.
• Recherche de texte : renvoie une liste de lieux à proximité en fonction d'une chaîne de recherche, par exemple "Pizza".
• Les requêtes Place Details renvoient des informations plus détaillées sur un lieu spécifique, y compris des avis d'utilisateurs.

Les informations renvoyées peuvent inclure des établissements comme des restaurants, des magasins ou des bureaux, ainsi que des résultats "geocode" indiquant des adresses ou des entités administratives, comme des communes ou des villes, et d'autres points d'intérêt.

Requêtes Find Place

Les requêtes Find Place vous permettent de rechercher un lieu à l'aide d'une requête textuelle ou d'un numéro de téléphone. Il existe deux types de requêtes Find Place :

• Find Place from Query
• Find Place from Phone Number

Find Place from Query

Find Place from Query renvoie un lieu à partir d'une entrée textuelle. Il peut s'agir de n'importe quel type de lieu, comme un nom d'entreprise ou une adresse. Pour effectuer une requête Find Place from Query, appelez la méthode PlacesService de findPlaceFromQuery(), qui utilise les paramètres suivants :

• query (obligatoire) : chaîne de texte sur laquelle doit porter la recherche, par exemple "restaurant" ou "123 Main Street". Il doit s'agir d'un nom de lieu, d'une adresse ou d'une catégorie d'établissements. Tout autre type d'entrée peut générer des erreurs, et ne renverra peut-être pas de résultats valides. L'API Places renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence estimée.
• fields (obligatoire) : un ou plusieurs champs spécifiant les types de données de lieu à renvoyer.
• locationBias (facultatif) : coordonnées définissant la zone à rechercher. Il peut s'agir par exemple :
  • d'un ensemble de coordonnées de latitude et de longitude spécifiées en tant que LatLngLiteral ou qu'objet LatLng ;
  • de limites rectangulaires (deux paires de latitude/longitude ou un objet LatLngBounds) ;
  • d'un rayon (en mètres) centré sur une latitude/longitude.

Vous devez également transmettre une méthode de rappel à findPlaceFromQuery() pour gérer l'objet de résultats et la réponse google.maps.places.PlacesServiceStatus.

L'exemple suivant illustre un appel à findPlaceFromQuery() pour rechercher "Musée d'art contemporain Australie", et qui inclut les champs name et geometry.

var map;
var service;
var infowindow;

function initMap() {
  var sydney = new google.maps.LatLng(-33.867, 151.195);

  infowindow = new google.maps.InfoWindow();

  map = new google.maps.Map(
      document.getElementById('map'), {center: sydney, zoom: 15});

  var request = {
    query: 'Museum of Contemporary Art Australia',
    fields: ['name', 'geometry'],
  };

  var service = new google.maps.places.PlacesService(map);