Places SDK для Android предоставляет вашему приложению обширную информацию о местах, включая название и адрес места, географическое положение, указанное в виде координат широты и долготы, тип места (например, ночной клуб, зоомагазин, музей) и многое другое. Чтобы получить доступ к этой информации для конкретного места, вы можете использовать идентификатор места — стабильный идентификатор, который однозначно идентифицирует место.
Детали места
Объект Place
предоставляет информацию о конкретном месте. Вы можете получить объект Place
следующими способами:
- Вызов
PlacesClient.fetchPlace()
— см. руководство по получению места по идентификатору . - Вызов
PlacesClient.findCurrentPlace()
— см. руководство по получению текущего места .
Когда вы запрашиваете место, вы должны указать, какие данные о месте нужно вернуть. Для этого передайте список значений Place.Field , определяющих возвращаемые данные. Этот список является важным фактором, поскольку он влияет на стоимость каждого запроса .
Поскольку результаты с данными о местах не могут быть пустыми, возвращаются только результаты с данными о местах (например, если в запрошенном месте нет фотографий, поле photos
не будет присутствовать в результате).
В следующем примере передается список из трех значений Place.Field для указания данных, возвращаемых запросом:
Котлин
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Ява
// Specify the fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Доступ к полям данных объекта Place
После получения объекта Place
используйте методы объекта для доступа к полям данных, указанным в запросе. Если поле отсутствует в объекте Place
, связанный метод возвращает значение null. Ниже показаны примеры некоторых доступных методов. Полный список всех методов см. в справочнике Place
API.
-
getAddress()
— адрес места в удобочитаемом формате. -
getAddressComponents()
—List
компонентов адреса для этого места. Эти компоненты предназначены для извлечения структурированной информации об адресе места, например, для поиска города, в котором оно расположено. Не используйте эти компоненты для форматирования адреса; вместо этого вызовитеgetAddress()
, который предоставит локализованный форматированный адрес. -
getId()
— текстовый идентификатор места. Подробнее об идентификаторах мест читайте далее на этой странице. -
getLatLng()
— географическое положение места, указанное в виде координат широты и долготы. -
getName()
– название места. getOpeningHours()
–OpeningHours
заведения. ВызовитеOpeningHours.getWeekdayText()
чтобы вернуть список строк, которые представляют часы открытия и закрытия для каждого дня недели. ВызовитеOpeningHours.getPeriods()
, чтобы вернуть список объектовperiod
с более подробной информацией, эквивалентной данным, предоставленнымgetWeekdayText()
.Объект
Place
также содержит методgetCurrentOpeningHours()
, который возвращает часы работы места в течение следующих семи дней, иgetSecondaryOpeningHours()
, который возвращает дополнительные часы работы места в течение следующих семи дней.isOpen()
— логическое значение, указывающее, открыто ли место в данный момент. Если время не указано, по умолчанию используется значение «сейчас».isOpen
будет возвращен только в том случае, если доступны какPlace.Field.UTC_OFFSET
, так иPlace.Field.OPENING_HOURS
. Чтобы обеспечить точные результаты, запросите поляPlace.Field.BUSINESS_STATUS
иPlace.Field.UTC_OFFSET
в исходном запросе места. Если запрос не запрошен, предполагается, что бизнес работает. Посмотрите это видео , чтобы узнать, как использоватьisOpen
с подробностями о месте.
Несколько простых примеров:
Котлин
val name = place.name val address = place.address val location = place.latLng
Ява
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
Получить место по ID
Идентификатор места — это текстовый идентификатор, который однозначно идентифицирует место. В Places SDK для Android вы можете получить идентификатор места, вызвав Place.getId()
. Служба автозаполнения мест также возвращает идентификатор места для каждого места, которое соответствует предоставленному поисковому запросу и фильтру. Вы можете сохранить идентификатор места и использовать его для повторного получения объекта Place
позже.
Чтобы получить место по идентификатору, вызовите PlacesClient.fetchPlace()
, передав FetchPlaceRequest
.
API возвращает FetchPlaceResponse
в Task
. FetchPlaceResponse
содержит объект Place
, соответствующий предоставленному идентификатору места.
В следующем примере кода показан вызов fetchPlace()
для получения сведений об указанном месте.
Котлин
// Define a Place ID. val placeId = IN"SERT_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, Pl"ace found: ${place.name}) " }.addOnFailureListener { exception: Exception - > if (exception is ApiException) { Log.e(TAG, Pl"ace not found: ${exception.message}) " val statusCode = exception.statusCode TODO(Ha"ndle error with given status code) " } }
Ява
// Define a Place ID. final String placeId = I"NSERT_PLACE_ID_HERE;" // Specify the fields to return. final ListP<lace.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, P"lace found: "+ place.getName()); }).addOnFailureListener((exception) - >{ if (exception instanceof ApiException) { final ApiException apiException = (ApiException) exception; Log.e(TAG, P"lace not found: "+ exception.getMessage()); final int statusCode = apiException.getStatusCode(); // TODO: Handle error with given status code. } });
Получить открытый статус
Метод PlacesClient.isOpen(IsOpenRequest request)
возвращает объект IsOpenResponse
, указывающий, открыто ли место в данный момент, на основе времени, указанного в вызове.
Этот метод принимает один аргумент типа IsOpenRequest
, который содержит:
- Объект
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 с необходимыми полями см. в разделе Детали места .
В следующем примере определяется, открыто ли место в данный момент. В этом примере вы передаете в isOpen()
только идентификатор места:
Котлин
val isOpenCalendar: Calendar = Calendar.getInstance() val placeId = Ch"IJD3uTd9hx5kcR1IQvGfr8dbk "val request: IsOpenRequest = try { IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return } val isOpenTask: TaskIs<OpenResponse => placesClient.isOpen(request) isOpenTask.addOnSuccessListener { response - > val isOpen = response.isOpen } // ...
Ява
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = C"hIJD3uTd9hx5kcR1IQvGfr8dbk;" IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } TaskI<sOpenResponse >placeTask = placesClient.isOpen(isOpenRequest); placeTask.addOnSuccessListener( (response) - > isOpen = response.isOpen()); // ...
В следующем примере показан вызов isOpen()
, в который вы передаете объект Place
. Объект Place
должен содержать действительный идентификатор места:
Котлин
val isOpenCalendar: Calendar = Calendar.getInstance() var place: Place val placeId = Ch"IJD3uTd9hx5kcR1IQvGfr8dbk /"/ Specify the required fields for an isOpen request. val placeFields: ListPl<ace.Field => listOf( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET ) val placeRequest: FetchPlaceRequest = FetchPlaceRequest.newInstance(placeId, placeFields) val placeTask: TaskFe<tchPlaceResponse => placesClient.fetchPlace(placeRequest) placeTask.addOnSuccessListener { placeResponse - > place = placeResponse.place val isOpenRequest: IsOpenRequest = try { IsOpenRequest.newInstance(place, isOpenCalendar.timeInMillis) } catch (e: IllegalArgumentException) { e.printStackTrace() return@addOnSuccessListener } val isOpenTask: TaskIs<OpenResponse => placesClient.isOpen(isOpenRequest) isOpenTask.addOnSuccessListener { isOpenResponse - > val isOpen = isOpenResponse.isOpen } // ... } // ...
Ява
@NonNull Calendar isOpenCalendar = Calendar.getInstance(); String placeId = C"hIJD3uTd9hx5kcR1IQvGfr8dbk;" // Specify the required fields for an isOpen request. ListP<lace.Field >placeFields = new ArrayList(<>Arrays.asList( Place.Field.BUSINESS_STATUS, Place.Field.CURRENT_OPENING_HOURS, Place.Field.ID, Place.Field.OPENING_HOURS, Place.Field.UTC_OFFSET )); FetchPlaceRequest request = FetchPlaceRequest.newInstance(placeId, placeFields); TaskF<etchPlaceResponse >placeTask = placesClient.fetchPlace(request); placeTask.addOnSuccessListener( (placeResponse) - >{ Place place = placeResponse.getPlace(); IsOpenRequest isOpenRequest; try { isOpenRequest = IsOpenRequest.newInstance(place, isOpenCalendar.getTimeInMillis()); } catch (IllegalArgumentException e) { e.printStackTrace(); return; } TaskI<sOpenResponse >isOpenTask = placesClient.isOpen(isOpenRequest); isOpenTask.addOnSuccessListener( (isOpenResponse) - >isOpen = isOpenResponse.isOpen()); // ... }); // ...
Отображение авторства в вашем приложении
Когда ваше приложение отображает информацию о месте, включая обзоры мест, оно также должно отображать любые сведения об авторстве. Для получения дополнительной информации см. Атрибуции .
Подробнее об идентификаторах мест
Идентификатор места, используемый в Places SDK для Android, совпадает с идентификатором, который используется в Places API . Каждый идентификатор места может относиться только к одному месту, но одно место может иметь более одного идентификатора места. Существуют и другие обстоятельства, которые могут привести к тому, что месту будет присвоен новый идентификатор. Например, это может произойти, если бизнес переезжает на новое место.
Когда вы запрашиваете место, указав идентификатор места, вы можете быть уверены, что всегда получите в ответ одно и то же место (если место еще существует). Однако обратите внимание, что ответ может содержать идентификатор места, отличный от идентификатора в вашем запросе.
Дополнительную информацию см. в обзоре идентификаторов мест .