Place Details

Selecciona la plataforma: Android iOS JavaScript Servicio web

El SDK de Places para Android proporciona a tu app información enriquecida sobre los lugares, incluido el nombre y la dirección, la ubicación geográfica especificada como coordenadas de latitud y longitud, el tipo de lugar (como un club nocturno, una tienda de mascotas o un 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 exclusiva un lugar.

Detalles del lugar

El objeto Place proporciona información sobre un lugar específico. Puedes obtener un objeto Place de las siguientes maneras:

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 mostrarán. Esta lista es una consideración importante, ya que afecta el costo de cada solicitud.

Como los resultados de los datos de lugares no pueden estar vacíos, solo se muestran los 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:

Kotlin

// Specify the fields to return.
val placeFields = listOf(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS)

Java

// Specify the fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Accede a los campos de datos del objeto Place

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.

  • getAddress(): Es la dirección del lugar, en formato legible por humanos.
  • getAddressComponents(): Es un List 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 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 mostrar una lista de cadenas que representan los horarios de apertura y cierre de cada día de la semana. Llama a OpeningHours.getPeriods() para mostrar una lista de objetos period con información más detallada que sea equivalente a los datos que proporciona getWeekdayText().

    El objeto Place también contiene el método getCurrentOpeningHours(), que muestra las horas de funcionamiento de un lugar durante los próximos siete días, y getSecondaryOpeningHours(), que muestra las horas de funcionamiento secundarias 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 la hora, el valor predeterminado es la hora actual. isOpen solo se mostrará si Place.Field.UTC_OFFSET y Place.Field.OPENING_HOURS están disponibles. 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á en funcionamiento. 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 de Place Autocomplete también muestra un ID de lugar para cada lugar que coincida con la búsqueda y el filtro proporcionados. También, 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 muestra un FetchPlaceResponse en un Task. 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.
    }
});

Cómo obtener el estado de abierto

El método PlacesClient.isOpen(IsOpenRequest request) muestra un objeto IsOpenResponse que indica si el lugar está abierto en función de 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 especifique un ID de lugar
  • Es un valor de hora opcional que especifica la hora en milisegundos a partir del 1 de enero de 1970 a las 00:00:00 Z. Si no se especifica la hora, el valor predeterminado es la hora actual.

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 no se proporcionan estos campos 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 de Place.

En el siguiente ejemplo, se determina si un lugar está abierto actualmente. En este ejemplo, solo pasas el ID del 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(), en la que 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 muestra información de lugares, incluidas las opiniones sobre ellos, también debe mostrar las atribuciones. 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 ID de lugar nuevo. Por ejemplo, esto puede suceder si una empresa se traslada a una ubicación nueva.

Cuando solicitas un lugar especificando 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 que sea diferente del que aparece en tu solicitud.

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