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.

Activer des API

Avant d'utiliser la bibliothèque Places dans l'API Maps JavaScript, vérifiez que l'API Places est activée dans la console Google Cloud, dans le projet que vous avez configuré pour l'API Maps JavaScript.

Pour afficher la liste des API activées :

  1. Accédez à la console Google Cloud.
  2. Cliquez sur le bouton Sélectionner un projet, sélectionnez le projet que vous avez configuré pour l'API Maps JavaScript, puis cliquez sur Ouvrir.
  3. Dans la liste des API du tableau de bord, recherchez API Places.
  4. Si l'API Places figure dans la liste, cela signifie qu'elle est déjà activée. Si l'API ne figure pas dans la liste, activez-la :
    1. En haut de la page, sélectionnez ACTIVER DES API ET DES SERVICES pour afficher l'onglet Bibliothèque. Vous pouvez également sélectionner Bibliothèque dans le menu de gauche.
    2. Recherchez l'API Places, puis sélectionnez-la dans la liste des résultats.
    3. Sélectionnez ACTIVER. Une fois le processus terminé, l'API Places apparaît dans la liste des API du tableau de bord.

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

Appliquer des restrictions d'API à vos clés limite l'utilisation de la clé API à un ou plusieurs SDK ou API. Les requêtes vers une API ou un SDK associé à la clé API seront traitées. Les requêtes vers une API ou un SDK non associé à la clé API échoueront. Pour restreindre l'utilisation d'une clé API avec l'API Places Library et Maps JavaScript :
  1. Accédez à la console Google Cloud.
  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 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);

  service.findPlaceFromQuery(request, function(results, status) {
    if (status === google.maps.places.PlacesServiceStatus.OK) {
      for (var i = 0; i < results.length; i++) {
        createMarker(results[i]);
      }
      map.setCenter(results[0].geometry.location);
    }
  });
}
 Voir un exemple

Find Place from Phone Number

Find Place from Phone Number renvoie un lieu à partir d'un numéro de téléphone. Pour effectuer une requête Find Place from Phone Number, appelez la méthode PlacesService de findPlaceFromPhoneNumber(), qui utilise les paramètres suivants :

  • phoneNumber (obligatoire) : un numéro de téléphone au format E.164 ;
  • 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 (quatre points 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 à findPlaceFromPhoneNumber() pour gérer l'objet de résultats et la réponse google.maps.places.PlacesServiceStatus.

Champs (méthodes Find Place)

Utilisez le paramètre fields pour spécifier un tableau de types de données de lieu à renvoyer (par exemple, fields: ['formatted_address', 'opening_hours', 'geometry']). Utilisez un point lorsque vous spécifiez des valeurs composées (par exemple, opening_hours.weekday_text).

Les champs correspondent aux résultats Place Search et sont divisés en trois catégories de facturation : Basic, Contact et Ambiance. Les champs Basic sont facturés au tarif de base et n'entraînent aucuns frais supplémentaires. Les champs Contact et Ambiance sont facturés à un tarif plus élevé. Pour en savoir plus, consultez la grille tarifaire. Les attributions (html_attributions) sont toujours renvoyées avec chaque appel, que le champ ait été demandé ou non.

Basic

La catégorie Basic inclut les champs suivants :
business_status, formatted_address, geometry, icon,icon_mask_base_uri, icon_background_color, name, permanently_closed (obsolète), photos, place_id, plus_code, types

Contact

La catégorie Contact inclut le champ suivant : opening_hours
(obsolète dans la bibliothèque Places, API Maps JavaScript. Utilisez une requête Places Details pour obtenir les résultats opening_hours.)

Ambiance

La catégorie Ambiance comprend les champs suivants : price_level, rating, user_ratings_total

Les méthodes findPlaceFromQuery() et findPlaceFromPhoneNumber() utilisent chacune le même ensemble de champs et peuvent renvoyer les mêmes champs dans leurs réponses respectives.

Définir un biais de localisation (méthodes Find Place)

Utilisez le paramètre locationBias pour que l'option Find Place favorise les résultats dans une zone particulière. Vous pouvez définir locationBias comme suit :

Limiter les résultats à une zone spécifique :

locationBias: {lat: 37.402105, lng: -122.081974}

Définir une zone rectangulaire à rechercher :

locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}

Vous pouvez également utiliser LatLngBounds.

Définir un rayon de recherche (en mètres) centré sur une zone particulière :

locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}

Requêtes Nearby Search

