Current Place

Avec le SDK Places pour Android, vous pouvez découvrir le lieu identifié par l'appareil via la géolocalisation. Il peut s'agir, par exemple, d'établissements locaux, de points d'intérêt et d'emplacements géographiques.

Remarque : Pour suivre un tutoriel guidé et pratique, consultez le tutoriel sur le lieu actuel.

Autorisations

Pour utiliser la bibliothèque, vous n'avez pas besoin de déclarer d'autorisations supplémentaires dans le fichier manifeste de votre application, car la bibliothèque déclare toutes les autorisations qu'elle utilise dans son propre 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 ce qui suit à 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>

En savoir plus sur les autorisations et envisager d'utiliser EasyPermissions pour commencer

Obtenir le point géographique actuel

Pour trouver l'établissement local ou l'autre lieu où se trouve actuellement l'appareil, procédez comme suit:

1. Appelez ContextCompat.checkSelfPermission pour vérifier si l'utilisateur a accordé l'autorisation d'accéder à la position de son appareil. Votre application doit également inclure du code pour demander à l'utilisateur une autorisation et pour gérer le résultat. Pour en savoir plus, consultez la section Demander des autorisations d'application.
2. Créez un FindCurrentPlaceRequest, en transmettant un List d'Place.Field, en spécifiant les types de données de lieu que votre application doit demander.
3. Appelez PlacesClient.findCurrentPlace() en transmettant le FindCurrentPlaceRequest que vous avez créé à l'étape précédente.
4. Obtenez la liste des PlaceLikelihood à partir de FindCurrentPlaceResponse.

Remarque:Bien que PlacesClient.fetchPlace() accepte tous les détails d'un lieu, PlacesClient.findCurrentPlace() n'en accepte qu'un sous-ensemble. Pour obtenir la liste des champs NON compatibles avec findCurrentPlace(), consultez la section Compatibilité des champs du SDK Places pour Android.

Les champs correspondent aux résultats de Place Search et sont divisés en trois catégories de facturation : Basic, Contact et Atmosphere. Les champs Basic sont facturés au tarif de base et n'entraînent aucuns frais supplémentaires. Les champs Contact et Atmosphere sont facturés à un tarif plus élevé. Pour en savoir plus sur la facturation des requêtes de données de lieu, consultez 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 d'être situé. Pour chaque lieu, le résultat indique la probabilité que le lieu soit le bon. La liste peut être vide si aucun lieu connu ne correspond à la position de l'appareil donnée.

Vous pouvez appeler PlaceLikelihood.getPlace() pour récupérer un objet Place et PlaceLikelihood.getLikelihood() pour obtenir la probabilité de l'établissement. Plus la valeur est élevée, plus la probabilité que l'établissement soit la meilleure correspondance est élevée.

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.

KotlinJava

// 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()
}

      

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

      

Remarques à propos des valeurs de probabilité :

• La probabilité indique la probabilité relative que le lieu soit la meilleure correspondance dans la liste des lieux renvoyés pour une seule requête. Vous ne pouvez pas comparer les probabilités entre différentes requêtes.
• La valeur de la probabilité est comprise entre 0,0 et 1,0.

Par exemple, pour représenter une probabilité de 55% que le lieu correct soit le lieu A et une probabilité de 35% qu'il s'agisse du lieu B, la réponse comporte deux membres, le lieu A avec une probabilité de 0,55 et le lieu B avec une probabilité de 0,35.

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

Vous pouvez utiliser un CancellationToken pour tenter d'annuler une demande à l'une des classes de requêtes (par exemple, FetchPlaceRequest). L'annulation est effectuée de la manière la plus optimale possible. Une fois la demande d'annulation envoyée, 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.

Afficher les mentions dans votre application

Lorsque votre application affiche des informations obtenues à partir de PlacesClient.findCurrentPlace(), elle doit également afficher des attributions. Consultez la documentation sur les attributions.