Place Details

Sélectionnez une plate-forme: Android iOS JavaScript Service Web

Le SDK Places pour Android fournit à votre application des informations détaillées sur les lieux, y compris leur nom et leur adresse, l'emplacement géographique spécifié en tant que coordonnées de latitude/longitude, le type de lieu (par exemple, discothèque, animalerie, musée), etc. Pour accéder à ces informations pour un lieu spécifique, vous pouvez utiliser l'identifiant de lieu, un identifiant stable qui identifie un lieu de manière unique.

Détails sur le lieu

L'objet Place fournit des informations sur un lieu spécifique. Vous pouvez obtenir un objet Place de différentes manières:

Lorsque vous demandez un lieu, vous devez spécifier les types de données de lieu à renvoyer. Pour ce faire, transmettez List<Place.Field> en spécifiant les types de données à renvoyer. Il s'agit d'un élément important, car il aura une incidence sur le coût de chaque requête. Étant donné que les résultats de données de lieu ne peuvent pas être vides, seuls les résultats de lieu avec des données sont renvoyés (par exemple, si un lieu demandé n'a pas de photos, le champ photos ne sera pas présent dans le résultat). Vous pouvez spécifier un ou plusieurs des champs suivants:

  • Place.Field.ADDRESS
  • Place.Field.ADDRESS_COMPONENTS
  • Place.Field.BUSINESS_STATUS
  • Place.Field.ID
  • Place.Field.LAT_LNG
  • Place.Field.NAME
  • Place.Field.OPENING_HOURS
  • Place.Field.PHONE_NUMBER
  • Place.Field.PHOTO_METADATAS
  • Place.Field.PLUS_CODE
  • Place.Field.PRICE_LEVEL
  • Place.Field.RATING
  • Place.Field.TYPES
  • Place.Field.USER_RATINGS_TOTAL
  • Place.Field.ICON_URL
  • Place.Field.ICON_BACKGROUND_COLOR
  • Place.Field.VIEWPORT
  • Place.Field.UTC_OFFSET
  • Place.Field.WEBSITE_URI

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.

Utilisez les méthodes suivantes pour récupérer des données à partir d'un Place:

  • getAddress() : adresse du lieu dans un format lisible.
  • getAddressComponents() : List de composants d'adresse de ce lieu. Ces composants sont fournis dans le but d'extraire des informations structurées sur l'adresse d'un lieu, par exemple pour trouver la ville où se trouve un lieu. N'utilisez pas ces composants pour le formatage d'adresse. Appelez plutôt getAddress(), qui fournit une adresse au format localisé.
  • getBusinessStatus() : état d'exploitation du lieu (s'il s'agit d'un établissement). Il peut contenir l'une des valeurs suivantes: OPERATIONAL, CLOSED_TEMPORARILY, CLOSED PERMANENTLY.
  • getAttributions() : attributions à présenter à l'utilisateur si les données du lieu sont utilisées.
  • getID() : identifiant textuel du lieu. Pour en savoir plus sur les ID de lieu, consultez le reste de cette page.
  • getLatLng() : emplacement géographique du lieu, spécifié sous la forme de coordonnées de latitude et de longitude.
  • getName() : nom du lieu.
  • getOpeningHours() : OpeningHours du lieu. Appelez OpeningHours.getWeekdayText() pour obtenir une liste de chaînes représentant les heures d'ouverture et de fermeture pour chaque jour de la semaine. Appelez OpeningHours.getPeriods() pour renvoyer une liste d'objets period avec des informations plus détaillées, équivalentes aux données fournies par getWeekdayText(). Remarque : Si un lieu est toujours ouvert, la période est représentée par le dimanche à minuit et la valeur closeEvent est nulle.
  • getPhoneNumber() : numéro de téléphone du lieu.
  • getPhotoMetadatas() : métadonnées associées à une photo associée au lieu, y compris l'image bitmap.
  • getPlusCode() : position PlusCode de ce lieu.
  • getPriceLevel() : niveau de tarification du lieu, affiché sous forme de nombre entier avec des valeurs comprises entre 0 (le moins cher) et 4 (le plus cher).
  • getRating() : note globale du lieu, renvoyée sous la forme d'une valeur flottante comprise entre 1 et 5, basée sur l'ensemble des avis des utilisateurs.
  • getTypes() : liste des types de lieu qui caractérisent ce lieu. Pour obtenir la liste des types de lieux disponibles, consultez la documentation de l'interface Place.
  • getUserRatingsTotal() : nombre total de notes de ce lieu.
  • getIconUrl() : URL d'un masque d'icône noire représentant le type de lieu.
  • getIconBackgroundColor : couleur d'arrière-plan de l'icône pour le type de lieu.
  • getUtcOffsetMinutes() : décalage UTC, en minutes.
  • getViewport() : fenêtre d'affichage, renvoyée en tant qu'objet LatLngBounds, utile pour afficher le lieu sur une carte. Peut renvoyer la valeur "null" si la taille du lieu est inconnue.
  • getWebsiteUri() : URI du site Web du lieu, s'il est connu. Site Web géré par l'établissement ou par une autre entité associée à ce lieu. Renvoie la valeur null si aucun site Web n'est connu.
  • isOpen() : valeur booléenne indiquant si l'établissement est actuellement ouvert Si aucune heure n'est spécifiée, la valeur par défaut est désormais. isOpen ne sera renvoyé que si Place.Field.UTC_OFFSET et Place.Field.OPENING_HOURS sont disponibles. Pour garantir des résultats précis, demandez les champs Place.Field.BUSINESS_STATUS et Place.Field.UTC_OFFSET dans votre requête de lieu d'origine. Dans le cas contraire, nous partons du principe que l'établissement est opérationnel. Regardez cette vidéo pour découvrir comment utiliser isOpen avec Place Details.

