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

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

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

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

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

Когда вы запрашиваете место, вы должны указать, какие данные места нужно вернуть. Для этого передайте список значений 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)

После получения объекта 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 со сведениями о месте.

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

Джава


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

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

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

В следующем примере определяется, открыто ли место в данный момент. В этом примере вы передаете только идентификатор места в 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());
// ...

Котлин


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

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

Джава


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

Котлин


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

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

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

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

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

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

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