Bibliothèque Places

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.
Sélectionnez une plate-forme : Android iOS JavaScript Service Web

Présentation

Les fonctions de la bibliothèque Places de l'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) contenus dans une zone définie, comme les limites d'une carte ou 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 saisie semi-automatique remplit le reste. Pour en savoir plus, consultez la documentation sur la saisie semi-automatique.

Premiers pas

Si vous ne connaissez pas l'API Maps JavaScript ni JavaScript, nous vous recommandons de consulter JavaScript et d'obtenir une clé API avant de commencer.

Activer les API

Avant d'utiliser la bibliothèque Places dans l'API Maps JavaScript, assurez-vous qu'elle est activée dans Google Cloud Console, dans le projet que vous avez configuré pour l'API Maps JavaScript.

Pour afficher la liste des API activées :

  1. Accédez à Google Cloud Console.
  2. Cliquez sur le bouton Sélectionner un projet, puis sélectionnez le projet que vous avez configuré pour l'API Maps JavaScript et 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 n'est pas répertoriée, 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 API Places, puis sélectionnez-la dans la liste des résultats.
    3. Sélectionnez ACTIVER. Une fois le processus terminé, 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&libraries=places&callback=initMap">
</script>

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

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

L'application de restrictions d'API à vos clés limite l'utilisation de la clé API à un ou plusieurs SDK ou API. Les requêtes adressées à 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 Google Cloud Console.
  2. Cliquez sur la liste déroulante du projet, puis sélectionnez le projet qui contient 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 répertoriée, vous devez l'activer.)
  6. Cliquez sur ENREGISTRER.

Limites d'utilisation et politiques

Quotas

L'API Places Library, JavaScript partage un quota d'utilisation avec l'API Places, comme décrit dans la documentation sur les limites d'utilisation. La limite de débit des requêtes par seconde est appliquée par session utilisateur, quel que soit le nombre d'utilisateurs qui partagent le même projet*.

Remarque: Lorsque vous chargez l'API pour la première fois, un quota initial de requêtes vous est attribué. Une fois que vous avez utilisé ce quota, l'API applique des limites de débit à d'autres requêtes par seconde. Si trop de requêtes sont effectuées dans un délai donné, l'API renvoie un code de réponse OVER_QUERY_LIMIT. La limite de débit par session empêche l'utilisation de services côté client pour les requêtes par lot. Pour les requêtes par lot, utilisez nos API de services Web.

Règles

L'utilisation de l'API Places Library et Maps JavaScript doit respecter les Règles décrites pour l'API Places.

Recherches de lieux

Le service Places vous permet d'effectuer les recherches suivantes:

  • 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 en fonction d'un numéro de téléphone.
  • La recherche à proximité 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 (restaurants, magasins, bureaux, etc.), ainsi que des résultats géocodés qui indiquent des adresses, des zones politiques telles que des villes et d'autres points d'intérêt.

Requêtes Find Place

Une requête Find Place vous permet 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:

Rechercher un lieu à partir d'une requête

La fonctionnalité Find Place from Query prend une entrée de texte et renvoie un lieu. Vous pouvez saisir n'importe quel type de données de lieu, par exemple un nom ou une adresse d'entreprise. Pour effectuer une requête Find Place from Query, appelez la méthode PlaceServicefindPlaceFromQuery(), qui utilise les paramètres suivants:

  • query (obligatoire) Chaîne de texte dans laquelle la recherche doit être effectuée, par exemple "restaurant" ou "123 rue des Champs". 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 renvoyer pas de résultats valides. L'API Places renvoie les correspondances de candidats en fonction de cette chaîne et classe les résultats en fonction de leur pertinence.
  • fields (obligatoire) Un ou plusieurs champs spécifiant les types de données Place à renvoyer.
  • locationBias (Facultatif) Coordonnées définissant la zone à rechercher. Il peut s'agir de l'un des éléments suivants :
    • Ensemble de coordonnées de latitude et de longitude spécifiées en tant qu'objets LatLngLiteral ou LatLng
    • Limites rectangulaires (deux paires de latitude/longitude ou un objet LatLngBounds)
    • 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 montre un appel à findPlaceFromQuery(), en recherchant le "musée d'Art contemporain australien" et en incluant 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

