Le SDK Places pour 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é en tant que coordonnées de latitude/longitude, le type de lieu (boîte de nuit, boutique pour animaux, 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:
- Appelez
PlacesClient.fetchPlace()
: consultez le guide pour obtenir un lieu à l'aide de son identifiant. - Appelez
PlacesClient.findCurrentPlace()
: consultez le guide pour obtenir le lieu actuel.
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 un élément important à prendre en compte, 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 contenant des données de lieu sont renvoyés (par exemple, si un lieu demandé ne comporte aucune photo, le champ photos
ne s'affichera pas).
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.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Java
// Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Accéder aux champs de données des objets Place
Après avoir obtenu l'objet Place
, utilisez ses méthodes pour accéder aux champs de données spécifiés dans la requête. Si le champ ne figure pas dans l'objet Place
, la méthode associée renvoie la valeur "null". Vous trouverez ci-dessous 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, au 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 se trouve un lieu. N'utilisez pas ces composants pour le formatage des adresses. Appelez plutôtgetAddress()
, qui fournit une adresse formatée localisée.getId()
: identifiant textuel du lieu. Pour en savoir plus sur les ID de lieu, consultez la suite 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. AppelezOpeningHours.getWeekdayText()
pour renvoyer une liste de chaînes représentant les heures d'ouverture et de fermeture pour chaque jour de la semaine. AppelezOpeningHours.getPeriods()
pour renvoyer une liste d'objetsperiod
avec des informations plus détaillées équivalentes aux données fournies pargetWeekdayText()
.L'objet
Place
contient également la méthodegetCurrentOpeningHours()
, qui renvoie les heures d'ouverture d'un lieu au cours des sept prochains jours, etgetSecondaryOpeningHours()
, qui renvoie les heures d'ouverture secondaires d'un lieu au cours des sept prochains jours.isOpen()
: booléen indiquant si l'établissement est actuellement ouvert. Si aucune heure n'est spécifiée, la valeur par défaut est "now".isOpen
ne sera renvoyé que siPlace.Field.UTC_OFFSET
etPlace.Field.OPENING_HOURS
sont disponibles. Pour garantir des résultats précis, demandez les champsPlace.Field.BUSINESS_STATUS
etPlace.Field.UTC_OFFSET
dans votre requête de lieu d'origine. S'il n'est pas demandé, nous partons du principe que l'entreprise est opérationnelle. Regardez cette vidéo pour découvrir comment utiliserisOpen
avec Place Details.
Voici quelques exemples simples :
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 son ID, appelez PlacesClient.fetchPlace()
en transmettant un FetchPlaceRequest
.
L'API renvoie un FetchPlaceResponse
dans un Task
.
Le 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é.
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. } });
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 accepte un seul argument de type IsOpenRequest
, qui contient les éléments suivants:
- Un objet
Place
ou une chaîne spécifiant un ID de lieu. - Valeur de temps facultative spécifiant le temps en millisecondes depuis 1970-01-01T00:00:00Z. Si aucune heure n'est spécifiée, la valeur par défaut est "now".
Cette méthode nécessite 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 les récupère à l'aide de PlacesClient.fetchPlace()
. Pour en savoir plus sur la création de l'objet Place avec les champs nécessaires, consultez Informations sur le lieu.
L'exemple suivant détermine si un lieu est actuellement ouvert. Dans cet exemple, vous transmettez uniquement l'ID de 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()
, où vous transmettez 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 sur les lieux, elle doit également afficher les mentions. Pour en savoir plus, consultez la section 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 celui utilisé dans l'API Places. Chaque identifiant de lieu ne peut faire référence qu'à un seul et même lieu. En revanche, un même lieu peut avoir plusieurs identifiants. Un lieu peut obtenir un nouvel ID de lieu dans d'autres circonstances. Cela peut se produire si une entreprise déménage, par exemple.
Lorsque vous demandez un lieu en spécifiant un ID de lieu, vous êtes sûr de recevoir toujours 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.