Bibliothèque Places

  1. Présentation
  2. Charger la bibliothèque
  3. Recherches de lieux
    1. Requêtes Nearby Search
    2. Requêtes Text Search
    3. Requêtes Radar Search
    4. Réponses aux recherches
    5. Accéder à des résultats supplémentaires
  4. Place Details
    1. Requêtes Place Details
    2. Réponses aux requêtes Place Details
  5. Référencer un lieu avec un identifiant de lieu
  6. Place Photos

Présentation

Les fonctions de la bibliothèque JavaScript Google Places permettent à votre application de rechercher des lieux (définis dans cette API en tant qu'établissements, points géographiques ou points d'intérêt) dans une zone donnée, comme à l'intérieur des limites d'une carte ou autour d'un point fixe.

Google Places API propose une fonctionnalité de saisie semi-automatique (Autocomplete) que vous pouvez utiliser pour reproduire dans votre application le comportement de frappe anticipée qu'utilise le champ de recherche de Google Maps. Lorsqu'un utilisateur commence à saisir une adresse, la fonction de saisie semi-automatique affiche automatiquement le reste de l'adresse. Pour plus d'informations, voir la documentation sur la saisie automatique.

Charger la bibliothèque

Le service Places est une bibliothèque autonome, séparée du code Maps API JavaScript principal. Pour utiliser les fonctionnalités contenues dans cette bibliothèque, vous devez d'abord la charger en utilisant le paramètre libraries dans l'URL bootstrap de Maps API :

<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"></script>

Pour plus d'informations, voir la présentation des bibliothèques.

Conditions requises liées aux logos

Si votre application contient des données Google Places API sur une carte, cette carte doit être fournie par Google.

Si votre application contient des données Google Places API sur une page ou une vue sans carte Google, vous devez accompagner ces données d'un logo « Powered by Google ». Par exemple, si votre application affiche une liste de lieux sur un onglet et une carte Google incluant ces lieux sur un autre onglet, le premier onglet doit inclure le logo « Powered by Google ».

Pour une utilisation sur fond blanc Pour une utilisation sur un autre fond

Le fichier zip suivant contient le logo « Powered by Google » aux dimensions appropriées pour applications de bureau, Android et iOS. Vous ne devez en aucun cas redimensionner ou modifier ces logos.

Télécharger : powered-by-google.zip

Recherches de lieux

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

  • Les requêtes Nearby Search renvoient une liste de lieux situés à proximité de la position géographique de l'utilisateur.
  • Les requêtes Text Search renvoient une liste de lieux situés à proximité en fonction d'une chaîne de recherche, par exemple « Pizza ».
  • Les requêtes Radar Search renvoient une liste importante de lieux dans un rayon de recherche donné, mais avec moins de détails que les requêtes Nearby Search ou Text Search.
  • Les requêtes de détails de lieu renvoient des informations détaillées sur un lieu spécifique, notamment des avis d'utilisateurs.

Les informations renvoyées peuvent inclure des établissements, tels que des restaurants, des magasins ou des bureaux, ainsi que des résultats « géocodés » indiquant des adresses, des entités administratives, telles que des communes ou des villes, et d'autres points d'intérêt.

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 point géographique, qui doit être spécifié en utilisant au choix :

  • des valeurs LatLngBounds.
  • une zone circulaire définie par la combinaison entre la propriété location, qui spécifie le centre du cercle en tant qu'objet LatLng, et un rayon mesuré en mètres.

