Place Details

Desarrolladores del Espacio Económico Europeo (EEE)

El SDK de Places para Android proporciona a tu app información enriquecida sobre 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 club nocturno, tienda de mascotas, museo) y mucho más. Para acceder a esta información de un lugar específico, puedes usar el ID de lugar, un identificador estable que identifica de forma única un lugar.

Detalles del lugar

El objeto Place proporciona información sobre un lugar específico. Puedes obtener un objeto Place llamando 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 devolver. Para ello, pasa una lista de valores de Place.Field que especifiquen los datos que se devolverá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 devuelve una solicitud:

Kotlin

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

Accede a los campos de datos del objeto Place

Después de obtener el objeto Place, usa sus métodos para acceder a los campos de datos especificados en la solicitud. Si falta el campo en el objeto Place, el método relacionado devuelve un valor nulo. A continuación, se muestran ejemplos de algunos de los métodos disponibles.

  • getAddress(): Dirección del lugar en formato legible.
  • getAddressComponents(): Es un List de componentes de dirección para este lugar. Estos componentes se proporcionan con el propósito de extraer información estructurada sobre la dirección de un lugar, por ejemplo, para encontrar la ciudad en la que se encuentra un lugar. No uses estos componentes para dar formato a la dirección. En su lugar, llama a getAddress(), que proporciona una dirección con formato localizada.
  • getId(): Es 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 el OpeningHours del lugar. Llama a OpeningHours.getWeekdayText() para devolver una lista de cadenas que representan los horarios de apertura y cierre de cada día de la semana. Llama a OpeningHours.getPeriods() para devolver una lista de objetos period con información más detallada que es equivalente a los datos proporcionados por getWeekdayText().

    El objeto Place también contiene el método getCurrentOpeningHours(), que muestra el horario de atención de un lugar durante los próximos siete días, y getSecondaryOpeningHours(), que muestra el horario de atención secundario de un lugar durante los próximos siete días.

  • isOpen(): Es un valor booleano que indica si el lugar está abierto en este momento. Si no se especifica una hora, se usará la hora actual de forma predeterminada. isOpen solo se devolverá si están disponibles Place.Field.UTC_OFFSET y Place.Field.OPENING_HOURS. Para garantizar resultados precisos, solicita los campos Place.Field.BUSINESS_STATUS y Place.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 usar isOpen con Place Details.

Estos son algunos ejemplos:

Kotlin

val name = place.name
val address = place.address
val location = place.latLng

Java

final CharSequence name = place.getName();
final CharSequence address = place.getAddress();
final LatLng location = place.getLatLng();

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 recuperar el ID de un lugar llamando a Place.getId(). El servicio Place Autocomplete también devuelve un ID de lugar para cada lugar que coincide con la búsqueda y el filtro proporcionados. Puedes almacenar el ID de lugar y usarlo para recuperar el objeto Place más adelante.

Para obtener un lugar por ID, llama a PlacesClient.fetchPlace() y pasa un FetchPlaceRequest.

La API devuelve un objeto FetchPlaceResponse en un objeto 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.

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

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

Obtén el estado de apertura

El método PlacesClient.isOpen(IsOpenRequest request) devuelve un objeto IsOpenResponse que indica si el lugar está abierto en el momento actual según la hora especificada en la llamada.

Este método toma un solo argumento de tipo IsOpenRequest que contiene lo siguiente:

  • Un objeto Place o una cadena que especifica un ID de lugar.
  • Es un valor de tiempo opcional que especifica el tiempo en milisegundos desde el 1970-01-01T00:00:00Z. Si no se especifica una hora, se usará la hora actual de forma predeterminada.

Este método requiere que los siguientes campos existan 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 el objeto Place con los campos necesarios, consulta Detalles del lugar.

En el siguiente ejemplo, se determina si un lugar está abierto en este momento. En este ejemplo, solo pasas el ID de lugar a 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
}
// ...

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

En el siguiente ejemplo, se muestra cómo llamar a isOpen() cuando pasas un objeto Place. El objeto Place debe contener un ID de lugar válido:

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

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

Mostrar atribuciones en tu aplicación

Cuando tu app muestre información de lugares, incluidas las opiniones sobre lugares, también deberá mostrar las atribuciones correspondientes. Para obtener más información, consulta 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 identificador 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. Hay 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 una ubicación nueva.

Cuando solicitas un lugar especificando un ID de lugar, puedes tener la certeza 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 se incluye en tu solicitud.

Para obtener más información, consulta la descripción general de los IDs de lugar.