Current Place (ancienne version)

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

Le SDK Places pour Android vous permet de découvrir le lieu correspondant à la position actuelle de l'appareil. Les lieux peuvent être des établissements locaux, des points d'intérêt et des emplacements 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 application, car la bibliothèque 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 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>

Pour en savoir plus, consultez la section 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 :

  1. 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 gérer le résultat. Pour en savoir plus, consultez Demander des autorisations d'application.
  2. Créez un FindCurrentPlaceRequest en transmettant une List de 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.

Les champs correspondent aux résultats 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 de se trouver. Pour chaque lieu, le résultat inclut une indication de la probabilité que le lieu soit le bon. La liste peut être vide s'il n'existe aucun lieu connu correspondant à la position de l'appareil.

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

L'exemple de code suivant récupère la liste des lieux où l'appareil est le plus susceptible de se trouver, puis consigne le nom et la probabilité de chaque lieu.

Kotlin

// Use fields to define the data types to return.
val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS, Place.Field.LOCATION)

// Define the search area around the current location (500m radius).
val currentLocation = LatLng(37.4220, -122.0841)
val circle = CircularBounds.newInstance(currentLocation, 500.0)
val request = SearchNearbyRequest.builder(circle, placeFields)
    .setMaxResultCount(20)
    .build()

// Call searchNearby and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) ==
    PackageManager.PERMISSION_GRANTED
) {
    placesClient.searchNearby(request).addOnSuccessListener { response ->
        binding.progressBar.visibility = View.GONE
        adapter.setPlaces(response.places)
    }.addOnFailureListener { exception ->
        binding.progressBar.visibility = View.GONE
        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()
}

Java

// Use fields to define the data types to return.
List<Place.Field> placeFields =
        Arrays.asList(
                Place.Field.DISPLAY_NAME,
                Place.Field.FORMATTED_ADDRESS,
                Place.Field.LOCATION);

// Define the search area around the current location.
LatLng currentLocation = new LatLng(37.4220, -122.0841);
LocationRestriction circle =
        CircularBounds.newInstance(currentLocation, /* radius= */ 500.0);

// Use the builder to create a SearchNearbyRequest.
SearchNearbyRequest request =
        SearchNearbyRequest.builder(circle, placeFields).setMaxResultCount(20).build();

// Call searchNearby and handle the response (first check that the user has granted
// permission).
if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION)
        == PackageManager.PERMISSION_GRANTED) {
    Task<SearchNearbyResponse> placeResponse = placesClient.searchNearby(request);
    placeResponse.addOnCompleteListener(
            task -> {
                binding.progressBar.setVisibility(View.GONE);
                if (task.isSuccessful()) {
                    SearchNearbyResponse response = task.getResult();
                    adapter.setPlaces(response.getPlaces());
                } else {
                    Exception exception = task.getException();
                    if (exception instanceof ApiException apiException) {
                        Log.e(
                                "CurrentPlace",
                                "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é fournit une 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é sera comprise entre 0,0 et 1,0.

Par exemple, pour représenter une probabilité de 55 % que le bon lieu soit le lieu A et une probabilité de 35 % que ce soit le 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.

Afficher les mentions dans votre application

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