Описания мест

Выберите платформу: Android iOS Веб-служба JavaScript

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

Детали места

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

• Вызов PlacesClient.fetchPlace() — см. руководство по получению места по идентификатору .
• Вызов PlacesClient.findCurrentPlace() — см. руководство по получению текущего места .
  В то время как PlacesClient.fetchPlace() поддерживает все поля данных о местах, PlacesClient.findCurrentPlace() поддерживает только подмножество полей данных о местах. Список полей, НЕ поддерживаемых функцией findCurrentPlace() , см. в разделе Поддержка полей Places SDK для Android .

Когда вы запрашиваете место, вы должны указать, какие данные о месте нужно вернуть. Для этого передайте список значений 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 placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Примечание. Places SDK для Android и Places SDK для Android (новинка) поддерживают разные модели ценообразования. Это означает, что цена звонка зависит от запрашиваемых вами полей и версии SDK, которую вы используете. Подробную информацию о ценах на оба SDK см. в разделе « Использование и выставление счетов» .

Доступ к полям данных объекта Place

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

• 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) . Дополнительную информацию см. в разделе Получение статуса открытия .

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

Котлин

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

      

Данные о месте доступа добавлены в версии 3.3.0.

Places SDK для Android версии 3.3.0 добавляет в Place новые данные:

• Типы мест : значения новых типов, связанные с местом.
• Отзывы : До пяти отзывов на одно место.
• Код языка названия : код языка названия места.

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

Примечание. Новый SDK поддерживает только новые данные Place в Java.

Доступ к новым типам мест

С каждым местом может быть связано одно или несколько значений типа . В Places SDK для Android версии 3.3.0 добавлено множество новых значений типов. Полный список см. в разделе «Расширенные типы мест» .

В Places SDK для Android версии 3.2.0 и более ранних версий вы использовали метод Place.getTypes() для доступа к значениям типов, связанным с местом. Place.getTypes() возвращает список типов в виде значений перечисления, определенных Place.Types .

Метод Place.getTypes() устарел в Places SDK для Android версии 3.3.0. Хотя вы можете продолжать использовать его в течение периода устаревания, вам следует вместо этого перенести свои приложения на использование Place.getPlaceTypes() .

Метод Place.getPlaceTypes() возвращает значения типа в виде списка строковых значений. Возвращаемые значения зависят от вашей версии Places SDK для Android:

• Places SDK для Android (новое) : возвращает строки, определенные в таблице A и таблице B, показанные в типах мест (новое) , включая все дополнительные типы мест, добавленные в версии 3.3.0.
• Places SDK для Android : возвращает перечисления, определенные Place.Types , которые не включают новые типы, добавленные в версии 3.3.0.

Чтобы узнать ключевые различия между двумя версиями SDK, см. раздел «Выбор версии SDK» .

Доступ к отзывам о местах

В Places SDK для Android (новинка) добавлен класс Review , который содержит обзор места. Объект Place может содержать до пяти отзывов.

Класс Review также может содержать указание авторства и указание автора. Если вы отображаете обзор в своем приложении, вы также должны указать любую ссылку или ссылку на автора. Дополнительную информацию см. в разделе Отображение обзора .

Чтобы заполнить объект Place отзывами, необходимо:

1. Включите новый SDK при настройке проекта Google Cloud .
2. Инициализируйте новый SDK внутри действия или фрагмента.
3. Включите Place.Field.REVIEWS в список полей запроса сведений о месте.
4. Вызовите PlacesClient.fetchPlace() . Поле отзывов не поддерживается PlacesClient.findCurrentPlace() .
5. Используйте метод Place.getReviews() для доступа к полю данных отзывов в объекте Place .

Доступ к коду языка названия места

Существующий метод Place.getName() возвращает текстовую строку, содержащую название места. Чтобы заполнить объект Place названием места, необходимо включить Place.Field.NAME в список полей запроса сведений о месте.

