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.Fields, указав типы данных о местах, которые должно запрашивать ваше приложение.
  3. Вызовите PlacesClient.findCurrentPlace(), передав FindCurrentPlaceRequest, созданный на предыдущем шаге.
  4. Получите список PlaceLikelihood из FindCurrentPlaceResponse.

Поля соответствуют результатам поиска мест и делятся на три категории, которые оплачиваются по разным тарифам: основные данные, контактные данные и данные об атмосфере. Запросы основных данных оплачиваются по базовой цене, и за них дополнительная плата не взимается. Запросы контактных данных и данных об атмосфере оплачиваются по более высокой ставке. Подробную информацию о том, как начисляется плата за запросы данных 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)
val request = 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
) {
    placesClient.findCurrentPlace(request).addOnSuccessListener { response ->
        binding.progressBar.visibility = View.GONE
        adapter.setPlaceLikelihoods(response.placeLikelihoods)
    }.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);

// 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 -> {
        binding.progressBar.setVisibility(View.GONE);
        if (task.isSuccessful()) {
            FindCurrentPlaceResponse response = task.getResult();
            adapter.setPlaceLikelihoods(response.getPlaceLikelihoods());
        } 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(), в нем также должно быть указано авторство. Подробнее об атрибуции…