Place Details

Le SDK Places pour Android fournit à votre application des informations détaillées sur des lieux, y compris leur nom et leur adresse, la position géographique spécifiée 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'ID 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:

• Appelez PlacesClient.findCurrentPlace() : consultez le guide pour obtenir le lieu actuel.
• Appelez PlacesClient.fetchPlace() : consultez le guide pour obtenir une adresse par ID.

Lorsque vous demandez un lieu, vous devez spécifier les données de lieu à renvoyer. Pour ce faire, transmettez une liste de valeurs Place.Field spécifiant les données à renvoyer. Cette liste est importante, car elle affecte 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 contenant 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).

L'exemple suivant transmet une liste de trois valeurs Place.Field permettant de spécifier les données renvoyées par une requête:

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

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

Après avoir obtenu l'objet Place, utilisez ses méthodes pour extraire les données de lieu. Voici quelques exemples de méthodes disponibles : Pour obtenir la liste complète de toutes les méthodes, consultez la documentation de référence de l'API Place.

• getAddress() : adresse du lieu, dans un format lisible.
• getAddressComponents() : List des 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 dans laquelle se trouve un lieu. N'utilisez pas ces composants pour le formatage d'adresse. Appelez plutôt getAddress(), qui fournit une adresse formatée localisée.
• 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é en tant que coordonnées de latitude et de longitude.
• getName() : nom du lieu.
• getOpeningHours() : OpeningHours du lieu. Appelez OpeningHours.getWeekdayText() pour renvoyer 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 dimanche à minuit et la valeur de closeEvent est nulle.
• 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 maintenant. isOpen ne sera renvoyé que si Place.Field.UTC_OFFSET et Place.Field.OPENING_HOURS sont disponibles. Pour garantir l'exactitude des résultats, 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 :

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

      

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

      

Obtenir un lieu par identifiant

Un ID 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 pour chaque lieu correspondant à la requête et au filtre fournis. Vous pouvez stocker l'ID de lieu et l'utiliser pour récupérer l'objet Place ultérieurement.

Pour obtenir une adresse par identifiant, appelez PlacesClient.fetchPlace() et transmettez FetchPlaceRequest.

L'API renvoie un FetchPlaceResponse dans un Task. 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é.

// 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.
    }
});

      

// 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 un lieu, elle doit également afficher les mentions. Consultez la documentation sur les attributions.

Informations supplémentaires sur les identifiants de lieu

L'ID de lieu utilisé dans le SDK Places pour Android est le même que celui utilisé dans 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. Dans d'autres cas, un lieu peut obtenir 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 êtes certain de toujours recevoir le même lieu dans la 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.