Une requête Nearby Search permet de rechercher des lieux dans une zone définie par mot clé ou par type. Une requête Nearby Search doit toujours inclure un lieu, qui doit être spécifié en utilisant au choix :

  • un LatLngBounds ;
  • une zone circulaire définie comme la combinaison de la propriété location (qui spécifie le centre du cercle en tant qu'objet LatLng) et un rayon, mesuré en mètres.

Une recherche Places Nearby est initiée par un appel à la méthode nearbySearch() de PlacesService, qui renvoie un tableau d'objets PlaceResult. Notez que la méthode nearbySearch() remplace la méthode search() à partir de la version 3.9.

service = new google.maps.places.PlacesService(map);
service.nearbySearch(request, callback);

Cette méthode utilise une requête avec les champs suivants :

  • Soit :
    • bounds, qui doit être un objet google.maps.LatLngBounds définissant la zone de recherche rectangulaire. La distance diagonale maximale prise en charge pour la zone de limites est d'environ 100 000 mètres.
    • un location et un radius. La première utilise un objet google.maps.LatLng et la seconde un entier simple représentant le rayon du cercle en mètres. Le rayon maximum autorisé est de 50 000 mètres. Notez que lorsque rankBy est défini sur DISTANCE, vous devez spécifier location. Toutefois, vous ne pouvez définir ni radius, ni bounds.
  • keyword (facultatif) : terme à mettre en correspondance avec tous les champs disponibles, y compris, mais sans s'y limiter, le nom, le type et l'adresse, ainsi que les avis des clients et d'autres contenus tiers.
  • minPriceLevel et maxPriceLevel (facultatif) : restreint les résultats aux seuls lieux compris dans la plage spécifiée. Les valeurs valides sont comprises entre 0 (le moins cher) et 4 (le plus cher), inclus.
  • name (obsolète) : Équivaut à keyword. Les valeurs de ce champ sont combinées à celles du champ keyword et transmises dans la même chaîne de recherche.
  • openNow (facultatif) : valeur booléenne indiquant que le service Places ne doit renvoyer que les lieux ouverts au moment de l'envoi de la requête. Si vous incluez ce paramètre dans la requête, les lieux qui ne précisent pas d'horaires d'ouverture dans la base de données Google Places ne sont pas renvoyés. Définir openNow sur false n'a aucun effet.
  • rankBy (facultatif) : spécifie l'ordre dans lequel les résultats sont listés. Les valeurs possibles sont les suivantes :
    • google.maps.places.RankBy.PROMINENCE (par défaut) : cette option permet de trier les résultats en fonction de leur importance. Ce classement privilégie les lieux importants situés dans le rayon défini par rapport aux lieux situés à proximité qui correspondent au critère de recherche, mais qui sont moins importants. L'importance peut être déterminée par la position du lieu dans l'index Google, sa popularité globale et d'autres facteurs. Lorsque google.maps.places.RankBy.PROMINENCE est spécifié, le paramètre radius est obligatoire.
    • google.maps.places.RankBy.DISTANCE : cette option trie les résultats par ordre croissant selon leur distance par rapport à l'élément location spécifié (obligatoire). Notez que vous ne pouvez pas spécifier de bounds personnalisé ni de radius si vous spécifiez RankBy.DISTANCE. Lorsque vous spécifiez RankBy.DISTANCE, au moins un des éléments keyword, name ou type est requis.
  • type : limite les résultats aux lieux correspondant au type spécifié. Un seul type peut être spécifié (si plusieurs types sont fournis, tous les types spécifiés après la première entrée sont ignorés). Consultez la liste des types compatibles.

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

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

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

  var request = {
    location: pyrmont,
    radius: '500',
    type: ['restaurant']
  };

  service = new google.maps.places.PlacesService(map);
  service.nearbySearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      createMarker(results[i]);
    }
  }
}

Voir un exemple

Requêtes Text Search

Le service Text Search de Google Places est un service Web qui renvoie des informations sur un ensemble de lieux en fonction d'une chaîne de texte (par exemple, "pizza à New York" ou "magasins de chaussures près d'Ottawa"). Ce service renvoie une liste des lieux correspondant à la chaîne de texte et aux limitations de zone géographique définis. La réponse à la recherche inclut une liste de lieux. Vous pouvez ajouter une requête Places Details pour obtenir plus d'informations sur les lieux indiqués dans la réponse.

Les recherches Text Search sont lancées avec un appel à la méthode textSearch() de PlacesService. 

service = new google.maps.places.PlacesService(map);
service.textSearch(request, callback);