Voici quelques exemples simples :

Java


final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

Kotlin


val name = place.name
val address = place.address
val location = place.latLng

      

Obtenir un lieu par identifiant

Un identifiant de lieu est un identifiant texte qui identifie un lieu de façon unique. Dans le SDK Places pour Android, vous pouvez récupérer l'ID d'un lieu en appelant Place.getId(). Le service Place Autocomplete renvoie également un ID de lieu correspondant à la requête et au filtre fournis. Vous pouvez stocker l'ID de lieu et l'utiliser pour récupérer à nouveau l'objet Place.

Pour obtenir un lieu par ID, appelez PlacesClient.fetchPlace(), en indiquant un FetchPlaceRequest.

L'API renvoie un FetchPlaceResponse dans un Task. L'élément FetchPlaceResponse contient un objet Place correspondant à l'ID de lieu fourni.

L'exemple de code suivant montre comment appeler fetchPlace() pour obtenir des détails sur le lieu spécifié.

Java


// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient.fetchPlace(request).addOnSuccessListener((response) -> {
    Place place = response.getPlace();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

Kotlin


// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

// Specify the fields to return.
val placeFields = listOf(Place.Field.ID, Place.Field.NAME)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

Afficher les mentions dans votre application

Lorsque votre application affiche des informations sur le lieu, elle doit également afficher les attributions. Consultez la documentation sur les attributions.

Informations supplémentaires sur les identifiants de lieu

L'identifiant de lieu utilisé dans le SDK Places pour Android est le même que pour l'API Places. Chaque ID de lieu ne peut faire référence qu'à un seul lieu, mais un même lieu peut avoir plusieurs ID de lieu. D'autres circonstances peuvent expliquer qu'un lieu obtienne un nouvel ID de lieu. Cela peut se produire, par exemple, si un établissement déménage.

Lorsque vous demandez un lieu en spécifiant un ID de lieu, vous pouvez être certain de toujours recevoir le même lieu en réponse (s'il existe toujours). Notez toutefois que la réponse peut contenir un ID de lieu différent de celui de votre requête.

Pour en savoir plus, consultez la présentation des ID de lieu.