Place Details

Développeurs de l'Espace économique européen (EEE)

Si votre adresse de facturation se trouve dans l'Espace économique européen, les Conditions d'utilisation de Google Maps Platform pour l'EEE s'appliqueront à votre utilisation des Services à compter du 8 juillet 2025. La fonctionnalité varie selon la région. En savoir plus

Le Places SDK for Android fournit à votre application des informations détaillées sur les lieux, y compris leur nom et leur adresse, leur emplacement géographique spécifié sous forme de coordonnées de latitude/longitude, leur type (par exemple, boîte de nuit, animalerie, musée) et plus encore. 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 en appelant PlacesClient.fetchPlace(). Consultez le guide sur l'obtention d'un lieu 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 a une incidence sur le coût de chaque requête.

Étant donné que les données de lieu ne peuvent pas être vides, seuls les résultats contenant des données sont renvoyés. Par exemple, s'il n'existe pas de photos du lieu demandé, le résultat ne contiendra pas de champ photos.

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

Kotlin

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

Java

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

Accéder aux champs de données de l'objet Place

Une fois l'objet Place obtenu, utilisez ses méthodes pour accéder aux champs de données spécifiés dans la requête. Si le champ est manquant dans l'objet Place, la méthode associée renvoie la valeur "null". Vous trouverez ci-dessous des exemples de certaines des 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 de composants d'adresse pour 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 il se trouve. N'utilisez pas ces composants pour mettre en forme les adresses. 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é sous forme de 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 horaires d'ouverture et de fermeture pour chaque jour de la semaine. Appelez OpeningHours.getPeriods() pour renvoyer une liste d'objets period contenant 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 closeEvent est nul.

  L'objet Place contient également les méthodes getCurrentOpeningHours(), qui renvoie les heures d'ouverture d'un lieu pour les sept prochains jours, et getSecondaryOpeningHours(), qui renvoie les heures d'ouverture secondaires d'un lieu pour les sept prochains jours.

• isOpen() : valeur booléenne indiquant si le lieu est actuellement ouvert. Si aucune heure n'est spécifiée, la valeur par défaut est l'heure actuelle. isOpen ne sera renvoyé que si Place.Field.UTC_OFFSET et Place.Field.OPENING_HOURS sont disponibles. Pour obtenir des résultats précis, demandez les champs Place.Field.BUSINESS_STATUS et Place.Field.UTC_OFFSET dans votre demande de lieu d'origine. Si aucune demande n'est envoyée, nous supposons que l'établissement est opérationnel. Regardez cette vidéo pour découvrir comment utiliser isOpen avec Place Details.

  Remarque  : Cette méthode est obsolète. Utilisez plutôt PlacesClient.isOpen(IsOpenRequest request). Pour en savoir plus, consultez Obtenir l'état ouvert.

Voici quelques exemples :

Kotlin

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

      

Java

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

      

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 de recherche 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 un lieu par ID, appelez PlacesClient.fetchPlace() en transmettant un FetchPlaceRequest.

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

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

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")
        }
    }

      

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

      

Remarque : Pour en savoir plus sur l'initialisation de PlacesClient, consultez Initialiser le client de l'API Places.

Vous pouvez utiliser un CancellationToken pour tenter d'annuler une requête à l'une des classes de requête (par exemple, FetchPlaceRequest). L'annulation est effectuée au mieux. Une fois la demande d'annulation émise, aucune réponse ne sera renvoyée. L'émission d'un jeton d'annulation ne garantit PAS qu'une requête particulière sera annulée. Vous pouvez toujours être facturé pour la requête, même si aucune réponse n'est renvoyée.

Obtenir l'état d'ouverture

La méthode PlacesClient.isOpen(IsOpenRequest request) renvoie un objet IsOpenResponse indiquant si le lieu est actuellement ouvert en fonction de l'heure spécifiée dans l'appel.

Cette méthode utilise un seul argument de type IsOpenRequest qui contient :

• Objet Place ou chaîne spécifiant un ID de lieu.
  Remarque  : L'objet Place doit contenir un ID de lieu valide.
• Valeur temporelle facultative spécifiant l'heure en millisecondes depuis 1970-01-01T00:00:00Z. Si aucune heure n'est spécifiée, la valeur par défaut est l'heure actuelle.

Cette méthode exige que les champs suivants existent dans l'objet Place :

• Place.Field.BUSINESS_STATUS
• Place.Field.CURRENT_OPENING_HOURS
• Place.Field.OPENING_HOURS
• Place.Field.UTC_OFFSET

Si ces champs ne sont pas fournis dans l'objet Place ou si vous transmettez un ID de lieu, la méthode utilise PlacesClient.fetchPlace() pour les récupérer. Pour en savoir plus sur la création de l'objet Place avec les champs nécessaires, consultez Détails du lieu.

Remarque  : Le SKU Places Basic Data est facturé pour les appels à fetchPlace() pour Place.Field.UTC_OFFSET et Place.Field.BUSINESS_STATUS. Le SKU Places Data Contact est facturé pour les appels à fetchPlace() pour Place.Field.CURRENT_OPENING_HOURS et Place.Field.OPENING_HOURS.

L'exemple suivant détermine si un lieu est actuellement ouvert. Dans cet exemple, vous ne transmettez que l'ID du lieu à isOpen() :

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    e.printStackTrace()
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    e.printStackTrace();
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) ->
                isOpen = response.isOpen());
// ...

      

L'exemple suivant montre comment appeler isOpen() en transmettant un objet Place. L'objet Place doit contenir un ID de lieu valide :

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"
// Specify the required fields for an isOpen request.
val placeFields: List<Place.Field> = listOf(
    Place.Field.BUSINESS_STATUS,
    Place.Field.CURRENT_OPENING_HOURS,
    Place.Field.ID,
    Place.Field.OPENING_HOURS,
    Place.Field.UTC_OFFSET
)

val placeRequest: FetchPlaceRequest =
    FetchPlaceRequest.newInstance(placeId, placeFields)
val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest)
placeTask.addOnSuccessListener { placeResponse ->
    place = placeResponse.place

    val isOpenRequest: IsOpenRequest = try {
        IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis)
    } catch (e: IllegalArgumentException) {
        e.printStackTrace()
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = isOpenResponse.isOpen
    }
    // ...
}
// ...

      

Java

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
// Specify the required fields for an isOpen request.
List<Place.Field> placeFields = new ArrayList<>(Arrays.asList(
        Place.Field.BUSINESS_STATUS,
        Place.Field.CURRENT_OPENING_HOURS,
        Place.Field.ID,
        Place.Field.OPENING_HOURS,
        Place.Field.UTC_OFFSET
));

FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

placeTask.addOnSuccessListener(
        (placeResponse) -> {
            Place place = placeResponse.getPlace();
            IsOpenRequest isOpenRequest;

            try {
                isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis());
            } catch (IllegalArgumentException e) {
                e.printStackTrace();
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> isOpen = isOpenResponse.isOpen());
            // ...
        });
// ...

      

Afficher les mentions dans votre application

Lorsque votre application affiche des informations sur un lieu, y compris des avis, elle doit également afficher les attributions. Pour en savoir plus, consultez Attributions.

Informations supplémentaires sur les identifiants de lieu

L'ID de lieu utilisé dans le SDK Places pour Android est le même identifiant que celui utilisé dans l'API Places. Chaque identifiant de lieu ne peut faire référence qu'à un seul lieu, mais un même lieu peut avoir plusieurs identifiants. Il existe d'autres circonstances qui peuvent entraîner l'attribution d'un nouvel ID de lieu. Par exemple, cela peut se produire si un établissement déménage.

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

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