Cette méthode utilise une requête avec les champs 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 peuvent ne pas renvoyer de résultats valides. Le service Places renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence estimée. Ce paramètre devient facultatif si type est également utilisé dans la requête de recherche.
  • Facultatif :
    • openNow : valeur booléenne indiquant que le service Places ne doit renvoyer que les lieux ouverts au moment de l'envoi de la requête. Si vous incluez ce paramètre dans la requête, les lieux sans horaires d'ouverture dans la base de données Google Places ne sont pas renvoyés. Définir openNow sur false n'a aucun effet.
    • minPriceLevel et maxPriceLevel  : restreint les résultats aux seuls lieux compris dans la fourchette de prix spécifiée. Les valeurs valides sont comprises entre 0 (le moins cher) et 4 (le plus cher), inclus.
    • Soit :
      • bounds, qui doit être un objet google.maps.LatLngBounds définissant la zone de recherche rectangulaire. La distance diagonale maximale prise en charge pour la zone de limites est d'environ 100 000 mètres.
      • location et radius : vous pouvez affiner les résultats à un cercle donné en transmettant les paramètres location et radius. Vous indiquez ainsi au service Places de privilégier les résultats situés à l'intérieur de ce cercle. Des résultats en dehors de la zone définie peuvent toutefois être affichés. L'emplacement utilise un objet google.maps.LatLng, et le rayon est un entier simple représentant le rayon du cercle en mètres. Le rayon maximum autorisé est de 50 000 mètres.
    • type : limite les résultats aux lieux correspondant au type spécifié. Un seul type peut être spécifié (si plusieurs types sont fournis, tous les types spécifiés après la première entrée sont ignorés). Consultez la liste des types compatibles.

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

var map;
var service;
var infowindow;

function initialize() {
  var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316);

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

  var request = {
    location: pyrmont,
    radius: '500',
    query: 'restaurant'
  };

  service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    for (var i = 0; i < results.length; i++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

Réponses aux recherches

Codes d'état

L'objet de réponse PlacesServiceStatus contient l'état de la requête et éventuellement des informations de débogage qui vous aident à savoir pourquoi la requête de lieu a échoué. Les valeurs possibles sont les suivantes :

  • INVALID_REQUEST : la requête n'est pas valide.
  • OK : la réponse contient un résultat valide.
  • OVER_QUERY_LIMIT : la page Web a dépassé son quota de requêtes.
  • REQUEST_DENIED : la page Web n'est pas autorisée à utiliser PlacesService.
  • UNKNOWN_ERROR : la requête PlacesService n'a pas pu être traitée en raison d'une erreur de serveur. Si vous essayez à nouveau, la requête pourrait aboutir.
  • ZERO_RESULTS : aucun résultat n'a été trouvé pour cette requête.

Résultats Place Search

Les fonctions findPlace(), nearbySearch() et textSearch() renvoient un tableau d'objets PlaceResult.

Chaque objet PlaceResult peut inclure les propriétés suivantes :

  • business_status indique l'état opérationnel du lieu (s'il s'agit d'une entreprise). Il peut contenir l'une des valeurs suivantes :
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Si aucune donnée n'existe, business_status n'est pas renvoyé.
  • formatted_address est une chaîne contenant l'adresse lisible de ce lieu. La propriété formatted_address n'est renvoyée que pour une recherche Text Search.

    Bien souvent, cette adresse équivaut à l'adresse postale. Notez que certains pays, comme le Royaume-Uni, n'autorisent pas la distribution des vraies adresses postales en raison de restrictions de licence.

    L'adresse formatée est composée d'un ou de plusieurs composants d'adresse logiques. Par exemple, l'adresse "111 8th Avenue, New York, NY" comprend les éléments suivants : "111" (le numéro de rue), "8th Avenue" (la route), "New York" (la ville) et "NY" (l'État américain).

    N'analysez pas l'adresse formatée de manière programmatique. Utilisez plutôt les composants d'adresse individuels, que la réponse de l'API inclut en plus du champ d'adresse formaté.

  • geometry : fournit les informations liées aux propriétés géométriques du lieu. Par exemple :
    • location fournit la latitude et la longitude du lieu.
    • viewport définit la fenêtre d'affichage préférée sur la carte lorsque ce lieu est affiché.
  • permanently_closed (obsolète) est un indicateur booléen qui précise si le lieu a fermé définitivement ou temporairement (valeur true). N'utilisez pas permanently_closed. Utilisez plutôt business_status pour obtenir l'état opérationnel des entreprises.
  • plus_code : (voir Open Location Code et Plus Codes) référence de lieu encodée, calculée à partir de coordonnées de latitude et de longitude, qui représente une zone : 1/8000e de degré par 1/8000e de degré (environ 14 m x 14 m à l'équateur) ou moins. Vous pouvez utiliser des Plus Codes pour remplacer les adresses postales dans les endroits où elles n'existent pas (où les bâtiments ne sont pas numérotés ni nommés).

    Les Plus Codes sont mis en forme comme un code global et un code composé :

    • global_code est un indicatif de zone à 4 caractères et un indicatif local à 6 caractères ou plus (849VCWC8+R9).
    • compound_code est un code local à six caractères ou plus avec un emplacement explicite (CWC8+R9, Mountain View, CA, États-Unis). N'analysez pas ce contenu de manière programmatique.
    Généralement, le code global et le code composé sont tous deux renvoyés. Toutefois, si le résultat se trouve dans un emplacement distant (par exemple, un océan ou un désert), seul le code global peut être renvoyé.
  • html_attributions : tableau des mentions que vous devez afficher dans les résultats de recherche. Chaque entrée du tableau contient le texte HTML d'une mention unique. Remarque : il s'agit d'une agrégation de toutes les mentions pour la réponse à la recherche dans son ensemble. Tous les objets PlaceResult de la réponse contiennent donc des listes d'attribution identiques.
  • icon renvoie l'URL associée à une icône colorée de 71 x 71 pixels au format PNG.
  • icon_mask_base_uri renvoie l'URL de base d'une icône non colorée, sans l'extension .svg ou .png.
  • icon_background_color renvoie le code couleur hexadécimale par défaut pour la catégorie du lieu.
  • name : nom du lieu.
  • opening_hours peut contenir les informations suivantes :
    • open_now est une valeur booléenne indiquant si le lieu est ouvert à l'heure actuelle (obsolète dans la bibliothèque Places, API Maps JavaScript, utilisez plutôt utc_offset_minutes).
  • place_id est un identifiant textuel qui identifie un lieu de manière unique. Pour récupérer des informations sur le lieu, transmettez cet identifiant dans la requête Place Details. Découvrez comment référencer un lieu avec un ID de lieu.
  • rating contient la note du lieu, sur une échelle de 0,0 à 5,0, basée sur l'ensemble des avis des utilisateurs.
  • types : tableau des types pour ce lieu (par exemple, ["political", "locality"] ou ["restaurant", "lodging"]). Ce tableau peut contenir plusieurs valeurs ou être vide. De nouvelles valeurs peuvent être ajoutées sans préavis. Consultez la liste des types compatibles.
  • vicinity : adresse simplifiée du lieu, comprenant la rue, le numéro et la ville, mais sans le département/la province, le code postal ou le pays. Par exemple, la valeur de vicinity du bureau de Google à Sydney en Australie est de 5/48 Pirrama Road, Pyrmont.

Accéder à des résultats supplémentaires

Par défaut, chaque recherche de lieu renvoie jusqu'à 20 résultats par requête. Toutefois, chaque recherche peut renvoyer jusqu'à 60 résultats, répartis sur trois pages. Des pages supplémentaires sont disponibles via l'objet PlaceSearchPagination. Pour accéder à ces pages supplémentaires, vous devez capturer l'objet PlaceSearchPagination avec une fonction de rappel. L'objet PlaceSearchPagination est défini comme suit :

  • hasNextPage : une propriété booléenne qui indique si d'autres résultats sont disponibles. Elle est true lorsqu'il existe une page de résultats supplémentaire.
  • nextPage() : une fonction qui renvoie l'ensemble de résultats suivant. Après avoir exécuté une recherche, vous devez attendre deux secondes avant que la page de résultats suivante soit disponible.

Pour afficher les résultats suivants, appelez nextPage. Chaque page de résultats doit être affichée avant de pouvoir afficher la suivante. Notez que chaque résultat correspond à une requête unique dans vos limites d'utilisation.

L'exemple ci-dessous montre comment modifier votre fonction de rappel pour capturer l'objet PlaceSearchPagination pour envoyer plusieurs requêtes de recherche.

TypeScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">

function initMap(): void {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: pyrmont,
      zoom: 17,
      mapId: "8d193001f940fde3",
    } as google.maps.MapOptions
  );

  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage: () => void | false;
  const moreButton = document.getElementById("more") as HTMLButtonElement;

  moreButton.onclick = function () {
    moreButton.disabled = true;

    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (
      results: google.maps.places.PlaceResult[] | null,
      status: google.maps.places.PlacesServiceStatus,
      pagination: google.maps.places.PlaceSearchPagination | null
    ) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;

      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    }
  );
}