Объект Place теперь содержит код языка для строки имени. Чтобы заполнить объект Place кодом языка, необходимо:

1. Включите новый SDK при настройке проекта Google Cloud .
2. Инициализируйте новый SDK внутри действия или фрагмента.
3. Включите Place.Field.NAME в список полей запроса. Это значение настраивает ответ таким образом, чтобы он включал в объект Place как название места, так и код языка.
4. Вызовите PlacesClient.fetchPlace() . PlacesClient.findCurrentPlace() не поддерживает поле кода языка.
5. Используйте метод Place.getNameLanguageCode() для доступа к полю кода языка в объекте Place .

Установить код региона в версии 3.3.0

Places SDK для Android (новая версия) добавляет параметр запроса кода региона в сведения о месте. Код региона используется для форматирования ответа, указанного в виде двухсимвольного кода CLDR . Этот параметр также может оказывать влияние на результаты поиска. Нет значения по умолчанию. Вам необходимо включить новый SDK, чтобы установить код региона.

Если название страны в поле адреса в ответе соответствует коду региона, код страны в адресе опускается.

Большинство кодов CLDR идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, нДВУ Соединенного Королевства — «uk» (.co.uk), а его код ISO 3166-1 — «gb» (технически для субъекта «Соединенное Королевство Великобритании и Северной Ирландии»). Параметр может повлиять на результаты в соответствии с действующим законодательством.

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

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

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

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

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

Котлин

// 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")
        }
    }

      

Джава

// 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.
    }
});

      

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

Получить открытый статус

Метод 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 с необходимыми полями см. в разделе Детали места .

Примечание. За вызовы fetchPlace() для Place.Field.UTC_OFFSET и Place.Field.BUSINESS_STATUS взимается плата за SKU базовых данных Places. С SKU контактных данных мест взимается плата за вызовы fetchPlace() для Place.Field.CURRENT_OPENING_HOURS и Place.Field.OPENING_HOURS .

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

Котлин

val isOpenCalendar: Calendar = Calendar.getInstance()
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"

val request: IsOpenRequest = try {
    IsOpenRequest.newInstance(placeId, isOpenCalendar.timeInMillis)
} catch (e: IllegalArgumentException) {
    e.printStackTrace()
    return
}
val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(request)
isOpenTask.addOnSuccessListener { response ->
    val isOpen = response.isOpen
}
// ...

      

Джава

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
IsOpenRequest isOpenRequest;

try {
    isOpenRequest = IsOpenRequest.newInstance(placeId, isOpenCalendar.getTimeInMillis());
} catch (IllegalArgumentException e) {
    e.printStackTrace();
    return;
}

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

placeTask.addOnSuccessListener(
        (response) ->
                isOpen = response.isOpen());
// ...

      

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

Котлин

val isOpenCalendar: Calendar = Calendar.getInstance()
var place: Place
val placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk"
// 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.UTC_OFFSET
)

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) {
        e.printStackTrace()
        return@addOnSuccessListener
    }
    val isOpenTask: Task<IsOpenResponse> = placesClient.isOpen(isOpenRequest)
    isOpenTask.addOnSuccessListener { isOpenResponse ->
        val isOpen = isOpenResponse.isOpen
    }
    // ...
}
// ...

      

Джава

@NonNull
Calendar isOpenCalendar = Calendar.getInstance();
String placeId = "ChIJD3uTd9hx5kcR1IQvGfr8dbk";
// 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.UTC_OFFSET
));

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) {
                e.printStackTrace();
                return;
            }
            Task<IsOpenResponse> isOpenTask = placesClient.isOpen(isOpenRequest);

            isOpenTask.addOnSuccessListener(
                    (isOpenResponse) -> isOpen = isOpenResponse.isOpen());
            // ...
        });
// ...

      

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

Когда ваше приложение отображает информацию о месте, включая обзоры мест, оно также должно отображать любые сведения об авторстве. Для получения дополнительной информации см. Атрибуции .

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

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

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

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