Pour lancer une requête Places Nearby Search, vous devez appeler la méthode nearbySearch() de PlacesService, qui renvoie un tableau d'objets PlaceResult. Notez que la méthode nearbySearch() remplace la méthode search() depuis 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 le champ :
    • bounds, qui doit être un objet google.maps.LatLngBounds définissant la zone de recherche rectangulaire ; soit les champs
    • location et radius, le premier utilisant un objet google.maps.LatLng et le deuxième nécessitant un simple chiffre entier représentant le rayon du cercle en mètres. Le rayon maximum autorisé est de 50 000 mètres.
  • keyword (facultatif) – Terme à comparer à tous les champs disponibles, y compris, mais sans s'y limiter, le nom, le type et l'adresse, ainsi que les avis de clients et autre contenu tiers.
  • minPriceLevel et maxPriceLevel (facultatifs) – Limitent les résultats aux seuls lieux compris dans la fourchette de prix définie. Les valeurs valides sont comprises entre 0 (le moins cher) et 4 (le plus cher), inclus.
  • name (facultatif) – Terme à comparer aux noms de lieu. Les résultats sont limités à ceux contenant la valeur name (le nom) indiquée. Notez qu'un lieu peut être associé à d'autres noms, outre son nom répertorié. L'API tente de comparer la valeur name indiquée à chacun de ces noms. Par conséquent, des lieux peuvent être renvoyés dans les résultats avec des noms répertoriés ne correspondant pas au terme de la recherche, mais dont les noms associés correspondent.
  • openNow (facultatif) – Valeur booléenne indiquant que le service Places doit renvoyer uniquement les lieux ouverts au moment de la recherche. 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 le paramètre openNow sur false n'a aucun effet.
  • rankBy (facultatif) – Spécifie l'ordre d'affichage des résultats. Les valeurs possibles sont les suivantes :
    • google.maps.places.RankBy.PROMINENCE (valeur 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 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 la valeur google.maps.places.RankBy.PROMINENCE est spécifiée, le paramètre radius est requis.
    • google.maps.places.RankBy.DISTANCE. Cette option classe par ordre croissant les résultats de la recherche en fonction de leur distance par rapport à un lieu déterminé par le paramètre location (obligatoire). Le paramètre RankBy.DISTANCE ne prend pas en charge les limites et/ou rayons personnalisés. Lorsque le paramètre RankBy.DISTANCE est spécifié, un ou plusieurs des champs keyword, name ou types sont requis.
  • types (facultatif) – Tableau contenant un ou plusieurs des types pris en charge figurant dans la liste Google Places API : Types de lieu pris en charge. Le service renvoie les résultats correspondant à tout type spécifié.

Vous devez également transmettre une méthode de rappel à la fonction nearbySearch() pour gérer l'objet results 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',
    types: ['store']
  };

  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++) {
      var place = results[i];
      createMarker(results[i]);
    }
  }
}

Voir l'exemple (place-search.html)

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 ; par exemple, « pizza à New York » ou « magasin de chaussures près d'Ottawa ». Ce service répond avec 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 de détails sur le lieu pour obtenir plus d'informations sur les lieux indiqués dans la réponse.

Les requêtes Text Search sont initiées par 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 porte la recherche, par exemple « restaurant ». Le service Places renvoie les résultats correspondant à cette chaîne et les classe en fonction de leur pertinence.
  • Facultatif :
    • openNow – Valeur booléenne indiquant que le service Places doit renvoyer uniquement les lieux ouverts au moment de la recherche. 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 le paramètre openNow sur false n'a aucun effet.
    • minPriceLevel et maxPriceLevel – Limitent les résultats aux seuls lieux compris dans la fourchette de prix définie. Les valeurs valides sont comprises entre 0 (le moins cher) et 4 (le plus cher), inclus.
    • Soit le champ :
      • bounds – Objet google.maps.LatLngBounds définissant le rectangle dans lequel effectuer la recherche ; soit les champs
      • location et radius – Vous pouvez affiner les résultats à un cercle donné en spécifiant 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. Le paramètre location utilise un objet google.maps.LatLng et le paramètre radius utilise un simple chiffre entier représentant le rayon du cercle en mètres. Le rayon maximum autorisé est de 50 000 mètres.
    • types – Tableau contenant un ou plusieurs des types pris en charge figurant dans la liste Google Places API : Types de lieu pris en charge. Le service renvoie les résultats correspondant à tout type spécifié.