function addPlaces(
  places: google.maps.places.PlaceResult[],
  map: google.maps.Map
) {
  const placesList = document.getElementById("places") as HTMLElement;

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon!,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name!,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name!;
      placesList.appendChild(li);

      li.addEventListener("click", () => {
        map.setCenter(place.geometry!.location!);
      });
    }
  }
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initMap() {
  // Create the map.
  const pyrmont = { lat: -33.866, lng: 151.196 };
  const map = new google.maps.Map(document.getElementById("map"), {
    center: pyrmont,
    zoom: 17,
    mapId: "8d193001f940fde3",
  });
  // Create the places service.
  const service = new google.maps.places.PlacesService(map);
  let getNextPage;
  const moreButton = document.getElementById("more");

  moreButton.onclick = function () {
    moreButton.disabled = true;
    if (getNextPage) {
      getNextPage();
    }
  };

  // Perform a nearby search.
  service.nearbySearch(
    { location: pyrmont, radius: 500, type: "store" },
    (results, status, pagination) => {
      if (status !== "OK" || !results) return;

      addPlaces(results, map);
      moreButton.disabled = !pagination || !pagination.hasNextPage;
      if (pagination && pagination.hasNextPage) {
        getNextPage = () => {
          // Note: nextPage will call the same handler function as the initial call
          pagination.nextPage();
        };
      }
    },
  );
}

