Place Details

Selecciona la plataforma: Android iOS JavaScript Servicio web

El SDK de Places para Android le 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, 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 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.fetchPlace(): Consulta la guía para obtener un lugar por ID.
• Llamar a PlacesClient.findCurrentPlace(): Consulta la guía para obtener el lugar actual.
  Si bien PlacesClient.fetchPlace() admite todos los campos de datos de lugar, PlacesClient.findCurrentPlace() solo admite un subconjunto de campos de datos de lugar. Para obtener la lista de campos que NO admite findCurrentPlace(), consulta Compatibilidad con campos del SDK de Places para Android.

Cuando solicitas un lugar, debes especificar qué datos del lugar se deben devolver. 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.

Como 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 aparecerá en el resultado).

En el siguiente ejemplo, se pasa una lista de tres valores 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 placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Nota: El SDK de Places para Android y el SDK de Places para Android (nuevo) admiten diferentes modelos de precios. Esto significa que el precio de una llamada se basa en los campos que solicites y la versión del SDK que uses. Para obtener información detallada sobre los precios de ambos SDK, consulta Uso y facturación.

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. 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 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, para encontrar la ciudad en la que se encuentra un lugar. No los uses 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 representen los horarios de apertura y cierre para 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 proporcionados por getWeekdayText().

  Nota: Si un lugar está siempre abierto, el período se representa como domingo a medianoche y el closeEvent es nulo.

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

• isOpen(): Es un valor booleano que indica si el lugar está abierto en ese momento. Si no se especifica la hora, el valor predeterminado es ahora. 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 la solicitud de lugar original. Si no se solicitan, se asume que la empresa está operativa. Consulta este video para obtener información sobre cómo usar isOpen con Place Details.

  Nota: Este método dejó de estar disponible. En su lugar, usa PlacesClient.isOpen(IsOpenRequest request). Para obtener más información, consulta Cómo obtener el estado de apertura.

Algunos ejemplos simples:

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

      

Accede a datos de Places agregados en la versión 3.3.0

La versión 3.3.0 del SDK de Places para Android agrega datos nuevos a Place:

• Tipos de lugares: Son los valores de tipo nuevos asociados con un lugar.
• Opiniones: Se admiten hasta cinco opiniones de un lugar.
• Código de idioma del nombre: Es el código de idioma del nombre de un lugar.

En las siguientes secciones, se describe cómo acceder a estos datos nuevos.

Nota: El nuevo SDK solo admite los nuevos datos de Place en Java.

Accede a nuevos tipos de lugares

Cada lugar puede tener uno o más valores de tipo asociados. El SDK de Places para Android versión 3.3.0 agrega muchos tipos de valores nuevos. Para obtener la lista completa, consulta Tipos de lugares expandidos.

En la versión 3.2.0 y anteriores del SDK de Places para Android, usabas el método Place.getTypes() para acceder a los valores de tipo asociados con un lugar. Place.getTypes() muestra una lista de tipos como valores de enumeración definidos por Place.Types.

El método Place.getTypes() dejó de estar obsoleto a partir de la versión 3.3.0 del SDK de Places para Android. Si bien puedes seguir usándolo durante el período de baja, debes migrar tus apps para que usen Place.getPlaceTypes().

El método Place.getPlaceTypes() muestra los valores de tipo como una lista de valores de cadena. Los valores que se muestran dependen de tu versión del SDK de Places para Android:

• SDK de Places para Android (nuevo): Muestra las cadenas definidas en las Tablas A y B que aparecen en Tipos de lugares (Nuevo), incluidos todos los tipos de lugares agregados en la versión 3.3.0.
• SDK de Places para Android: Muestra las enumeraciones definidas por Place.Types, que no incluyen los tipos nuevos que se agregaron en la versión 3.3.0.

Para conocer las diferencias clave entre las dos versiones del SDK, consulta Elige tu versión del SDK.

Accede a las opiniones de lugares

El SDK de Places para Android (nuevo) agrega la clase Review, que contiene una opinión de un lugar. El objeto Place puede contener hasta cinco opiniones.

La clase Review también puede contener una atribución y una atribución de autor. Si muestras la opinión en tu app, también debes mostrar cualquier atribución o del autor. Para obtener más información, consulta Muestra una opinión.

Para propagar el objeto Place con opiniones, debes hacer lo siguiente:

