Place Details (Legacy)

Desenvolvedores do Espaço Econômico Europeu (EEE)

Se o endereço de faturamento estiver no Espaço Econômico Europeu, a partir de 8 de julho de 2025, os Termos de Serviço da Plataforma Google Maps para o EEE vão valer para o uso dos serviços. A funcionalidade varia de acordo com a região. Saiba mais.

Este produto está no status legado. A partir de outubro de 2026, a API Places (legada) não poderá mais ser ativada para novos projetos do Google Cloud. Os projetos atuais continuam totalmente compatíveis. Para novos recursos e melhor desempenho, migre para a API Places (nova).

O SDK do Places para Android (legado) fornece ao seu app informações detalhadas sobre lugares, incluindo nome, endereço, localização geográfica especificada como coordenadas de latitude/longitude, tipo de lugar (como boate, pet shop, museu) e muito mais. Para acessar essas informações de um lugar específico, use o ID de lugar, um identificador estável que identifica um lugar de forma exclusiva.

Detalhes do lugar

O objeto Place fornece informações sobre um lugar específico. Para acessar um objeto Place, chame PlacesClient.fetchPlace(). Consulte o guia sobre como encontrar um lugar por ID.

Ao solicitar um lugar, você precisa especificar quais dados retornar. Para fazer isso, transmita uma lista de valores de Place.Field especificando os dados a serem retornados. Essa lista é uma consideração importante porque afeta o custo de cada solicitação.

Como os resultados de dados de lugar não podem ficar vazios, apenas aqueles que têm dados são retornados. Por exemplo, se um lugar solicitado não tiver fotos, o campo photos não estará presente no resultado.

O exemplo a seguir transmite uma lista de três valores Place.Field para especificar os dados retornados por uma solicitação:

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

Acessar campos de dados do objeto Place

Depois de receber o objeto Place, use os métodos dele para acessar os campos de dados especificados na solicitação. Se o campo estiver ausente do objeto Place, o método relacionado vai retornar nulo. Confira abaixo exemplos de alguns dos métodos disponíveis.

Para uma lista completa de todos os métodos, consulte a referência da API Place.

• getAddress(): o endereço do lugar em um formato legível por humanos.
• getAddressComponents(): um List de componentes de endereço para esse lugar. Esses componentes são fornecidos para extrair informações estruturadas sobre o endereço de um lugar, por exemplo, encontrar a cidade em que um lugar está localizado. Não use esses componentes para formatação de endereço. Em vez disso, chame getAddress(), que fornece um endereço formatado localizado.
• getId(): o identificador textual do lugar. Leia mais sobre IDs de lugar no restante desta página.
• getLatLng(): a localização geográfica do lugar, especificada como coordenadas de latitude e longitude.
• getName(): o nome do local.

• getOpeningHours(): o OpeningHours do lugar. Chame OpeningHours.getWeekdayText() para retornar uma lista de strings que representam os horários de abertura e fechamento de cada dia da semana. Chame OpeningHours.getPeriods() para retornar uma lista de objetos period com informações mais detalhadas que sejam equivalentes aos dados fornecidos por getWeekdayText().

  Observação : se um lugar estiver sempre aberto, o período será representado como domingo à meia-noite, e closeEvent será nulo.

  O objeto Place também contém o método getCurrentOpeningHours(), que retorna o horário de funcionamento de um lugar nos próximos sete dias, e getSecondaryOpeningHours(), que retorna o horário de funcionamento secundário de um lugar nos próximos sete dias.

• isOpen(): um booleano que indica se o lugar está aberto no momento. Se nenhum horário for especificado, o padrão será o momento atual. isOpen só será retornado se Place.Field.UTC_OFFSET e Place.Field.OPENING_HOURS estiverem disponíveis. Para garantir resultados precisos, solicite os campos Place.Field.BUSINESS_STATUS e Place.Field.UTC_OFFSET na sua solicitação de lugar original. Se não for solicitado, consideramos que a empresa está em funcionamento. Assista a este vídeo para saber como usar isOpen com o Place Details.

  Observação : esse método foi descontinuado. Em vez disso, use PlacesClient.isOpen(IsOpenRequest request). Para mais informações, consulte Receber status de abertura.