function addPlaces(places, map) {
  const placesList = document.getElementById("places");

  for (const place of places) {
    if (place.geometry && place.geometry.location) {
      const image = {
        url: place.icon,
        size: new google.maps.Size(71, 71),
        origin: new google.maps.Point(0, 0),
        anchor: new google.maps.Point(17, 34),
        scaledSize: new google.maps.Size(25, 25),
      };

      new google.maps.Marker({
        map,
        icon: image,
        title: place.name,
        position: place.geometry.location,
      });

      const li = document.createElement("li");

      li.textContent = place.name;
      placesList.appendChild(li);
      li.addEventListener("click", () => {
        map.setCenter(place.geometry.location);
      });
    }
  }
}

window.initMap = initMap;
index.js
Voir l'exemple

Essayer l'exemple

Place Details

En plus de fournir une liste de lieux dans une zone donnée, le service Places peut également renvoyer des informations détaillées sur un lieu en particulier. Lorsqu'un lieu est renvoyé dans une réponse à une recherche de lieu, son ID de lieu peut être utilisé pour demander des informations supplémentaires, comme son adresse complète, son numéro de téléphone, les avis et notes des visiteurs, etc.

Requêtes Place Details

Les requêtes Place Details sont effectuées via un appel à la méthode getDetails() du service.

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

Cette méthode utilise une requête qui contient le placeId du lieu souhaité et des champs indiquant les types de données Places à renvoyer. Découvrez comment référencer un lieu avec un ID de lieu.

Vous devrez également utiliser une méthode de rappel, qui doit gérer le code d'état transmis dans la réponse google.maps.places.PlacesServiceStatus, ainsi que l'objet google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4',
  fields: ['name', 'rating', 'formatted_phone_number', 'geometry']
};

service = new google.maps.places.PlacesService(map);
service.getDetails(request, callback);

function callback(place, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    createMarker(place);
  }
}

Voir un exemple

Champs (Place Details)

Le paramètre fields accepte un tableau de chaînes (noms de champs).

Utilisez le paramètre fields pour spécifier un tableau de types de données de lieu à renvoyer (par exemple, fields: ['address_components', 'opening_hours', 'geometry']). Utilisez un point lorsque vous spécifiez des valeurs composées (par exemple, opening_hours.weekday_text).

Les champs correspondent aux résultats Place Details et sont divisés en trois catégories de facturation : Basic, Contact et Ambiance. Les champs Basic sont facturés au tarif de base et n'entraînent aucuns frais supplémentaires. Les champs Contact et Ambiance sont facturés à un tarif plus élevé. Pour en savoir plus, consultez la grille tarifaire. Les attributions (html_attributions) sont toujours renvoyées avec chaque appel, qu'elles aient été demandées ou non.

Basic

