Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

Информация о местах (устаревшая версия)

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

Places SDK для Android (устаревшая версия) предоставляет вашему приложению подробную информацию о местах, включая название и адрес места, географическое местоположение, указанное в виде координат широты/долготы, тип места (например, ночной клуб, зоомагазин, музей) и многое другое. Чтобы получить доступ к этой информации для определенного места, вы можете использовать идентификатор места – стабильный идентификатор, который уникальным образом идентифицирует место.

Об этом месте

Объект Place предоставляет информацию об определенном месте. Чтобы получить объект Place, вызовите метод PlacesClient.fetchPlace(). Подробнее о том, как получить место по идентификатору…

При запросе места необходимо указать, какие данные о нем нужно вернуть. Для этого передайте список значений Place.Field, указывающих, какие данные нужно вернуть. Этот список важен, поскольку он влияет на стоимость каждого запроса.

Поскольку ответ на запрос информации из таких полей не может быть пустым, возвращаются только результаты для мест, о которых такая информация есть. Например, если у места нет фотографий, поля photos в результатах не будет.

В следующем примере передается список из трех значений Place.Field, чтобы указать, какие данные должны быть возвращены по запросу:

Kotlin

// Specify the fields to return.
val placeFields = listOf(Place.Field.DISPLAY_NAME, Place.Field.RATING)

Java

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.DISPLAY_NAME, Place.Field.RATING);

Как получить доступ к полям данных объекта Place

Получив объект Place, используйте его методы для доступа к полям данных, указанным в запросе. Если в объекте Place нет поля, связанный с ним метод возвращает значение null. Ниже приведены примеры некоторых доступных методов.

getAddress() – адрес места в человекочитаемом формате.
getAddressComponents() – List компонентов адреса для этого места. Эти компоненты предназначены для извлечения структурированной информации об адресе места, например для поиска города, в котором находится место. Не используйте эти компоненты для форматирования адреса. Вместо этого вызовите метод getAddress(), который возвращает локализованный отформатированный адрес.
getId() – текстовый идентификатор места. Подробнее об идентификаторах мест рассказывается далее на этой странице.
getLatLng() – географическое местоположение места, указанное в виде координат широты и долготы.
getName() – название места.
getOpeningHours() – OpeningHours места. Вызовите метод OpeningHours.getWeekdayText(), чтобы получить список строк, представляющих часы работы по дням недели. Вызовите OpeningHours.getPeriods(), чтобы получить список объектов period с более подробной информацией, эквивалентной данным, предоставляемым getWeekdayText().

Примечание. Если место работает круглосуточно, период времени представлен как воскресенье в полночь, а closeEvent имеет значение null.

Объект Place также содержит метод getCurrentOpeningHours(), который возвращает часы работы места в течение следующих семи дней, и метод getSecondaryOpeningHours(), который возвращает дополнительные часы работы места в течение следующих семи дней.
isOpen() – логическое значение, указывающее, открыто ли место в данный момент. Если время не указано, по умолчанию используется текущее. Значение isOpen возвращается, только если доступны оба значения: Place.Field.UTC_OFFSET и Place.Field.OPENING_HOURS. Чтобы получить точные результаты, запросите поля Place.Field.BUSINESS_STATUS и Place.Field.UTC_OFFSET в исходном запросе места. Если запрос не отправлен, считается, что компания работает. См. это видео об использовании isOpen с информацией о местах.

Примечание. Этот метод больше не поддерживается. Вместо этого используйте PlacesClient.isOpen(IsOpenRequest request). Подробнее о том, как получить статус открытости…

Ниже приведено несколько примеров.

Kotlin

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

Java

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

Получение информации о месте по его идентификатору

Идентификатор места – это уникальный текстовый идентификатор. В Places SDK для Android идентификатор места можно получить, вызвав метод Place.getId(). Сервис автозаполнения мест также возвращает идентификатор места для каждого места, соответствующего поисковому запросу и фильтру. Вы можете сохранить идентификатор места и использовать его, чтобы получить объект Place позже.

Чтобы получить место по идентификатору, вызовите PlacesClient.fetchPlace(), передав FetchPlaceRequest.

API возвращает FetchPlaceResponse в Task. FetchPlaceResponse содержит объект Place, соответствующий указанному идентификатору места.

В примере ниже показан вызов fetchPlace() для получения сведений об указанном месте.

Kotlin

// Define a Place ID.
val placeId = PlaceIdProvider.getRandomPlaceId()

