Current Place (устаревшая версия)

Разработчики из Европейской экономической зоны (ЕЭЗ)

С помощью Places SDK для Android вы можете определить место, в котором находится устройство. Например, это могут быть местные компании, достопримечательности и географические объекты.

Разрешения

Чтобы использовать библиотеку, вам не нужно объявлять дополнительные разрешения в манифесте приложения, поскольку библиотека объявляет все разрешения, которые она использует в своем манифесте. Однако если в приложении используется PlacesClient.findCurrentPlace(), то вы должны запрашивать доступ к данным о местоположении во время выполнения.

Если ваше приложение не использует PlacesClient.findCurrentPlace(), явно удалите разрешения ACCESS_FINE_LOCATION и ACCESS_COARSE_LOCATION, добавленные библиотекой, указав в манифесте следующее:

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

Подробнее о разрешениях… Чтобы начать работу, рекомендуем использовать EasyPermissions.

Получение данных о текущем местоположении

Чтобы найти компанию или другое место, где сейчас находится устройство, выполните следующие действия:

  1. Вызовите ContextCompat.checkSelfPermission, чтобы проверить, предоставил ли пользователь разрешение на доступ к данным о местоположении устройства. В приложении также должен быть код, который запрашивает разрешение у пользователя и обрабатывает результат. Подробнее о запросе разрешений для приложения…
  2. Создайте объект FindCurrentPlaceRequest, передав ему список List объектов Place.Field, в которых указаны типы данных о месте, запрашиваемые приложением.
  3. Вызовите PlacesClient.findCurrentPlace(), передав объект FindCurrentPlaceRequest, созданный на предыдущем шаге.
  4. Получите список PlaceLikelihood из FindCurrentPlaceResponse.

Поля соответствуют результатам поиска мест и делятся на три категории, которые оплачиваются по разным тарифам: основные данные, контактные данные и данные об атмосфере. Поля Basic оплачиваются по базовой цене, и за них дополнительная плата не взимается. Запросы контактных данных и данных об атмосфере оплачиваются по более высокой ставке. Подробную информацию о том, как начисляется плата за запросы данных Places, можно найти в статье Статистика использования и оплата.

API возвращает FindCurrentPlaceResponse в Task. FindCurrentPlaceResponse содержит список объектов PlaceLikelihood, представляющих места, где может находиться устройство. Для каждого места в результатах указывается вероятность того, что оно является правильным. Список может быть пустым, если в указанном местоположении устройства нет известных мест.

Вы можете вызвать PlaceLikelihood.getPlace(), чтобы получить объект Place, и PlaceLikelihood.getLikelihood(), чтобы получить оценку вероятности места. Чем выше значение, тем больше вероятность того, что место является наилучшим совпадением.

В следующем примере кода извлекается список мест, где устройство может находиться с наибольшей вероятностью, и регистрируется название и вероятность для каждого места.

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

Примечания, касающиеся значений вероятности.

  • Вероятность – это относительная величина, которая показывает, насколько место соответствует запросу по сравнению с другими местами в списке. Нельзя сравнивать вероятности для разных запросов.
  • Значение вероятности будет находиться в диапазоне от 0,0 до 1,0.

Например, если вероятность того, что правильным местом является место А, составляет 55 %, а вероятность того, что это место Б, составляет 35 %, ответ будет содержать два элемента: место А с вероятностью 0,55 и место Б с вероятностью 0,35.

Указание авторства в приложении

Если в вашем приложении демонстрируется информация, полученная с помощью вызова PlacesClient.findCurrentPlace(), в нем также должно быть указано авторство. Подробнее об атрибуции…