La catégorie "Basic" comprend les champs suivants :
address_components, adr_address, business_status, formatted_address, geometry, icon, icon_mask_base_uri, icon_background_color,name, permanently_closed (obsolète), photo, place_id, plus_code, type, url, utc_offset (obsolète dans la bibliothèque Places, l'API Maps JavaScript), utc_offset_minutes, vicinity

Contact

La catégorie "Contact" comprend les champs suivants :
formatted_phone_number, international_phone_number, opening_hours et website

Ambiance

La catégorie "Ambiance" comprend les champs suivants : price_level, rating, reviews, user_ratings_total

En savoir plus sur les champs de lieu. Pour en savoir plus sur la facturation des requêtes de données de lieu, consultez Utilisation et facturation.

Réponses Place Details

Codes d'état

L'objet de réponse PlacesServiceStatus contient l'état de la requête et éventuellement des informations de débogage qui vous aident à savoir pourquoi la requête Place Details a échoué. Les valeurs possibles sont les suivantes :

  • INVALID_REQUEST : la requête n'est pas valide.
  • OK : la réponse contient un résultat valide.
  • OVER_QUERY_LIMIT : la page Web a dépassé son quota de requêtes.
  • NOT_FOUND : L'emplacement référencé est introuvable dans la base de données Places.
  • REQUEST_DENIED : la page Web n'est pas autorisée à utiliser PlacesService.
  • UNKNOWN_ERROR : la requête PlacesService n'a pas pu être traitée en raison d'une erreur de serveur. Si vous essayez à nouveau, la requête pourrait aboutir.
  • ZERO_RESULTS : aucun résultat n'a été trouvé pour cette requête.

Résultats des requêtes Place Details

Un appel getDetails() qui aboutit renvoie un objet PlaceResult avec les propriétés suivantes :

  • address_components : tableau contenant les composants distincts applicables à cette adresse.

    Chaque composant d'adresse contient généralement les champs suivants :

    • types[] est un tableau indiquant le type du composant d'adresse. Consultez la liste des types compatibles.
    • long_name est la description complète ou le nom du composant d'adresse renvoyé par le geocoder.
    • short_name est un nom textuel abrégé pour le composant d'adresse, s'il est disponible. Par exemple, un composant d'adresse pour l'Alaska peut avoir "Alaska" comme long_name et "AK" comme short_name, correspondant à l'abréviation postale de deux lettres.

    Notez les informations suivantes concernant le tableau address_components[] :

    • Le tableau de composants d'adresse peut contenir formatted_address et des composants supplémentaires.
    • Le tableau n'inclut pas nécessairement toutes les entités politiques contenant une adresse, à l'exception de celles incluses dans formatted_address. Pour récupérer toutes les entités politiques contenant une adresse spécifique, vous devez utiliser le geocoding inversé, en transmettant à la requête la latitude/longitude de l'adresse en tant que paramètre.
    • Le format de la réponse ne sera peut-être pas le même d'une requête à l'autre. En particulier, le nombre d'address_components varie selon l'adresse demandée et peut changer au fil du temps pour la même adresse. Un composant peut changer de position dans le tableau. Le type du composant peut changer. Un composant particulier peut être manquant dans une réponse ultérieure.
  • business_status indique l'état opérationnel du lieu (s'il s'agit d'une entreprise). Il peut contenir l'une des valeurs suivantes :
    • OPERATIONAL
    • CLOSED_TEMPORARILY
    • CLOSED_PERMANENTLY
    Si aucune donnée n'existe, business_status n'est pas renvoyé.
  • formatted_address : adresse lisible de ce lieu.

    Bien souvent, cette adresse équivaut à l'adresse postale. Notez que certains pays, comme le Royaume-Uni, n'autorisent pas la distribution des vraies adresses postales en raison de restrictions de licence.

    L'adresse formatée est composée d'un ou de plusieurs composants d'adresse logiques. Par exemple, l'adresse "111 8th Avenue, New York, NY" comprend les éléments suivants : "111" (le numéro de rue), "8th Avenue" (la route), "New York" (la ville) et "NY" (l'État américain).

    N'analysez pas l'adresse formatée de manière programmatique. Utilisez plutôt les composants d'adresse individuels, que la réponse de l'API inclut en plus du champ d'adresse formaté.

  • formatted_phone_number : numéro de téléphone du lieu, au format conforme à la norme régionale.
  • geometry : fournit les informations liées aux propriétés géométriques du lieu. Par exemple :
    • location fournit la latitude et la longitude du lieu.
    • viewport définit la fenêtre d'affichage préférée sur la carte lorsque ce lieu est affiché.
  • permanently_closed (obsolète) est un indicateur booléen qui précise si le lieu a fermé définitivement ou temporairement (valeur true). N'utilisez pas permanently_closed. Utilisez plutôt business_status pour obtenir l'état opérationnel des entreprises.
  • plus_code : (voir Open Location Code et Plus Codes) référence de lieu encodée, calculée à partir de coordonnées de latitude et de longitude, qui représente une zone : 1/8000e de degré par 1/8000e de degré (environ 14 m x 14 m à l'équateur) ou moins. Vous pouvez utiliser des Plus Codes pour remplacer les adresses postales dans les endroits où elles n'existent pas (où les bâtiments ne sont pas numérotés ni nommés).

    Les Plus Codes sont mis en forme comme un code global et un code composé :

    • global_code est un indicatif de zone à 4 caractères et un indicatif local à 6 caractères ou plus (849VCWC8+R9).
    • compound_code est un code local à six caractères ou plus avec un emplacement explicite (CWC8+R9, Mountain View, CA, États-Unis). N'analysez pas ce contenu de manière programmatique.
    Généralement, le code global et le code composé sont tous deux renvoyés. Toutefois, si le résultat se trouve dans un emplacement distant (par exemple, un océan ou un désert), seul le code global peut être renvoyé.
  • html_attributions : texte de la mention à afficher pour ce résultat de lieu.
  • icon : URL d'une ressource d'image pouvant être utilisée pour représenter le type de ce lieu.
  • international_phone_number contient le numéro de téléphone du lieu au format international. Le format international inclut l'indicatif du pays, précédé du signe plus (+). Par exemple, le international_phone_number pour le bureau de Google à Sydney, en Australie, est +61 2 9374 4000.
  • name : nom du lieu.
  • utc_offset : obsolète dans la Bibliothèque Places, API Maps JavaScript, utilisez utc_offset_minutes à la place.
  • utc_offset_minutes indique le décalage horaire actuel du lieu par rapport à UTC, exprimé en minutes. Par exemple, pour les lieux situés à Sydney, Australie, en heure d'été, ce paramètre est 660 (+11 heures par rapport à l'heure UTC). Pour les lieux situés en Californie, en heure d'hiver, ce paramètre est -480 (-8 heures par rapport à l'heure UTC).
  • opening_hours contient les informations suivantes :
    • open_now (obsolète dans la bibliothèque Places, API Maps JavaScript. Utilisez plutôt opening_hours.isOpen(). Regardez cette vidéo pour découvrir comment utiliser isOpen avec Place Details.) est une valeur booléenne indiquant si l'établissement est ouvert à l'heure actuelle.
    • periods[] est un tableau de périodes d'ouverture sur sept jours à partir du dimanche, dans l'ordre chronologique. Chaque période contient les éléments suivants :
      • open contient une paire d'objets de jour et d'heure décrivant les horaires d'ouverture du lieu :
        • day est un nombre compris entre 0 et 6, correspondant aux jours de la semaine (0 correspondant à dimanche). Par exemple, le 2 correspond au mardi.
        • time peut contenir une heure de la journée au format 24 heures hhmm (les valeurs sont comprises entre 0000 et 2359). time sera indiqué dans le fuseau horaire du lieu.
      • close peut contenir une paire d'objets de jour et d'heure décrivant les horaires de fermeture de l'établissement. Remarque : Si un lieu est toujours ouvert, la section close ne figurera pas dans la réponse. Vous pouvez représenter un lieu toujours ouvert par une période open contenant day avec la valeur 0 et time avec la valeur 0000, et aucun close.
    • weekday_text est un tableau de sept chaînes représentant les horaires d'ouverture formatées pour chaque jour de la semaine. Si un paramètre language a été spécifié dans la requête Places Details, le service Places formate et localise les horaires d'ouverture de manière appropriée pour cette langue. L'ordre des éléments dans le tableau dépend du paramètre language. Pour certaines langues, le premier jour de la semaine est le lundi. Pour d'autres, c'est le dimanche.
  • permanently_closed (obsolète) est un indicateur booléen qui précise si le lieu a fermé définitivement ou temporairement (valeur true). N'utilisez pas permanently_closed. Utilisez plutôt business_status pour obtenir l'état opérationnel des entreprises.
  • photos[] : tableau d'objets PlacePhoto Un PlacePhoto peut être utilisé pour obtenir une photo avec la méthode getUrl(). Vous pouvez également inspecter l'objet à la recherche des valeurs suivantes :
    • height : hauteur maximale de l'image, en pixels.
    • width : largeur maximale de l'image, en pixels.
    • html_attributions : texte de la mention à afficher pour cette photo de lieu.
  • place_id : identifiant textuel qui identifie un lieu de manière unique, et qui peut être utilisé pour récupérer des informations sur ce lieu via une requête Places Details. Découvrez comment référencer un lieu avec un ID de lieu.
  • rating : note du lieu, sur une échelle de 0,0 à 5,0, basée sur l'ensemble des avis des utilisateurs.
  • reviews : tableau comportant jusqu'à cinq avis. Chaque avis contient plusieurs composants :
    • aspects[] contient un tableau d'objets PlaceAspectRating, chacun fournissant une note concernant un seul attribut de l'établissement. Le premier objet du tableau est considéré comme l'aspect principal. Chaque PlaceAspectRating est défini comme suit :
      • type : le nom de l'aspect évalué. Les types suivants sont acceptés : appeal, atmosphere, decor, facilities, food, overall, quality et service.
      • rating est la note de l'utilisateur pour l'aspect évalué, sur une échelle de 0 à 3.
    • author_name est le nom de l'utilisateur qui a envoyé l'avis. Les avis anonymes sont attribués à "Un utilisateur Google". Si un paramètre de langue a été défini, l'expression "Un utilisateur Google" renvoie une chaîne localisée.
    • author_url : URL du profil Google+ de l'utilisateur, si disponible.
    • language : code de langue IETF indiquant la langue utilisée dans l'avis de l'utilisateur. Ce champ contient uniquement l'indicateur principal de la langue et non le tag secondaire qui précise le pays ou la région. Par exemple, toutes les évaluations en anglais sont signalées par "en", et non "en-AU", "en-UK", etc.
    • rating : la note globale que l'utilisateur a attribuée à ce lieu. Il s'agit d'un nombre entier compris entre 1 et 5.
    • text : avis de l'utilisateur. Lorsqu'un utilisateur rédige un avis sur un lieu avec Google Places, les évaluations texte sont considérées comme facultatives. Ce champ peut donc être vide.
  • types : tableau des types pour ce lieu (par exemple, ["political", "locality"] ou ["restaurant", "lodging"]). Ce tableau peut contenir plusieurs valeurs ou être vide. De nouvelles valeurs peuvent être ajoutées sans préavis. Consultez la liste des types compatibles.
  • url : URL de la page Google officielle de ce lieu. Il s'agit de la page Google contenant les informations les plus pertinentes disponibles sur le lieu. Les applications doivent associer ou intégrer cette page à tout écran qui affiche des résultats détaillés sur le lieu à l'utilisateur.
  • vicinity : adresse simplifiée du lieu, comprenant la rue, le numéro et la ville, mais sans le département/la province, le code postal ou le pays. Par exemple, la valeur de vicinity du bureau de Google à Sydney en Australie est de 5/48 Pirrama Road, Pyrmont. La propriété vicinity n'est renvoyée que pour une recherche Nearby Search.
  • website indique le site Web faisant autorité pour ce lieu, comme la page d'accueil d'un établissement.