1. Habilita el SDK nuevo cuando configures tu proyecto de Google Cloud.
2. Inicializa el SDK nuevo dentro de una actividad o un fragmento.
3. Incluye Place.Field.REVIEWS en la lista de campos de la solicitud de detalles del lugar.
4. Llama a PlacesClient.fetchPlace(). El campo de opiniones no es compatible con PlacesClient.findCurrentPlace().
5. Usa el método Place.getReviews() para acceder al campo de datos de las opiniones en el objeto Place.

Accede al código de idioma del nombre del lugar

El método Place.getName() existente muestra una cadena de texto que contiene el nombre de un lugar. Para propagar el objeto Place con el nombre del lugar, debes incluir Place.Field.NAME en la lista de campos de la solicitud de detalles del lugar.

El objeto Place ahora contiene el código de idioma de la string de nombre. Para propagar el objeto Place con el código de idioma, debes hacer lo siguiente:

1. Habilita el SDK nuevo cuando configures tu proyecto de Google Cloud.
2. Inicializa el SDK nuevo dentro de una actividad o un fragmento.
3. Incluye el Place.Field.NAME en la lista de campos de la solicitud. Este valor configura la respuesta para que incluya el nombre del lugar y el código de idioma en el objeto Place.
4. Llama a PlacesClient.fetchPlace(). PlacesClient.findCurrentPlace() no admite el campo del código de idioma.
5. Usa el método Place.getNameLanguageCode() para acceder al campo del código de idioma en el objeto Place.

Establece el código de región en la versión 3.3.0

El SDK de Places para Android (nuevo) agrega el parámetro de solicitud del código regional a Place Details. El código regional se usa para dar formato a la respuesta, especificado como un valor de código CLDR de dos caracteres. Este parámetro también puede tener un efecto de personalización en los resultados de la búsqueda. No hay un valor predeterminado. Debes habilitar el SDK nuevo para configurar el código de región.

Si el nombre del país del campo de dirección en la respuesta coincide con el código de región, este se omite de la dirección.

La mayoría de los códigos CLDR son idénticos a los códigos ISO 3166-1, con algunas excepciones notables. Por ejemplo, el ccTLD del Reino Unido es "uk" (.co.uk), mientras que su código ISO 3166-1 es "gb" (técnicamente para la entidad de "Reino Unido de Gran Bretaña e Irlanda del Norte"). El parámetro puede afectar los resultados según la ley aplicable.

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 muestra un ID de lugar para cada lugar que coincida con la búsqueda y el filtro proporcionados. 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 FetchPlaceRequest.

La API muestra un FetchPlaceResponse en un Task. El campo 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.
    }
});

      

Puedes usar un CancellationToken para intentar cancelar una solicitud a cualquiera de las clases de solicitudes (por ejemplo, FetchPlaceRequest). La cancelación se realiza según el criterio del mejor esfuerzo. Una vez que se emite una solicitud de cancelación, no se mostrará ninguna respuesta. Emitir un token de cancelación NO garantiza la cancelación de una solicitud en particular y es posible que se te cobre por la solicitud incluso si no se muestra ninguna respuesta.

Obtener estado abierto

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

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

• Es un objeto Place o una cadena que especifica un ID de lugar.
  Nota: El objeto Place debe contener un ID de lugar válido.
• Un valor de tiempo opcional que especifica el tiempo en milisegundos desde 1970-01-01T00:00:00Z. Si no se especifica la hora, el valor predeterminado es 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 el objeto de lugar con los campos necesarios, consulta Detalles de lugar.

Nota: Se cobra el SKU de Basic Data de Places por las llamadas a fetchPlace() para Place.Field.UTC_OFFSET y Place.Field.BUSINESS_STATUS. Se cobra el SKU de Contact Data de Places por las llamadas a fetchPlace() para Place.Field.CURRENT_OPENING_HOURS y Place.Field.OPENING_HOURS.

En el siguiente ejemplo se determina si un lugar está abierto actualmente. En este ejemplo, solo se pasa 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(), 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 del lugar, incluidas las opiniones sobre estos, 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 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 provocar que un sitio obtenga un ID de lugar nuevo. Por ejemplo, esto puede suceder si una empresa se muda a una nueva ubicación.

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 diferente del que aparece en tu solicitud.

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