Aktualne miejsce (starsza wersja)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Za pomocą pakietu Places SDK for Android możesz znaleźć miejsce w aktualnie zgłaszanej lokalizacji urządzenia. Miejsca to m.in. lokalnie działające firmy, ciekawe miejsca i położenia geograficzne.

Uprawnienia

Aby korzystać z biblioteki, nie musisz deklarować żadnych dodatkowych uprawnień w pliku manifestu aplikacji, ponieważ biblioteka deklaruje wszystkie uprawnienia, których używa, w swoim pliku manifestu. Jeśli jednak aplikacja używa PlacesClient.findCurrentPlace(), musisz poprosić o uprawnienia dostępu do lokalizacji w czasie działania.

Jeśli Twoja aplikacja nie używa PlacesClient.findCurrentPlace(), wyraźnie usuń uprawnienia ACCESS_FINE_LOCATION i ACCESS_COARSE_LOCATION wprowadzone przez bibliotekę, dodając do pliku manifestu te informacje:

<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>

Dowiedz się więcej o  uprawnieniach i rozważ użycie EasyPermissions, aby rozpocząć.

Uzyskiwanie bieżącej lokalizacji

Aby znaleźć lokalnie działającą firmę lub inne miejsce, w którym aktualnie znajduje się urządzenie, wykonaj te czynności:

  1. Wywołaj ContextCompat.checkSelfPermission, aby sprawdzić, czy użytkownik przyznał uprawnienia dostępu do lokalizacji urządzenia. Aplikacja musi też zawierać kod, który prosi użytkownika o przyznanie uprawnień i obsługuje wynik. Więcej informacji znajdziesz w artykule Prośba o uprawnienia aplikacji.
  2. Utwórz FindCurrentPlaceRequest, przekazując List obiektów Place.Field i określając typy danych o miejscach, o które aplikacja powinna prosić.
  3. Wywołaj PlacesClient.findCurrentPlace(), przekazując obiekt FindCurrentPlaceRequest utworzony w poprzednim kroku.
  4. Pobierz listę PlaceLikelihood z FindCurrentPlaceResponse.

Pola odpowiadają wynikom wyszukiwania miejsc i są podzielone na 3 kategorie rozliczeniowe: Basic, Contact i Atmosphere. Pola podstawowe są rozliczane według stawki podstawowej i nie wiążą się z dodatkowymi opłatami. Pola Kontakt i Atmosfera są rozliczane według wyższej stawki. Więcej informacji o tym, jak rozliczane są żądania danych o miejscach, znajdziesz w artykule Użycie i rozliczenia.

Interfejs API zwraca obiekt FindCurrentPlaceResponse w obiekcie Task. FindCurrentPlaceResponse zawiera listę obiektów PlaceLikelihood reprezentujących miejsca, w których prawdopodobnie znajduje się urządzenie. W przypadku każdego miejsca wynik zawiera wskazanie prawdopodobieństwa, że jest to właściwe miejsce. Lista może być pusta, jeśli nie ma znanego miejsca odpowiadającego danej lokalizacji urządzenia.

Możesz wywołać metodę PlaceLikelihood.getPlace(), aby pobrać obiekt Place, oraz metodę PlaceLikelihood.getLikelihood(), aby uzyskać ocenę prawdopodobieństwa miejsca. Wyższa wartość oznacza większe prawdopodobieństwo, że miejsce jest najlepiej dopasowane.

Poniższy przykładowy kod pobiera listę miejsc, w których urządzenie najprawdopodobniej się znajduje, i rejestruje nazwę oraz prawdopodobieństwo dla każdego miejsca.

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

Uwagi dotyczące wartości prawdopodobieństwa:

  • Prawdopodobieństwo określa względne prawdopodobieństwo, że dane miejsce jest najlepiej dopasowane na liście miejsc zwróconych w ramach pojedynczego żądania. Nie można porównywać prawdopodobieństw w różnych żądaniach.
  • Wartość prawdopodobieństwa będzie mieścić się w zakresie od 0,0 do 1,0.

Na przykład, aby przedstawić 55-procentowe prawdopodobieństwo, że prawidłowym miejscem jest miejsce A, i 35-procentowe prawdopodobieństwo, że jest to miejsce B, odpowiedź zawiera 2 elementy: miejsce A z prawdopodobieństwem 0,55 i miejsce B z prawdopodobieństwem 0,35.

Wyświetlanie atrybucji w aplikacji

Gdy aplikacja wyświetla informacje uzyskane z PlacesClient.findCurrentPlace(), musi też wyświetlać informacje o źródle. Zapoznaj się z dokumentacją dotyczącą atrybucji.