Remarque : Il est possible que les notes multidimensionnelles ne soient pas disponibles pour tous les lieux. S'il n'y a pas assez d'évaluations, la réponse contenant les détails inclut une note héritée sur une échelle de 0,0 à 5,0 (si disponible) ou aucune note.

Référencer un lieu avec un ID de lieu

Un ID de lieu est une référence unique à un lieu sur une carte Google. Des identifiants de lieu sont disponibles pour la plupart des points géographiques, y compris les entreprises, points de repère, parcs et intersections.

Pour utiliser un identifiant de lieu dans votre application, vous devez d'abord le rechercher. Il est disponible dans le PlaceResult d'une requête Place Search ou Details. Vous pouvez ensuite utiliser cet identifiant de lieu pour rechercher Place Details.

Les ID de lieu ne sont pas soumis aux restrictions de mise en cache stipulées dans la section 3.2.3(b) des conditions d'utilisation de Google Maps Platform. Vous pouvez donc stocker des ID de lieu pour les utiliser ultérieurement. Pour connaître les bonnes pratiques de stockage d'ID de lieu, consultez la présentation des ID de lieu.

var map;

function initialize() {
  // Create a map centered in Pyrmont, Sydney (Australia).
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.8666, lng: 151.1958},
    zoom: 15
  });

  // Search for Google's office in Australia.
  var request = {
    location: map.getCenter(),
    radius: '500',
    query: 'Google Sydney'
  };

  var service = new google.maps.places.PlacesService(map);
  service.textSearch(request, callback);
}

