Place Details (heredado)

Desarrolladores del Espacio Económico Europeo (EEE)

Si tu dirección de facturación se encuentra en el Espacio Económico Europeo, a partir del 8 de julio de 2025, se aplicarán las Condiciones del Servicio de Google Maps Platform para el EEE al uso que hagas de los Servicios. La funcionalidad varía según la región. Obtén más información.

Este producto se encuentra en estado heredado. A partir de octubre de 2026, ya no se podrá habilitar la API de Places (heredada) para los proyectos nuevos de Google Cloud. Los proyectos existentes siguen siendo totalmente compatibles. Para obtener funciones nuevas y un mejor rendimiento, migra a la API de Places (nueva).

El SDK de Places para Android (heredado) 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 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 un lugar de forma inequívoca.

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, ya que afecta el costo de cada solicitud.

Debido a que los resultados de datos de lugar no pueden estar vacíos, solo se mostrarán 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 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);
  

Cómo acceder 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 devuelve 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 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. No uses estos componentes para aplicar formato a la dirección. En su lugar, llama a getAddress(), que proporciona una dirección con formato localizado.
• 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 obtener una lista de cadenas que representen los horarios de atención para cada día de la semana. Llama a OpeningHours.getPeriods() para que se devuelva una lista de objetos period con información más detallada que sea equivalente a los datos que proporciona getWeekdayText().

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

  El objeto Place también contiene el método getCurrentOpeningHours(), que devuelve el horario de atención de un lugar durante los próximos siete días, y getSecondaryOpeningHours(), que devuelve 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 ese momento. Si no se especifica una hora, el valor predeterminado es ahora. isOpen solo se devolverá si Place.Field.UTC_OFFSET y Place.Field.OPENING_HOURS están disponibles. Para garantizar que los resultados sean 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.

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

Estos son algunos ejemplos:

Kotlin

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

      

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 de Place Autocomplete también devuelve 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 nuevamente 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 = 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.
                    }
                });

      

Nota: Para obtener más información sobre cómo inicializar PlacesClient, consulta Inicializa el cliente de la API de Places.

Puedes usar un CancellationToken para intentar cancelar una solicitud a cualquiera de las clases de solicitud (por ejemplo, FetchPlaceRequest). La cancelación se realiza de la mejor manera posible. Una vez que se emita una solicitud de cancelación, no se devolverá ninguna respuesta. Emitir un token de cancelación NO garantiza que se cancelará una solicitud específica, y es posible que se te cobre por la solicitud, incluso si no se devuelve ninguna respuesta.

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 ese momento según la hora especificada en la llamada.

Este método toma un solo argumento del 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.
• Es 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 es ahora.

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 Place Details.

Nota: El SKU de Basic Data de Places se cobra por las llamadas a fetchPlace() para Place.Field.UTC_OFFSET y Place.Field.BUSINESS_STATUS. El SKU de Contact Data de Places se cobra 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 en ese momento. En este ejemplo, solo pasas el ID de lugar a isOpen():

Kotlin

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

      

En el siguiente ejemplo, se muestra cómo llamar a isOpen() pasando 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 = 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());

      

Mostrar atribuciones en tu aplicación

Cuando tu app muestre información de un lugar, incluidas las opiniones, también debe 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 (heredado) es el mismo identificador que se usa en la API de Places (heredada). 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 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 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.