Сведения о месте (устаревшая версия)

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

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

Подробности о месте

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

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

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

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

Котлин 

// 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 , соответствующий метод возвращает null. Ниже приведены примеры некоторых доступных методов.

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

Получите место по удостоверению личности.

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

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

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

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

Котлин 

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

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

Котлин 

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 должен содержать действительный идентификатор места:

Котлин 

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

Отображайте атрибуцию в своем приложении

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

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

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

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

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