Vous devez également transmettre une méthode de rappel à la fonction textSearch() pour gérer l'objet results 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]);
    }
  }
}

Requêtes Radar Search

Une requête Radar Search permet de rechercher des lieux dans un rayon de recherche défini par mot clé, par type ou par nom. Les requêtes Radar Search renvoient plus de résultats que les requêtes Nearby Search ou Text Search, mais ces résultats contiennent moins de champs. Pour obtenir plus d'informations sur les lieux indiqués dans la réponse, vous pouvez appeler la méthode PlacesService.getDetails().

Les objets PlaceResult renvoyés par la méthode radarSearch() incluent uniquement les propriétés suivantes :

  • geometry.location
  • place_id
  • reference (Remarque : La propriété reference est progressivement abandonnée au profit de place_id, tel que décrit dans l'avis lié à l'abandon sur cette page.)

Pour lancer une requête Places Radar Search, vous devez appeler la méthode radarSearch() de PlacesService, qui renvoie un tableau contenant jusqu'à 200 objets PlaceResult.

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

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

  • Soit le champ :
    • bounds, qui doit être un objet google.maps.LatLngBounds définissant la zone de recherche rectangulaire ; soit les champs
    • location et radius, le premier utilisant un objet google.maps.LatLng et le deuxième nécessitant un simple chiffre entier représentant le rayon du cercle en mètres. Le rayon maximum autorisé est de 50 000 mètres.
  • Au moins l'un des deux paramètres suivants :
    • keyword (facultatif) – Terme à comparer à tous les champs disponibles, y compris, mais sans s'y limiter, le nom, le type et l'adresse, ainsi que les avis de clients et autre contenu tiers.
    • name (facultatif) – Terme à comparer aux noms de lieu. Les résultats sont limités à ceux contenant la valeur name (le nom) indiquée. Notez qu'un lieu peut être associé à d'autres noms, outre son nom répertorié. L'API tente de comparer la valeur name indiquée à chacun de ces noms. Par conséquent, des lieux peuvent être renvoyés dans les résultats avec des noms répertoriés ne correspondant pas au terme de la recherche, mais dont les noms associés correspondent.
    • types (facultatif) – Tableau contenant un ou plusieurs des types pris en charge figurant dans la liste Google Places API : Types de lieu pris en charge. Le service renvoie les résultats correspondant à tout type spécifié.
  • Facultatif :
    • minPriceLevel et maxPriceLevel (facultatifs) – Limitent les résultats aux seuls lieux compris dans la fourchette de prix définie. Les valeurs valides sont comprises entre 0 (le moins cher) et 4 (le plus cher), inclus.
    • openNow – Valeur booléenne indiquant que le service Places doit renvoyer uniquement les lieux ouverts au moment de la recherche. 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 le paramètre openNow sur false n'a aucun effet.

Vous devez également transmettre une méthode de rappel à la fonction radarSearch() pour gérer l'objet PlaceResults et google.maps.places.PlacesServiceStatus.

var map;
var infoWindow;
var service;

function initMap() {
  map = new google.maps.Map(document.getElementById('map'), {
    center: {lat: -33.867, lng: 151.206},
    zoom: 15,
    styles: [{
      stylers: [{ visibility: 'simplified' }]
    }, {
      elementType: 'labels',
      stylers: [{ visibility: 'off' }]
    }]
  });

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

  // The idle event is a debounced event, so we can query & listen without
  // throwing too many requests at the server.
  map.addListener('idle', performSearch);
}

function performSearch() {
  var request = {
    bounds: map.getBounds(),
    keyword: 'best view'
  };
  service.radarSearch(request, callback);
}

function callback(results, status) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    console.error(status);
    return;
  }
  for (var i = 0, result; result = results[i]; i++) {
    addMarker(result);
  }
}