// Specify the fields to return.
val placeFields = listOf(
    Place.Field.ID,
    Place.Field.DISPLAY_NAME,
    Place.Field.FORMATTED_ADDRESS,
    Place.Field.LOCATION,
)

// Construct a request object, passing the place ID and fields array.
val request = FetchPlaceRequest.newInstance(placeId, placeFields)

placesClient.fetchPlace(request)
    .addOnSuccessListener { response: FetchPlaceResponse ->
        val place = response.place

        val name = place.displayName
        val address = place.formattedAddress
        val location = place.location

        binding.placeName.text = name
        binding.placeAddress.text = address
        if (location != null) {
            binding.placeLocation.text = getString(
                R.string.place_location,
                location.latitude,
                location.longitude,
            )
        } else {
            binding.placeLocation.text = null
        }
        Log.i(TAG, "Place found: ${place.displayName}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            val message = getString(R.string.place_not_found, exception.message)
            binding.placeName.text = message
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

Java

// Define a Place ID.
final String placeId = PlaceIdProvider.getRandomPlaceId();

// Specify the fields to return.
final List<Place.Field> placeFields =
        Arrays.asList(
                Place.Field.ID,
                Place.Field.DISPLAY_NAME,
                Place.Field.FORMATTED_ADDRESS,
                Place.Field.LOCATION);

// Construct a request object, passing the place ID and fields array.
final FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);

placesClient
        .fetchPlace(request)
        .addOnSuccessListener(
                (response) -> {
                    Place place = response.getPlace();

                    final CharSequence name = place.getDisplayName();
                    final CharSequence address = place.getFormattedAddress();
                    final LatLng location = place.getLocation();

                    binding.placeName.setText(name);
                    binding.placeAddress.setText(address);
                    if (location != null) {
                        binding.placeLocation.setText(
                                getString(
                                        R.string.place_location,
                                        location.latitude,
                                        location.longitude));
                    } else {
                        binding.placeLocation.setText(null);
                    }

                    Log.i(TAG, "Place found: " + place.getDisplayName());
                })
        .addOnFailureListener(
                (exception) -> {
                    if (exception instanceof ApiException apiException) {
                        final String message =
                                getString(
                                        R.string.place_not_found,
                                        apiException.getMessage());
                        binding.placeName.setText(message);
                        Log.e(TAG, "Place not found: " + exception.getMessage());
                        final int statusCode = apiException.getStatusCode();
                        // TODO: Handle error with given status code.
                    }
                });

Примечание. Подробную информацию об инициализации PlacesClient можно найти в разделе Инициализация клиента Places API.

Получение статуса открытия

Метод PlacesClient.isOpen(IsOpenRequest request) возвращает объект IsOpenResponse, указывающий, открыто ли место в настоящее время, на основе времени, указанного в вызове.

Этот метод принимает один аргумент типа IsOpenRequest, который содержит:

Объект Place или строка, указывающая идентификатор места.
Примечание. Объект Place должен содержать действительный идентификатор места.
Необязательное значение времени, указывающее время в миллисекундах с 1970-01-01T00:00:00Z. Если время не указано, по умолчанию используется текущее.

Для этого метода в объекте Place должны быть следующие поля:

Place.Field.BUSINESS_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET

Если эти поля не указаны в объекте Place или если вы передаете идентификатор места, метод использует PlacesClient.fetchPlace(), чтобы получить их. Подробнее о том, как создать объект Place с нужными полями…

Примечание. Оплата по коду Basic Data SKU начисляется за вызовы fetchPlace() для Place.Field.UTC_OFFSET и Place.Field.BUSINESS_STATUS. Оплата по коду Places Contact Data SKU начисляется за вызовы fetchPlace() для Place.Field.CURRENT_OPENING_HOURS и Place.Field.OPENING_HOURS.

В следующем примере определяется, открыто ли место в данный момент. В этом примере вы передаете в isOpen() только идентификатор места:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = PlaceIdProvider.getRandomPlaceId()

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    Log.e("PlaceIsOpen", "Error: " + e.message)
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen ?: false
    binding.isOpenByIdResult.text = getString(R.string.is_open_by_id, isOpen.toString())
    Log.d("PlaceIsOpen", "Is open by ID: $isOpen")
}
// ...

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    Log.e("PlaceIsOpen", "Error: " + e.getMessage());
    return;
}

Task<IsOpenResponse> placeTask = placesClient.isOpen(isOpenRequest);

