Сведения о месте

Выберите платформу: Android iOS JavaScript Web Service

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

Сведения о месте

Объект Place предоставляет информацию о конкретном месте. Вы можете получить объект Place следующими способами:

• Вызов PlacesClient.findCurrentPlace() — см. руководство по получению текущего места .
• Вызов PlacesClient.fetchPlace() — см. руководство по получению места по идентификатору .

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

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

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

Ява

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

Котлин

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

Примечание: findCurrentPlace() и fetchPlace() поддерживают разные наборы полей. findCurrentPlace() НЕ поддерживает следующие поля: Place.Field.ADDRESS_COMPONENTS , Place.Field.CURBSIDE_PICKUP , Place.Field.DELIVERY , Place.Field.DINE_IN , Place.Field.OPENING_HOURS , Place.Field.PHONE_NUMBER , Place.Field.TAKEOUT , Place.Field.UTC_OFFSET и Place.Field.WEBSITE_URI .

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

• getAddress() — адрес места в удобочитаемом формате.
• getAddressComponents() — List компонентов адреса для этого места. Эти компоненты предназначены для извлечения структурированной информации об адресе места, например, для поиска города, в котором расположено место. Не используйте эти компоненты для форматирования адреса; вместо этого вызовите getAddress() , который предоставляет адрес в локализованном формате.
• getID() — текстовый идентификатор места. Подробнее об идентификаторах мест читайте в оставшейся части этой страницы.
• getLatLng() — географическое положение места, указанное в виде координат широты и долготы.
• getName() — название места.
• getOpeningHours() — OpeningHours заведения. Вызовите OpeningHours.getWeekdayText() , чтобы вернуть список строк, представляющих часы открытия и закрытия для каждого дня недели. Вызовите OpeningHours.getPeriods() , чтобы вернуть список объектов period с более подробной информацией, которая эквивалентна данным, предоставленным getWeekdayText() . Примечание. Если место всегда открыто, период времени представлен как воскресенье в полночь, а closeEvent имеет значение null.
• isOpen() — логическое значение, указывающее, открыто ли место в данный момент. Если время не указано, по умолчанию используется сейчас. isOpen будет возвращено только в том случае, если доступны как Place.Field.UTC_OFFSET , так и Place.Field.OPENING_HOURS . Чтобы обеспечить точные результаты, запросите поля Place.Field.BUSINESS_STATUS и Place.Field.UTC_OFFSET в исходном запросе места. Если не запрашивается, предполагается, что бизнес работает. Посмотрите это видео , чтобы узнать, как использовать isOpen со сведениями о месте.

Несколько простых примеров:

Ява

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

      

Котлин

val name = place.name
val address = place.address
val location = place.latLng

      

Получить место по ID

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

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

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

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

Ява

// Define a Place ID.
final String placeId = "INSERT_PLACE_ID_HERE";

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

// 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();
    Log.i(TAG, "Place found: " + place.getName());
}).addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
        final ApiException apiException = (ApiException) exception;
        Log.e(TAG, "Place not found: " + exception.getMessage());
        final int statusCode = apiException.getStatusCode();
        // TODO: Handle error with given status code.
    }
});

      

Котлин

// Define a Place ID.
val placeId = "INSERT_PLACE_ID_HERE"

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

// 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
        Log.i(PlaceDetailsActivity.TAG, "Place found: ${place.name}")
    }.addOnFailureListener { exception: Exception ->
        if (exception is ApiException) {
            Log.e(TAG, "Place not found: ${exception.message}")
            val statusCode = exception.statusCode
            TODO("Handle error with given status code")
        }
    }

      

Вы можете использовать CancellationToken , чтобы попытаться отменить запрос к любому из классов запросов (например, FetchPlaceRequest ). Отмена производится на основе максимальных усилий. После отправки запроса на отмену ответ не возвращается. Выдача токена отмены НЕ гарантирует, что конкретный запрос будет отменен, и с вас все равно может взиматься плата за запрос, даже если ответ не будет возвращен .

Отображение атрибутов в вашем приложении

Когда ваше приложение отображает информацию о месте, оно также должно отображать атрибуцию. См. документацию по атрибуциям .

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

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

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

Для получения дополнительной информации см. обзор идентификатора места .