function addMarker(place) {
  var marker = new google.maps.Marker({
    map: map,
    position: place.geometry.location,
    icon: {
      url: 'http://maps.gstatic.com/mapfiles/circle.png',
      anchor: new google.maps.Point(10, 10),
      scaledSize: new google.maps.Size(10, 17)
    }
  });

  google.maps.event.addListener(marker, 'click', function() {
    service.getDetails(place, function(result, status) {
      if (status !== google.maps.places.PlacesServiceStatus.OK) {
        console.error(status);
        return;
      }
      infoWindow.setContent(result.name);
      infoWindow.open(map, marker);
    });
  });
}

Voir l'exemple (place-radar-search.html)

Réponses aux recherches

Codes de statut

L'objet de réponse PlacesServiceStatus contient le statut 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 :

  • ERROR : Un problème est survenu lors de la communication avec les serveurs Google.
  • 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 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 nearbySearch() et textSearch() renvoient un tableau d'objets PlaceResult. La fonction radarSearch() renvoie un sous-ensemble des champs de l'objet PlaceResult, tel que décrit ci-dessus.

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

  • formatted_address est une chaîne contenant une adresse lisible de ce lieu. Bien souvent, cette adresse équivaut à l'« adresse postale ». La propriété formatted_address est renvoyée uniquement pour une requête Text Search.
  • geometry : Fournit les informations liées aux propriétés géométriques du lieu. Notamment :
    • location fournit la latitude et la longitude du lieu.
    • viewport définit la fenêtre d'affichage préférée sur la carte pour l'affichage du lieu.
  • html_attributions : Tableau des mentions que vous devez afficher lors de l'affichage des 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 dans la réponse contiennent donc des listes de mentions identiques.
  • icon : URL d'une ressource d'image pouvant être utilisée pour représenter le type de ce lieu.
  • id : contient un identifiant unique correspondant à ce lieu. Cet identifiant peut ne pas être utilisé pour extraire des informations sur ce lieu, mais pour regrouper des données qui lui sont associées et en vérifier l'identité dans plusieurs recherches séparées. Dans la mesure où les identifiants sont susceptibles de changer, il est recommandé de comparer l'identifiant conservé pour un lieu à l'identifiant renvoyé dans les requêtes de détails ultérieures pour ce même lieu, et d'apporter les modifications nécessaires, le cas échéant. Remarque : La propriété id est progressivement abandonnée au profit de place_id, tel que décrit dans l'avis lié à l'abandon sur cette page.
  • name : Nom du lieu.
  • opening_hours peut contenir les informations suivantes :
    • open_now est une valeur booléenne qui indique si le lieu est ouvert actuellement.
  • place_id est un identifiant texte qui identifie un lieu de façon unique. Pour extraire des informations sur le lieu, indiquez cet identifiant dans le champ placeId d'une requête de détails sur un lieu. En savoir plus sur comment référencer un lieu avec un identifiant 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.
  • reference contient un jeton pouvant être utilisé pour interroger le service Details (recherche de détails) ultérieurement. Ce jeton peut différer de la référence utilisée dans la requête envoyée au service Details (recherche de détails). Il est recommandé de mettre à jour régulièrement les références stockées pour les lieux. Même si ce jeton identifie le lieu de manière unique, l'inverse n'est pas vrai. Un lieu peut être associé à plusieurs jetons de référence valides. Remarque : La propriété reference est progressivement abandonnée au profit de place_id, tel que décrit dans l'avis lié à l'abandon sur cette page.
  • types : Tableau de types pour ce lieu (par ex., ["political", "locality"] ou ["restaurant", "establishment"]).
  • 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, pour le bureau de Google à Sydney, Australie, la valeur vicinity est 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. Les pages supplémentaires sont disponibles via l'objet PlaceSearchPagination. Pour accéder à ces pages supplémentaires, vous devez capturer l'objet PlaceSearchPagination via une fonction de rappel. L'objet PlaceSearchPagination est défini comme suit :

  • hasNextPage – Propriété booléenne indiquant si d'autres résultats sont disponibles. Elle est définie sur true lorsqu'il existe des pages de résultats supplémentaires.
  • nextPage() – Fonction qui renvoie l'ensemble suivant de résultats. Après avoir exécuté une recherche, vous devez attendre deux secondes avant que la page suivante de résultats soit disponible.