Rechercher le lieu à partir du numéro de téléphone

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

  • phoneNumber (obligatoire) Numéro de téléphone au format E.164.
  • fields (obligatoire) Un ou plusieurs champs spécifiant les types de données Place à renvoyer.
  • locationBias (facultatif) Coordonnées définissant la zone à rechercher. Il peut s'agir de l'un des éléments suivants :
    • Ensemble de coordonnées de latitude et de longitude spécifiées en tant qu'objets LatLngLiteral ou LatLng
    • Limites rectangulaires (quatre points de latitude/longitude ou un objet LatLngBounds)
    • 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 de recherche de lieux et sont divisés en trois catégories de facturation: Basic, Contact et Atmosphere. Les champs de base sont facturés au tarif de base et n'entraînent aucuns frais supplémentaires. Les champs de contact et d'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 de base 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

Coordonnées

La catégorie "Contact" inclut le champ suivant : opening_hours
(obsolète dans les API Places Library et Maps JavaScript. Utilisez une requête Places Details pour obtenir les résultats opening_hours.

Atmosphère

La catégorie "Atmosphere" 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 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 sur laquelle effectuer la recherche:

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

Vous pouvez également utiliser une valeur LatLngBounds.

Définissez un rayon à rechercher (en mètres), centré sur une zone particulière:

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

Requêtes Nearby Search

Une recherche à proximité vous permet de rechercher des lieux dans une zone spécifiée par mot clé ou par type. Une recherche à proximité doit toujours inclure un lieu, qui peut être spécifié de deux manières:

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

Une recherche Places Nearby est lancée via un appel à la méthode nearbySearch() 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 :

  • Au choix :
    • bounds, qui doit être un objet google.maps.LatLngBounds définissant la zone de recherche rectangulaire ; ou
    • un location et un radius. Le premier utilise un objet google.maps.LatLng et le second un entier simple représentant le rayon du cercle en mètres. Le rayon maximal autorisé est de 50 000 mètres. Notez que lorsque rankBy est défini sur DISTANCE, vous devez spécifier un élément location, mais pas les champs radius ou 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 plus abordable) 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. Les lieux qui ne précisent pas d'horaires d'ouverture dans la base de données Google Adresses ne sont pas renvoyés si vous incluez ce paramètre dans votre requête. Définir openNow sur false n'a aucun effet.
  • rankBy (facultatif) : spécifie l'ordre dans lequel les résultats sont répertoriés. Les valeurs possibles sont les suivantes :
    • google.maps.places.RankBy.PROMINENCE (par défaut) Cette option trie les résultats en fonction de leur importance. Le classement privilégie les lieux importants situés dans le rayon défini pour les lieux à proximité qui correspondent, mais qui sont moins visibles. La proéminence peut être affectée par le classement d'un lieu dans l'index Google, sa popularité mondiale 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 en fonction de 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, un ou plusieurs des éléments keyword, name ou type sont requis.
  • type : limite les résultats aux lieux correspondant au type spécifié. Vous ne pouvez spécifier qu'un seul type (si plusieurs types sont fournis, tous les types qui suivent la première entrée sont ignorés). Consultez la liste des types acceptés.

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 de recherche textuelle Google Adresses est un service Web qui renvoie des informations sur un ensemble de lieux en fonction d'une chaîne (par exemple, "pizza à New York" ou "magasins de chaussures à proximité d'Ottawa"). Le service renvoie une liste de lieux correspondant à la chaîne de texte et tout biais de localisation défini. La réponse à la recherche inclut une liste de lieux. Vous pouvez envoyer une requête Places Details pour en savoir plus sur les lieux dans la réponse.

Les recherches textuelles sont lancées avec un appel à la méthode PlacesService's textSearch().

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 dans laquelle la recherche doit être effectuée, par exemple "restaurant" ou "123 rue des Champs". 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 renvoyer pas de résultats valides. Le service Places renvoie les correspondances de candidats en fonction de cette chaîne et les classe en fonction de leur pertinence. Ce paramètre devient facultatif si le paramètre 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. Les lieux qui ne précisent pas d'horaires d'ouverture dans la base de données Google Adresses ne sont pas renvoyés si vous incluez ce paramètre dans votre requête. Définir openNow sur false n'a aucun effet.
    • minPriceLevel et maxPriceLevel : limite les résultats aux seuls endroits situés dans le niveau de prix spécifié Les valeurs valides sont comprises entre 0 (le plus abordable) et 4 (le plus cher), inclus.
    • Au choix :
      • bounds : objet google.maps.LatLngBounds définissant le rectangle dans lequel effectuer la recherche
      • location et radius : vous pouvez influencer les résultats pour un cercle spécifié en transmettant un paramètre location et un paramètre radius. Cette commande indique au service Places de privilégier les résultats figurant dans 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 utilise un nombre 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é. Vous ne pouvez spécifier qu'un seul type (si plusieurs types sont fournis, tous les types qui suivent la première entrée sont ignorés). Consultez la liste des types acceptés.

