El SDK de Places para Android proporciona a tu app información enriquecida sobre los lugares, incluidos el nombre y la dirección del lugar, la ubicación geográfica especificada como coordenadas de latitud y longitud, el tipo de lugar (como un club nocturno, una tienda de mascotas y un museo), entre otros. Para acceder a esta información de un lugar específico, puedes usar el ID de lugar, un identificador estable que identifica un lugar de forma exclusiva.
Detalles del lugar
El objeto Place
proporciona información sobre un lugar específico. Puedes obtener un objeto Place
de las siguientes maneras:
- Llamar a
PlacesClient.findCurrentPlace()
: Consulta la guía para obtener el lugar actual. - Llamar a
PlacesClient.fetchPlace()
: Consulta la guía para obtener un lugar por ID.
Cuando solicitas un lugar, debes especificar qué datos del lugar se deben mostrar. Para ello, pasa una lista de valores de Place.Field que especifique los datos que se mostrarán. Esta lista es una consideración importante porque afecta el costo de cada solicitud.
Debido a que los resultados de datos de lugar no pueden estar vacíos, solo se muestran resultados de lugares con datos (por ejemplo, si un lugar solicitado no tiene fotos, el campo photos
no estará presente en el resultado).
En el siguiente ejemplo, se pasa una lista de tres valores de Place.Field para especificar los datos que muestra una solicitud:
Java
// Specify the fields to return. final ListplaceFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);
Kotlin
// Specify the fields to return. val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)
Después de obtener el objeto Place
, usa los métodos del objeto para acceder a los campos de datos especificados en la solicitud. Si falta el campo en el objeto Place
,
el método relacionado muestra un valor nulo. A continuación, se muestran ejemplos de algunos de los métodos disponibles.
Para obtener una lista completa de todos los métodos, consulta la referencia de la API de Place
.
getAddress()
: Es la dirección del lugar, en un formato legible.getAddressComponents()
: Es unList
de componentes de dirección para este lugar. Estos componentes se proporcionan con el fin de extraer información estructurada sobre la dirección de un lugar, por ejemplo, encontrar la ciudad en la que se encuentra un lugar. No uses estos componentes para dar formato a las direcciones. En su lugar, llama agetAddress()
, que proporciona una dirección con formato localizada.getId()
: el identificador textual del lugar. Obtén más información sobre los IDs de lugar en el resto de esta página.getLatLng()
: Es la ubicación geográfica del lugar, especificada como coordenadas de latitud y longitud.getName()
: Es el nombre del lugar.getOpeningHours()
: Es elOpeningHours
del lugar. Llama aOpeningHours.getWeekdayText()
para que se muestre una lista de strings que representan los horarios de apertura y cierre de cada día de la semana. Llama aOpeningHours.getPeriods()
para mostrar una lista de objetosperiod
con información más detallada equivalente a los datos que proporcionagetWeekdayText()
.El objeto
Place
también contiene el métodogetCurrentOpeningHours()
, que muestra el horario de atención de un lugar durante los próximos siete días, ygetSecondaryOpeningHours()
, que muestra el horario de atención secundario de un lugar en los próximos siete días.isOpen()
: Es un valor booleano que indica si el lugar está abierto actualmente. Si no se especifica una hora, el valor predeterminado será ahora.isOpen
solo se mostrará siPlace.Field.UTC_OFFSET
yPlace.Field.OPENING_HOURS
están disponibles. Para garantizar resultados precisos, solicita los camposPlace.Field.BUSINESS_STATUS
yPlace.Field.UTC_OFFSET
en tu solicitud de lugar original. Si no se solicita, se supone que la empresa está operativa. Consulta este video para obtener información sobre cómo usarisOpen
con Place Details.
Algunos ejemplos simples:
Java
final CharSequence name = place.getName(); final CharSequence address = place.getAddress(); final LatLng location = place.getLatLng();
Kotlin
val name = place.name val address = place.address val location = place.latLng
Obtener un sitio por id.
Un ID de lugar es un identificador textual que identifica de forma exclusiva un lugar. En el SDK de Places para Android, puedes llamar a Place.getId()
para recuperar el ID de un lugar.
El servicio Place Autocomplete también muestra un ID de lugar para cada lugar que coincide con el filtro y la búsqueda que se proporcionaron. Puedes almacenar el ID de lugar y usarlo para recuperar el objeto Place
más tarde.
Para obtener un lugar por ID, llama a PlacesClient.fetchPlace()
y pasa un objeto FetchPlaceRequest
.
La API muestra un FetchPlaceResponse
en un Task
.
El objeto FetchPlaceResponse
contiene un objeto Place
que coincide con el ID de lugar proporcionado.
En el siguiente ejemplo de código, se muestra cómo llamar a fetchPlace()
para obtener detalles del lugar especificado.
Java
// 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. } });
Kotlin
// 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") } }
Obtener estado abierto
El método PlacesClient.isOpen(IsOpenRequest request)
muestra un objeto IsOpenResponse
que indica si el lugar está abierto en ese momento en función del horario especificado en la llamada.
Este método toma un solo argumento del tipo IsOpenRequest
que contiene lo siguiente:
- Un objeto
Place
o una string que especifica un ID de lugar. - Un valor de tiempo opcional que especifica la hora en milisegundos desde 1970-01-01T00:00:00Z. Si no se especifica una hora, el valor predeterminado será ahora.
Este método requiere que existan los siguientes campos en el objeto Place
:
Place.Field.BUSINESS_STATUS
Place.Field.CURRENT_OPENING_HOURS
Place.Field.OPENING_HOURS
Place.Field.UTC_OFFSET
Si estos campos no se proporcionan en el objeto Place
, o si pasas un ID de lugar, el método usa PlacesClient.fetchPlace()
para recuperarlos. Para obtener más información sobre cómo crear un objeto Place con los campos necesarios, consulta Detalles del lugar.
En el siguiente ejemplo, se determina si un lugar está abierto actualmente. En este ejemplo, solo pasas el ID de lugar a isOpen()
:
Java
@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()); // ...
Kotlin
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 } // ...
En el siguiente ejemplo, se muestra cómo llamar a isOpen()
, en el que pasas un objeto Place
.
El objeto Place
debe contener un ID de lugar válido:
Java
@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()); // ... }); // ...
Kotlin
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 } // ... } // ...
Mostrar atribuciones en tu aplicación
Cuando tu app muestra información de lugares, también debe mostrar las atribuciones. Consulta la documentación sobre las atribuciones.
Más información sobre los id. de sitio
El ID de lugar que se usa en el SDK de Places para Android es el mismo que se usa en la API de Places. Cada ID de lugar puede hacer referencia a un solo lugar, pero un lugar puede tener más de un ID de lugar. Existen otras circunstancias que pueden hacer que un lugar obtenga un nuevo ID de lugar. Por ejemplo, esto puede suceder si una empresa se muda a otro lugar.
Cuando solicitas un lugar mediante la especificación de un ID de lugar, puedes estar seguro de que siempre recibirás el mismo lugar en la respuesta (si el lugar aún existe). Sin embargo, ten en cuenta que la respuesta puede contener un ID de lugar diferente del que aparece en tu solicitud.
Para obtener más información, consulta la descripción general del ID de lugar.