// Checks that the PlacesServiceStatus is OK, and adds a marker
// using the place ID and location from the PlacesService.
function callback(results, status) {
  if (status == google.maps.places.PlacesServiceStatus.OK) {
    var marker = new google.maps.Marker({
      map: map,
      place: {
        placeId: results[0].place_id,
        location: results[0].geometry.location
      }
    });
  }
}

google.maps.event.addDomListener(window, 'load', initialize);

Photos du lieu

La fonctionnalité Place Photo vous permet d'ajouter du contenu photographique de qualité supérieure à votre site. Le service Photo vous donne accès à des millions de photos stockées dans les bases de données Places et Google + Local. Lorsque vous obtenez des informations sur un lieu à l'aide d'une requête de Places Details, des références photo sont renvoyées pour le contenu photographique correspondant. Les requêtes Nearby Search et Text Search renvoient également une référence photo unique par lieu, le cas échéant. Le service Photo vous permet ensuite d'accéder aux photos référencées et de redimensionner l'image pour qu'elle s'adapte parfaitement à votre application.

Un tableau d'objets PlacePhoto sera renvoyé dans l'objet PlaceResult pour toute requête getDetails(), textSearch() ou nearbySearch() effectuée concernant PlacesService.

Remarque : Le nombre de photos renvoyées varie en fonction de la requête.

  • Une recherche Nearby Search ou Text Search renvoie au maximum un objet PlacePhoto.
  • Une requête Details renvoie jusqu'à 10 objets PlacePhoto.

Vous pouvez demander l'URL de l'image associée en appelant la méthode PlacePhoto.getUrl() et en transmettant un objet PhotoOptions valide. L'objet PhotoOptions vous permet de spécifier la hauteur et la largeur maximales souhaitées pour l'image. Si vous spécifiez une valeur pour maxHeight et maxWidth, le service de photo redimensionne l'image à la plus petite des deux tailles, tout en conservant le format d'origine.

L'extrait de code suivant accepte un objet de lieu et ajoute un repère sur la carte si une photo est disponible. L'image du repère par défaut est remplacée par une version réduite de la photo.

function createPhotoMarker(place) {
  var photos = place.photos;
  if (!photos) {
    return;
  }

  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    title: place.name,
    icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35})
  });
}

Les photos renvoyées par le service Photo sont extraites de plusieurs sources : elles peuvent être fournies par des propriétaires d'établissement ou par des utilisateurs. Dans la plupart des cas, les photos de lieu peuvent être utilisées sans attribution, ou contiendront déjà l'attribution. Toutefois, si l'élément photo renvoyé inclut une valeur dans le champ html_attributions, vous devez inclure l'attribution supplémentaire dans votre application partout où vous affichez l'image.