Le SDK Places pour Android vous permet de découvrir ce lieu à l'emplacement indiqué par l'appareil. Il peut s'agir d'établissements locaux, de points d'intérêt et de zones géographiques.
Autorisations
Pour utiliser la bibliothèque, vous n'avez pas besoin de déclarer d'autorisations supplémentaires dans le fichier manifeste de votre appli, car elle déclare toutes les autorisations qu'elle utilise dans son fichier manifeste. Toutefois, si votre application utilise PlacesClient.findCurrentPlace()
, vous devez demander des autorisations d'accéder à la position au moment de l'exécution.
Si votre application n'utilise pas PlacesClient.findCurrentPlace()
, supprimez explicitement les autorisations ACCESS_FINE_LOCATION
et ACCESS_COARSE_LOCATION
introduites par la bibliothèque en ajoutant les éléments suivants à votre fichier manifeste :
<manifest ... xmlns:tools="http://schemas.android.com/tools"> ... <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/> <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove"/> ... </manifest>
Obtenez plus d'informations sur les autorisations et envisagez d'utiliser EasyPermissions pour commencer.
Obtenir le point géographique actuel
Pour trouver l'établissement local ou un autre lieu où se trouve actuellement l'appareil, procédez comme suit:
- Appelez
ContextCompat.checkSelfPermission
pour vérifier si l'utilisateur a autorisé l'accès à la position de son appareil. Votre application doit également inclure du code pour demander l'autorisation à l'utilisateur et pour gérer le résultat. Pour en savoir plus, consultez Demander des autorisations pour une application. - Créez un
FindCurrentPlaceRequest
, en transmettant unList
dePlace.Field
, en spécifiant les types de données de lieu que votre application doit demander. - Appelez
PlacesClient.findCurrentPlace()
en transmettant l'identifiantFindCurrentPlaceRequest
que vous avez créé à l'étape précédente. - Obtenez la liste des
PlaceLikelihood
à partir deFindCurrentPlaceResponse
.
Les champs correspondent aux résultats Place Search et sont divisés en trois catégories de facturation : Basic, Contact et Ambiance. Les champs Basic sont facturés au tarif de base et n'entraînent aucuns frais supplémentaires. Les champs Contact et Ambiance sont facturés à un tarif plus élevé. Pour en savoir plus sur la facturation des requêtes de données de lieu, consultez la page Utilisation et facturation.
L'API renvoie un FindCurrentPlaceResponse
dans un Task
.
FindCurrentPlaceResponse
contient une liste d'objets PlaceLikelihood
représentant les lieux où l'appareil est susceptible de se trouver. Pour chaque lieu, le résultat indique la probabilité que le lieu soit correct. La liste peut être vide si aucun lieu connu ne correspond à la position de l'appareil donné.
Vous pouvez appeler PlaceLikelihood.getPlace()
pour récupérer un objet Place
et PlaceLikelihood.getLikelihood()
pour obtenir la note de probabilité du lieu. Plus la valeur est élevée, plus il y a de chances que le lieu soit le meilleur.
L'exemple de code suivant récupère la liste des lieux où l'appareil est le plus susceptible de se trouver, et consigne le nom et la probabilité de chaque lieu.
Java
// Use fields to define the data types to return. List<Place.Field> placeFields = Collections.singletonList(Place.Field.NAME); // Use the builder to create a FindCurrentPlaceRequest. FindCurrentPlaceRequest request = FindCurrentPlaceRequest.newInstance(placeFields); // Call findCurrentPlace and handle the response (first check that the user has granted permission). if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) { Task<FindCurrentPlaceResponse> placeResponse = placesClient.findCurrentPlace(request); placeResponse.addOnCompleteListener(task -> { if (task.isSuccessful()){ FindCurrentPlaceResponse response = task.getResult(); for (PlaceLikelihood placeLikelihood : response.getPlaceLikelihoods()) { Log.i(TAG, String.format("Place '%s' has likelihood: %f", placeLikelihood.getPlace().getName(), placeLikelihood.getLikelihood())); } } else { Exception exception = task.getException(); if (exception instanceof ApiException) { ApiException apiException = (ApiException) exception; Log.e(TAG, "Place not found: " + apiException.getStatusCode()); } } }); } else { // A local method to request required permissions; // See https://developer.android.com/training/permissions/requesting getLocationPermission(); }
Kotlin
// Use fields to define the data types to return. val placeFields: List<Place.Field> = listOf(Place.Field.NAME) // Use the builder to create a FindCurrentPlaceRequest. val request: FindCurrentPlaceRequest = FindCurrentPlaceRequest.newInstance(placeFields) // Call findCurrentPlace and handle the response (first check that the user has granted permission). if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) { val placeResponse = placesClient.findCurrentPlace(request) placeResponse.addOnCompleteListener { task -> if (task.isSuccessful) { val response = task.result for (placeLikelihood: PlaceLikelihood in response?.placeLikelihoods ?: emptyList()) { Log.i( TAG, "Place '${placeLikelihood.place.name}' has likelihood: ${placeLikelihood.likelihood}" ) } } else { val exception = task.exception if (exception is ApiException) { Log.e(TAG, "Place not found: ${exception.statusCode}") } } } } else { // A local method to request required permissions; // See https://developer.android.com/training/permissions/requesting getLocationPermission() }
Remarques à propos des valeurs de probabilité :
- La probabilité fournit une probabilité relative que le lieu soit le meilleur résultat dans la liste des lieux renvoyés pour une seule requête. Vous ne pouvez pas comparer les probabilités pour différentes requêtes.
- La valeur de probabilité est comprise entre 0,0 et 1,0.
Par exemple, pour représenter une probabilité de 55% que le bon endroit soit le lieu A et la probabilité de 35% qu'il s'agisse du lieu B, la réponse contient deux membres : le lieu A avec une probabilité de 0, 55 et le lieu B avec une probabilité de 0,35.
Afficher les mentions dans votre application
Lorsque votre application affiche des informations obtenues via PlacesClient.findCurrentPlace()
, elle doit également afficher les mentions. Consultez la documentation sur les attributions.