Pour appeler l'ensemble suivant de résultats, appelez nextPage. Chaque page de résultats doit être affichée avant de pouvoir afficher la page suivante de résultats. 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 et ainsi pouvoir émettre plusieurs requêtes de recherche.

var map;

function initMap() {
  var pyrmont = {lat: -33.866, lng: 151.196};

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

  var service = new google.maps.places.PlacesService(map);
  service.nearbySearch({
    location: pyrmont,
    radius: 500,
    types: ['store']
  }, processResults);
}

function processResults(results, status, pagination) {
  if (status !== google.maps.places.PlacesServiceStatus.OK) {
    return;
  } else {
    createMarkers(results);

    if (pagination.hasNextPage) {
      var moreButton = document.getElementById('more');

      moreButton.disabled = false;

      moreButton.addEventListener('click', function() {
        moreButton.disabled = true;
        pagination.nextPage();
      });
    }
  }
}

function createMarkers(places) {
  var bounds = new google.maps.LatLngBounds();
  var placesList = document.getElementById('places');

  for (var i = 0, place; place = places[i]; i++) {
    var 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)
    };

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

    placesList.innerHTML += '<li>' + place.name + '</li>';

    bounds.extend(place.geometry.location);
  }
  map.fitBounds(bounds);
}

Voir l'exemple (place-search-pagination.html)

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. Une fois qu'un lieu a été fourni dans une réponse à une recherche de lieu, son identifiant de lieu peut être utilisé pour demander des détails supplémentaires sur ce lieu, tels que son adresse complète, son numéro de téléphone, les notes et avis des utilisateurs, etc. (La référence du lieu peut également servir à récupérer les détails d'un lieu, mais ce champ est progressivement abandonné au profit de l'identifiant de lieu, tel que décrit dans l'avis lié à l'abandon sur cette page.)

Requêtes Place Details

Les requêtes de détails de lieu sont effectuées en appelant la méthode getDetails() du service.

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

Cette méthode utilise une requête contenant la propriété placeId ou reference du lieu souhaité. La propriété reference est toutefois progressivement abandonnée au profit de placeId, tel que décrit dans l'avis lié à l'abandon sur cette page. En savoir plus sur comment référencer un lieu avec un identifiant de lieu.

Elle utilise également une méthode de rappel qui doit gérer le code de statut transmis dans la réponse google.maps.places.PlacesServiceStatus ainsi que l'objet google.maps.places.PlaceResult.

var request = {
  placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4'
};

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 l'exemple (place-details.html)

Réponses aux requêtes Place Details