placeTask.addOnSuccessListener(
        (response) -> {
            final boolean isOpen = Boolean.TRUE.equals(response.isOpen());
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, String.valueOf(isOpen)));
            Log.d("PlaceIsOpen", "Is open by ID: " + isOpen);
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByIdResult.setText(
                    getString(R.string.is_open_by_id, "Error: " + exception.getMessage()));
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
        });

В следующем примере показан вызов isOpen(), в котором передается объект Place. Объект Place должен содержать действительный идентификатор места:

Kotlin

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = PlaceIdProvider.getRandomPlaceId()
// Specify the required fields for an isOpen request.
val placeFields: List<Place.Field> = listOf(
    Place.Field.BUSINESS_STATUS,
    Place.Field.CURRENT_OPENING_HOURS,
    Place.Field.ID,
    Place.Field.OPENING_HOURS,
    Place.Field.DISPLAY_NAME,
)

val placeRequest: FetchPlaceRequest =
    FetchPlaceRequest.newInstance(placeId, placeFields)
val placeTask: Task<FetchPlaceResponse> = placesClient.fetchPlace(placeRequest)
placeTask.addOnSuccessListener { placeResponse ->
    place = placeResponse.place

    val isOpenRequest: IsOpenRequest = try {
        IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis)
    } catch (e: IllegalArgumentException) {
        Log.e("PlaceIsOpen", "Error: " + e.message)
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = when (isOpenResponse.isOpen) {
            true -> getString(R.string.is_open)
            else -> getString(R.string.is_closed)
        }
        binding.isOpenByObjectResult.text = getString(
            R.string.is_open_by_object,
            place.displayName,
            isOpen,
        )
        Log.d("PlaceIsOpen", "Is open by object: $isOpen")
    }
    // ...
}
// ...

Java

@NonNull Calendar isOpenCalendar = Calendar.getInstance();
String placeId = PlaceIdProvider.getRandomPlaceId();
// Specify the required fields for an isOpen request.
List<Place.Field> placeFields =
        new ArrayList<>(
                Arrays.asList(
                        Place.Field.BUSINESS_STATUS,
                        Place.Field.CURRENT_OPENING_HOURS,
                        Place.Field.ID,
                        Place.Field.OPENING_HOURS,
                        Place.Field.DISPLAY_NAME));

FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields);
Task<FetchPlaceResponse> placeTask = placesClient.fetchPlace(request);

placeTask.addOnSuccessListener(
        (placeResponse) -> {
            Place place = placeResponse.getPlace();
            IsOpenRequest isOpenRequest;

            try {
                isOpenRequest =
                        IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis());
            } catch (IllegalArgumentException e) {
                Log.e("PlaceIsOpen", "Error: " + e.getMessage());
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> {
                        final boolean isOpen = Boolean.TRUE.equals(isOpenResponse.isOpen());
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        String.valueOf(isOpen)));
                        Log.d("PlaceIsOpen", "Is open by object: " + isOpen);
                    });
            isOpenTask.addOnFailureListener(
                    (exception) -> { // also update the result text field
                        binding.isOpenByObjectResult.setText(
                                getString(
                                        R.string.is_open_by_object,
                                        place.getDisplayName(),
                                        "Error: " + exception.getMessage()));
                        Log.e("PlaceIsOpen", "Error: " + exception.getMessage());
                    });
        });
placeTask.addOnFailureListener(
        (exception) -> {
            binding.isOpenByObjectResult.setText("Error: " + exception.getMessage());
            Log.e("PlaceIsOpen", "Error: " + exception.getMessage());

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

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

Подробнее об идентификаторах мест

Идентификатор места, используемый в Places SDK для Android (старая версия), совпадает с идентификатором, используемым в Places API (старая версия). Идентификатор может относиться только к одному месту, однако одному месту можно присвоить сразу несколько идентификаторов. Идентификатор места может измениться и по другим причинам. Например, это может произойти, если компания переехала.

Если вы запрашиваете место по его идентификатору, то можете быть уверены, что в ответе всегда будет одно и то же место (если оно ещё существует). Однако обратите внимание, что ответ может содержать идентификатор места, отличный от указанного в запросе.

Подробную информацию можно найти в статье Общие сведения об идентификаторах мест.

Информация о местах (устаревшая версия) Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Об этом месте

Kotlin

Java

Как получить доступ к полям данных объекта Place

Kotlin

Java

Получение информации о месте по его идентификатору

Kotlin

Java

Получение статуса открытия

Kotlin

Java

Kotlin

Java

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

Подробнее об идентификаторах мест

Информация о местах (устаревшая версия)