Place Details

Selecione a plataforma: Android iOS JavaScript Serviço da Web

O SDK do Places para Android oferece ao seu app informações detalhadas sobre lugares, incluindo nome e endereço, localização geográfica especificada como coordenadas de latitude/longitude, o tipo de lugar (como casa noturna, pet shop, museu) e muito mais. Para acessar essas informações em um lugar específico, use o ID do 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. É possível receber um objeto Place das seguintes maneiras:

• Chame PlacesClient.findCurrentPlace(). Consulte o guia sobre como ver o lugar atual.
• Chame PlacesClient.fetchPlace(). Consulte o guia sobre como ver um lugar por ID.

Ao solicitar um lugar, você precisa especificar quais dados retornar. Para fazer isso, transmita uma lista de valores Place.Field que especificam 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 estar vazios, apenas resultados com 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 de Place.Field para especificar os dados retornados por uma solicitação:

Java

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

Kotlin

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

Observação: findCurrentPlace() e fetchPlace() são compatíveis com diferentes conjuntos de campos. findCurrentPlace() NÃO oferece suporte aos seguintes campos: Place.Field.ADDRESS_COMPONENTS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.TAKEOUT, Place.Field.UTC_OFFSET e Place.Field.WEBSITE_URI.

Depois de receber o objeto Place, use os métodos do objeto para recuperar os dados do lugar. Veja abaixo exemplos de alguns dos métodos disponíveis. Para ver uma lista completa de todos os métodos, consulte a referência da API Place.

• getAddress(): o endereço do lugar, em formato legível.
• getAddressComponents(): um List de componentes de endereço para este lugar. Esses componentes são usados com a finalidade de 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 formatar o 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 lugar.
• 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.
• isOpen(): um booleano que indica se o lugar está aberto no momento. Se nenhum tempo for especificado, o padrão será agora. 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 solicitação de lugar original. Se não for solicitado, presume-se que a empresa está funcionando. Veja este vídeo para saber como usar isOpen com o Place Details.

Alguns exemplos simples:

Java

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

      

Kotlin

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

      

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 correspondente à 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 ver um lugar por ID, chame PlacesClient.fetchPlace(), transmitindo um FetchPlaceRequest.

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

O exemplo de código a seguir mostra como chamar fetchPlace() para ver detalhes do lugar especificado.

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

      

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

      

Use um CancellationToken para tentar cancelar uma solicitação em qualquer uma das classes de solicitação (por exemplo, FetchPlaceRequest). O cancelamento é feito na medida do possível. Quando o pedido de cancelamento for emitido, nenhuma resposta será 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 por ela, mesmo que nenhuma resposta seja retornada.

Exibir atribuições no seu aplicativo

Quando o app exibe informações de lugar, ele também precisa exibir atribuições. Consulte a documentação sobre atribuições.

Mais informações sobre IDs de local

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

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

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