Codes de statut

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

  • ERROR : Un problème est survenu lors de la communication avec les serveurs Google.
  • 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 : Le point géographique référencé n'a pas été trouvé 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() réussi renvoie un objet PlaceResult avec les propriétés suivantes :

  • address_components : Ensemble de composants d'adresse pour le lieu en question. Pour plus de détails, voir la section Types de composant d'adresse du service Geocoding.
  • formatted_address : Adresse complète du lieu.
  • formatted_phone_number : Numéro de téléphone du lieu, au format régional.
  • geometry : Fournit les informations liées aux propriétés géométriques du lieu. Notamment :
    • location fournit la latitude et la longitude du lieu.
    • viewport définit la fenêtre d'affichage préférée sur la carte pour l'affichage du lieu.
  • 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.
  • id : contient un identifiant unique correspondant à ce lieu. Cet identifiant peut ne pas être utilisé pour extraire des informations sur ce lieu, mais pour regrouper des données qui lui sont associées et en vérifier l'identité dans plusieurs recherches séparées. Dans la mesure où les identifiants sont susceptibles de changer, il est recommandé de comparer l'identifiant conservé pour un lieu à l'identifiant renvoyé dans les requêtes de détails ultérieures pour ce même lieu, et d'apporter les modifications nécessaires, le cas échéant. Remarque : La propriété id est progressivement abandonnée au profit de place_id, tel que décrit dans l'avis lié à l'abandon sur cette page.
  • 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 numéro international (international_phone_number) du bureau de Google à Sydney, Australie, est le +61 2 9374 4000.
  • name : Nom du lieu.
  • utc_offset contient le décalage en minutes du fuseau horaire de ce lieu par rapport à l'heure UTC. 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), et 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 est une valeur booléenne qui indique si le lieu est ouvert actuellement.
    • periods[] est un ensemble de périodes d'ouverture sur 7 jours à partir du dimanche, dans l'ordre chronologique. Chaque période contient les valeurs suivantes :
      • open contient une paire d'objets day et time décrivant le jour et l'heure d'ouverture du lieu :
        • day, un nombre compris entre 0 et 6 correspondant aux jours de la semaine, à partir du dimanche. Par exemple, 2 signifie Mardi.
        • time peut contenir une heure de la journée au format 24 heures hhmm (les valeurs se situent entre 0000 et 2359). Le paramètre time sera indiqué dans le fuseau horaire du lieu.
      • close peut contenir une paire d'objets day et time décrivant le jour et l'heure de fermeture du lieu. Remarque : Si un lieu est toujours ouvert, la section close sera absente de la réponse. Un lieu toujours ouvert est représenté par une période open contenant le paramètre day avec la valeur 0 et le paramètre time avec la valeur 0000, sans paramètre close.
    • weekday_text est un ensemble de 7 chaînes représentant les heures d'ouverture formatées pour chaque jour de la semaine. Si un paramètre language a été spécifié dans la requête de détails de lieu, le service Places formate et localise les heures d'ouverture en fonction de cette langue. L'ordre des éléments de ce 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 : indicateur booléen qui précise si le lieu a fermé définitivement (valeur true). Si le lieu n'a pas fermé définitivement, cet indicateur ne figure pas dans la réponse.
  • photos[] : tableau d'objets PlacePhoto. Un objet PlacePhoto peut être utilisé avec la méthode getUrl() pour obtenir une photo. Vous pouvez également vérifier la présence des valeurs suivantes dans l'objet :
    • 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 texte qui définit de manière unique un lieu et qui peut être utilisé pour extraire des informations sur ce lieu via une requête de détails de lieu. En savoir plus sur comment référencer un lieu avec un identifiant de lieu.
  • rating : Note du lieu, sur une échelle de 0.0 à 5.0, basée sur l'ensemble des avis des utilisateurs.
  • reference contient un jeton pouvant être utilisé pour interroger le service Details (recherche de détails) ultérieurement. Ce jeton peut différer de la référence utilisée dans la requête envoyée au service Details (recherche de détails). Il est recommandé de mettre à jour régulièrement les références stockées pour les lieux. Même si ce jeton identifie le lieu de manière unique, l'inverse n'est pas vrai. Un lieu peut être associé à plusieurs jetons de référence valides. Remarque : La propriété reference est progressivement abandonnée au profit de place_id, tel que décrit dans l'avis lié à l'abandon sur cette page.
  • reviews désigne un tableau de cinq évaluations maximum. Chaque évaluation contient plusieurs composants :
    • aspects[] contient un tableau d'objets PlaceAspectRating, chacun fournissant une note pour un attribut unique de l'établissement. Le premier objet du tableau est considéré comme l'aspect principal. Chaque objet PlaceAspectRating est défini comme suit :
      • type, le nom de l'aspect évalué. Les types suivants sont pris en charge : appeal (attrait), atmosphere (ambiance), decor (décor), facilities (commodités), food (nourriture), overall (général), quality (qualité) et service.
      • rating, la note de l'utilisateur pour cet aspect spécifique, sur une échelle de 0 à 3.
    • author_name, le nom de l'utilisateur qui a soumis l'évaluation. Les évaluations anonymes sont associées à l'indication « A Google user » (Utilisateur Google). Si un paramètre de langue a été défini, l'indication « A Google user » renvoie une chaîne localisée.
    • author_url, l'URL du profil Google+ de l'utilisateur, si disponible.
    • language, un code langue IETF indiquant la langue utilisée dans l'évaluation de l'utilisateur. Ce champ contient uniquement l'indicateur principal de la langue et non l'indicateur 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 de l'utilisateur pour ce lieu. Il s'agit d'un nombre entier compris entre 1 et 5.
    • text, l'évaluation de l'utilisateur. Lors de la consultation d'un lieu avec Google Places, les évaluations texte sont considérées comme facultatives. Ce champ peut donc être vide.
  • types : Tableau de types pour ce lieu (par ex., ["political", "locality"] ou ["restaurant", "establishment"]).
  • 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, pour le bureau de Google à Sydney, Australie, la valeur vicinity est 5/48 Pirrama Road, Pyrmont. La propriété vicinity est renvoyée uniquement pour une requête Nearby Search.
  • website contient l'adresse du site Web officiel de ce lieu, telle que la page d'accueil d'une entreprise.