Alguns exemplos:

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

      

Obter local por ID

O ID de lugar é um indicador textual que identifica um local de forma exclusiva. No SDK do Places para Android, é possível recuperar o ID de um lugar chamando Place.getId(). O serviço Place Autocomplete também retorna um ID de lugar para cada local que corresponde à consulta de pesquisa e ao filtro fornecidos. Você pode armazenar o ID de lugar e usá-lo para recuperar o objeto Place novamente mais tarde.

Para encontrar um lugar por ID, chame PlacesClient.fetchPlace(), transmitindo um FetchPlaceRequest.

A API retorna um FetchPlaceResponse em um Task. O FetchPlaceResponse contém um objeto Place que corresponde ao ID de lugar fornecido.

O exemplo de código a seguir mostra como chamar fetchPlace() para receber detalhes do 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.
                    }
                });

      

Observação: para mais informações sobre como inicializar PlacesClient, consulte Inicializar o cliente da API Places.

É possível usar um CancellationToken para tentar cancelar uma solicitação para qualquer uma das classes de solicitação (por exemplo, FetchPlaceRequest). O cancelamento é feito da melhor maneira possível. Depois que uma solicitação de cancelamento é emitida, nenhuma resposta é retornada. A emissão de um token de cancelamento NÃO garante que uma solicitação específica será cancelada, e você ainda poderá ser cobrado pela solicitação, mesmo que nenhuma resposta seja retornada.

Ver status de abertura

O método PlacesClient.isOpen(IsOpenRequest request) retorna um objeto IsOpenResponse que indica se o lugar está aberto no momento com base no horário especificado na chamada.

Esse método usa um único argumento do tipo IsOpenRequest que contém:

• Um objeto Place ou uma string que especifica um ID de lugar.
  Observação : o objeto Place precisa conter um ID de lugar válido.
• Um valor de tempo opcional que especifica o tempo em milissegundos a partir de 1970-01-01T00:00:00Z. Se nenhum horário for especificado, o padrão será o momento atual.

Esse método exige que os seguintes campos existam no objeto Place:

• Place.Field.BUSINESS_STATUS
• Place.Field.CURRENT_OPENING_HOURS
• Place.Field.OPENING_HOURS
• Place.Field.UTC_OFFSET

Se esses campos não forem fornecidos no objeto Place ou se você transmitir um ID de lugar, o método vai usar PlacesClient.fetchPlace() para buscá-los. Para mais informações sobre como criar o objeto Place com os campos necessários, consulte Place Details.

Observação : a SKU Basic Data do Places é cobrada por chamadas para fetchPlace() para Place.Field.UTC_OFFSET e Place.Field.BUSINESS_STATUS. A SKU de dados de contato do Places é cobrada por chamadas para fetchPlace() para Place.Field.CURRENT_OPENING_HOURS e Place.Field.OPENING_HOURS.

O exemplo a seguir determina se um lugar está aberto no momento. Neste exemplo, você só transmite o ID de lugar para 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());
        });

      

O próximo exemplo mostra como chamar isOpen() transmitindo um objeto Place. O objeto Place precisa conter um 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());

      

Exibir atribuições no seu aplicativo

Quando o app mostra informações de lugares, incluindo avaliações, ele também precisa exibir as atribuições. Para mais informações, consulte atribuições.

Mais informações sobre IDs de local

O ID de lugar usado no SDK do Places para Android (legado) é o mesmo identificador usado na API Places (legada). Cada ID de lugar pode se referir a apenas um lugar, mas um único lugar pode ter mais de um ID. Há outras circunstâncias que podem fazer com que um lugar receba um novo ID de lugar. Por exemplo, isso pode acontecer se uma empresa se mudar para um novo local.

Ao solicitar um lugar especificando um ID de lugar, você sempre vai receber o mesmo lugar na resposta (se ele ainda existir). No entanto, a resposta pode conter um ID de lugar diferente daquele na sua solicitação.

Para mais informações, consulte a visão geral do ID de lugar.