Vous devez également transmettre une méthode de rappel à textSearch() pour gérer l'objet résultats et une 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 peut contenir des informations de débogage pour vous aider à identifier la raison pour laquelle la requête de lieu a échoué. Les valeurs possibles sont les suivantes :

  • INVALID_REQUEST: cette 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 du 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'un établissement). 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 de texte.

    Souvent, cette adresse équivaut à l'adresse postale. Notez que dans certains pays, tels que le Royaume-Uni, la distribution de véritables adresses postales n'est pas autorisée en raison de restrictions de licence.

    L'adresse formatée est composée de manière logique d'un ou de plusieurs composants d'adresse. Par exemple, l'adresse "111 8th Avenue, New York, NY" est constituée des éléments suivants : "111" (le numéro de rue), "8th Avenue" (la route), "New York" (la ville) et "NY" (l'État des États-Unis).

    N'analysez pas l'adresse formatée par programmation. Vous devez utiliser les composants d'adresse individuels, que la réponse de l'API inclut en plus du champ d'adresse mis en forme.

  • geometry : informations liées à la géométrie 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 une option booléenne indiquant si le lieu a été fermé définitivement ou temporairement (valeur true). N'utilisez pas permanently_closed. Utilisez plutôt business_status pour obtenir l'état opérationnel des établissements.
  • plus_code (voir Open Location Code et le code plus codes) est une référence de lieu encodée à partir de la latitude et de la longitude. Elle représente une zone géographique: 1/8000th de degré par 1/8000th de degré (environ 14m x 14m à l'équateur) ou moins. Les Plus Codes peuvent être utilisés 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).

    Le plus code est mis en forme comme un code global et un code composé:

    • global_code est un indicatif de zone de 4 caractères et un indicatif local à 6 caractères ou plus (849VCWC8+R9).
    • compound_code correspond à un code local à six caractères ou plus avec un emplacement explicite (CWC8+R9, Mountain View, CA, États-Unis). N'analysez pas ce contenu par programmation.
    Généralement, le code global et le code composé sont 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 d'attributions à afficher lors de l'affichage des résultats de recherche. Chaque entrée du tableau contient le texte HTML d'une seule attribution. Remarque : Il s'agit d'un regroupement de toutes les attributions pour l'intégralité de la réponse de recherche. Tous les objets PlaceResult de la réponse contiennent donc des listes d'attribution identiques.
  • icon renvoie l'URL associée à une icône PNG colorée de 71 x 71 pixels.
  • icon_mask_base_uri renvoie l'URL de base d'une icône non colorée, moins l'extension .svg ou .png.
  • icon_background_color renvoie le code couleur HEX 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 de l'API Maps JavaScript, utilisez 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 le nom de la rue, le numéro de rue et la localité, mais pas la province/l'État, le code postal ni le pays. Par exemple, le bureau Google de Sydney en Australie possède la valeur vicinity 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. Cependant, 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 à des pages supplémentaires, vous devez capturer l'objet PlaceSearchPagination via une fonction de rappel. L'objet PlaceSearchPagination est défini comme suit:

  • hasNextPage est une propriété booléenne qui indique si d'autres résultats sont disponibles. true lorsqu'il existe une page de résultats supplémentaire.
  • nextPage() est une fonction qui renvoie le prochain ensemble de résultats. Après avoir effectué une recherche, vous devez attendre deux secondes pour 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 la page de résultats suivante. Notez que chaque recherche est comptabilisée comme une seule requête par rapport à vos limites d'utilisation.

L'exemple ci-dessous montre comment modifier votre fonction de rappel pour capturer l'objet PlaceSearchPagination afin de pouvoir 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;

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;
Voir un exemple

Essayer l'exemple

Place Details

En plus de fournir une liste de lieux dans une zone, le service Places peut également renvoyer des informations détaillées sur un lieu spécifique. Lorsqu'un lieu est renvoyé dans une réponse de recherche sur un lieu, son identifiant peut être utilisé pour demander des informations supplémentaires sur ce lieu, telles que son adresse complète, son numéro de téléphone, les notes et les avis des utilisateurs, etc.

Requêtes Place Details

Les requêtes Place Details sont demandé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 lieu souhaité (placeId) et des champs indiquant les types de données Places à renvoyer. Découvrez comment référencer un lieu avec un ID de lieu.

Il utilise également 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 (détails du lieu)

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_component', '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 Atmosphere. Les champs de base sont facturés au tarif de base et n'entraînent aucuns frais supplémentaires. Les champs de contact et d'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 de base inclut les champs suivants :
address_component, 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 de Maps Library, dans Maps/ ;

Coordonnées

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

Atmosphère

La catégorie "Atmosphere" comprend les champs suivants : price_level, rating, review, 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 la section Utilisation et facturation.

Réponses aux requêtes de détails de lieu

Codes d'état

L'objet de réponse PlacesServiceStatus contient l'état de la requête et peut contenir des informations de débogage pour vous aider à identifier la raison pour laquelle la requête Places Details a échoué. Les valeurs possibles sont les suivantes :

  • INVALID_REQUEST : cette 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 du 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 réussi getDetails() renvoie un PlaceResult objet doté des 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 ou le nom en texte intégral du composant d'adresse renvoyé par le géocodeur.
    • short_name est un nom de texte abrégé pour le composant d'adresse, s'il est disponible. Par exemple, un composant d'adresse pour l'État d'Alaska peut avoir un long_name d'Alaska et un short_name d'AK à l'aide de l'abréviation postale de deux lettres.

    Notez les informations suivantes sur le tableau address_components[]:

    • Le tableau de composants d'adresse peut contenir plus de composants que formatted_address.
    • 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 latitude/longitude de l'adresse en tant que paramètre à la requête.
    • Il n'est pas garanti que le format de la réponse reste le même entre les requêtes. En particulier, le nombre de 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'un établissement). 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.

    Souvent, cette adresse équivaut à l'adresse postale. Notez que dans certains pays, tels que le Royaume-Uni, la distribution de véritables adresses postales n'est pas autorisée en raison de restrictions de licence.

    L'adresse formatée est composée de manière logique d'un ou de plusieurs composants d'adresse. Par exemple, l'adresse "111 8th Avenue, New York, NY" est constituée des éléments suivants : "111" (le numéro de rue), "8th Avenue" (la route), "New York" (la ville) et "NY" (l'État des États-Unis).

    N'analysez pas l'adresse formatée par programmation. Vous devez utiliser les composants d'adresse individuels, que la réponse de l'API inclut en plus du champ d'adresse mis en forme.

  • formatted_phone_number : numéro de téléphone du lieu, au format conformément à la Convention régionale du numéro.
  • geometry: informations liées à la géométrie 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 une option booléenne indiquant si le lieu a été fermé définitivement ou temporairement (valeur true). N'utilisez pas permanently_closed. Utilisez plutôt business_status pour obtenir l'état opérationnel des établissements.
  • plus_code (voir Open Location Code et le code plus codes) est une référence de lieu encodée à partir de la latitude et de la longitude. Elle représente une zone géographique: 1/8000th de degré par 1/8000th de degré (environ 14m x 14m à l'équateur) ou moins. Les Plus Codes peuvent être utilisés 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).

    Le plus code est mis en forme comme un code global et un code composé:

    • global_code est un indicatif de zone de 4 caractères et un indicatif local à 6 caractères ou plus (849VCWC8+R9).
    • compound_code correspond à un code local à six caractères ou plus avec un emplacement explicite (CWC8+R9, Mountain View, CA, États-Unis). N'analysez pas ce contenu par programmation.
    Généralement, le code global et le code composé sont 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 d'attribution à afficher pour ce résultat de lieu.
  • icon: URL d'une ressource image pouvant 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 et le 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 l'API Places Library et Maps JavaScript : utilisez utc_offset_minutes à la place.
  • utc_offset_minutes indique le nombre de minutes de décalage horaire actuel de ce lieu par rapport à UTC. Par exemple, pour les lieux situés à Sydney, en Australie, pendant l'heure d'été, ce paramètre est de 660 (+11 heures par rapport à l'heure UTC), et pour les lieux situés en Californie, en heure d'été, il est de -480 (-88 par rapport à l'heure d'été).
  • opening_hours contient les informations suivantes :
    • open_now (obsolète dans la bibliothèque Places, l'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[] correspond à un tableau de périodes d'ouverture couvrant 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 qui décrivent à quel moment le lieu ouvre :
        • day est un nombre compris entre 0 et 6, correspondant aux jours de la semaine commençant le dimanche. Par exemple, 2 signifie mardi.
        • time peut contenir une heure de la journée au format 24 heures hhmm (les valeurs sont comprises entre 0000 et 2359). Le time sera indiqué dans le fuseau horaire du lieu.
      • close peut contenir une paire d'objets de jour et d'heure décrivant la fermeture du lieu. Remarque : Si un lieu est toujours ouvert, la section close ne figurera pas dans la réponse. Les applications peuvent s'appuyer sur le fait qu'elles soient toujours ouvertes et représentées sous la forme d'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 mis en forme 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 ce tableau dépend du paramètre language. Certaines langues commencent la semaine le lundi et d'autres le dimanche.
  • permanently_closed (obsolète) est une option booléenne indiquant si le lieu a été fermé définitivement ou temporairement (valeur true). N'utilisez pas permanently_closed. Utilisez plutôt business_status pour obtenir l'état opérationnel des établissements.
  • 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 d'attribution à afficher avec 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 de l'établissement, comprise entre 0,0 et 5,0 basée sur l'ensemble des avis des utilisateurs.
  • reviews est un tableau contenant jusqu'à cinq avis. Chaque avis comprend plusieurs composants :
    • aspects[] contient un tableau d'objets PlaceAspectRating, chacun fournissant une note pour 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 est le nom de l'aspect évalué. Les types suivants sont acceptés: appeal, atmosphere, decor, facilities, food, overall, quality et service.
      • rating : note des utilisateurs pour cet aspect spécifique, 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 correspond à l'URL du profil Google+ de l'utilisateur, le cas échéant.
    • language est un code de langue IETF indiquant la langue utilisée dans l'avis de l'utilisateur. Ce champ ne contient que la balise de langue principale, et non la balise secondaire indiquant le pays ou la région. Par exemple, tous les avis en anglais sont associés au libellé "fr" et non "fr-FR" ou "fr-FR", etc.
    • rating est la note globale attribuée à ce lieu par l'utilisateur. Il s'agit d'un nombre entier compris entre 1 et 5.
    • text l'avis de l'utilisateur. Lorsque vous évaluez un établissement avec Google Adresses, les avis textuels sont considérés comme facultatifs. Par conséquent, ce champ peut ê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 meilleures informations disponibles sur le lieu. Les applications doivent inclure un lien vers cette page ou l'intégrer sur n'importe quel écran qui présente à l'utilisateur des résultats détaillés sur le lieu.
  • vicinity: adresse simplifiée du lieu, comprenant le nom de la rue, le numéro de rue et la localité, mais pas la province/l'État, le code postal ni le pays. Par exemple, le bureau Google de Sydney en Australie possède la valeur vicinity 5/48 Pirrama Road, Pyrmont. La propriété vicinity n'est renvoyée que pour une recherche à proximité.
  • website indique le site Web faisant autorité pour ce lieu, tel que la page d'accueil d'un établissement.

Remarque:Les évaluations multidimensionnelles peuvent ne pas être disponibles pour tous les établissements. Si le nombre d'avis est trop faible, la réponse détaillée inclut une ancienne note sur une échelle de 0.0 à 5.0 (si disponible) ou aucune note.

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

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

Pour utiliser un identifiant de lieu dans votre application, vous devez d'abord rechercher cet identifiant, disponible dans 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 indiquées dans la section 3.2.3(a) des conditions d'utilisation de Google Maps Platform. Vous pouvez donc stocker des identifiants de lieu pour une utilisation ultérieure. 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 haute qualité à votre site. Le service Photo vous permet d'accéder aux 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 Places Details, des références photo sont renvoyées pour le contenu photographique approprié. Les requêtes Nearby Search et Text Search renvoient également une seule référence photo 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 à la taille optimale pour votre application.

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

Remarque:Le nombre de photos renvoyées varie selon les demandes.

  • Une recherche à proximité ou une recherche textuelle 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 un maxWidth, le service de photo redimensionne l'image à la plus petite des deux tailles, tout en conservant les proportions d'origine.

L'extrait de code suivant accepte un objet de lieu et ajoute un repère à la carte s'il existe une photo. L'image par défaut du repère est remplacée par une petite version 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 Photos sont extraites de plusieurs sources, y compris des propriétaires d'établissement et des photos fournies par les utilisateurs. Dans la plupart des cas, ces photos peuvent être utilisées sans mention d'attribution ou en comporteront une partie. 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.