Les notes multidimensionnelles peuvent ne pas être disponibles pour tous les lieux. Si le nombre d'évaluations est trop peu élevé, 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 identifiant de lieu

Sur une carte Google, il se peut que les lieux ne soient référencés qu'avec leur identifiant de lieu. De tels identifiants sont disponibles pour la plupart des points géographiques, y compris les entreprises, points de repère, parcs et intersections. Ces identifiants sont fixes, c'est-à-dire qu'une fois l'identifiant de lieu déterminé pour un point géographique, vous pouvez réutiliser cette valeur lorsque vous recherchez ce point géographique.

Pour utiliser un identifiant de lieu dans votre application, vous devez d'abord rechercher cet identifiant, disponible dans l'objet PlaceResult d'une requête Place Search or Place Details. Vous pouvez ensuite utiliser cet identifiant de lieu pour rechercher les détails d'un lieu ou permettre l'enregistrement des mentions dans une carte avec connexion.

Les identifiants de lieu ne sont pas concernés par les restrictions de mise en cache stipulées dans la Section 10.5.d des Conditions de service de Google Maps API. Vous pouvez par conséquent stocker les identifiants de lieu indéfiniment.

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

Place Photos

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 détails de lieu, 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. À l'aide du service Photo, vous pouvez ensuite accéder aux photos référencées et redimensionner l'image pour qu'elle s'adapte parfaitement à votre application.

Un tableau d'objets PlacePhoto est renvoyé avec l'objet PlaceResult pour toute requête getDetails(), textSearch() ou nearbySearch() effectuée auprès du service PlacesService.

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

  • Une requête Nearby Search ou Text Search renvoie au maximum un objet PlacePhoto.
  • Les requêtes Radar Search ne renvoient aucune photo.
  • Une requête Details renvoie jusqu'à 10 objets PlacePhoto.

Vous pouvez faire une requête d'URL pour 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 à la fois le paramètre max_height et le paramètre max_width, le service Photo redimensionne l'image à la plus petite des deux, tout en conservant le rapport hauteur-largeur d'origine.

Le fragment de code suivant accepte un objet de lieu et ajoute un marqueur sur la carte si une photo est disponible. L'image du marqueur 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})
  });
}

Envoyer des commentaires concernant…

Google Maps JavaScript API
Google Maps JavaScript API
Besoin d'aide ? Consultez notre page d'assistance.