Place Details

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

O SDK do Places para Android oferece ao seu aplicativo informações detalhadas sobre lugares, incluindo o nome e o endereço do lugar, a 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 de um lugar específico, você pode usar o ID de lugar, um identificador estável que identifica um local de forma exclusiva.

Detalhes do lugar

O objeto Place fornece informações sobre um lugar específico. É possível pegar um objeto Place das seguintes maneiras:

Ao solicitar um lugar, você precisa especificar quais tipos de dados retornar. Para fazer isso, transmita um List<Place.Field>, especificando os tipos de dados a serem retornados. Essa é uma consideração importante, já que isso afetará o custo de cada solicitação. Como os resultados de dados de lugar não podem ficar vazios, somente resultados de lugar com dados são retornados. Por exemplo, se um local solicitado não tiver fotos, o campo photos não estará presente no resultado. É possível especificar um ou mais dos seguintes campos:

  • Place.Field.ADDRESS
  • Place.Field.ADDRESS_COMPONENTS
  • Place.Field.BUSINESS_STATUS
  • Place.Field.ID
  • Place.Field.LAT_LNG
  • Place.Field.NAME
  • Place.Field.OPENING_HOURS
  • Place.Field.PHONE_NUMBER
  • Place.Field.PHOTO_METADATAS
  • Place.Field.PLUS_CODE
  • Place.Field.PRICE_LEVEL
  • Place.Field.RATING
  • Place.Field.TYPES
  • Place.Field.USER_RATINGS_TOTAL
  • Place.Field.ICON_URL
  • Place.Field.ICON_BACKGROUND_COLOR
  • Place.Field.VIEWPORT
  • Place.Field.UTC_OFFSET
  • Place.Field.WEBSITE_URI

Saiba mais sobre os campos de lugar. Para mais informações sobre como as solicitações de dados de lugar são faturadas, consulte Uso e faturamento.

Use os métodos a seguir para recuperar dados de um Place:

  • getAddress(): o endereço do lugar em um formato legível.
  • getAddressComponents(): uma 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, para 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.
  • getBusinessStatus(): o status operacional do lugar, se for uma empresa. Ele pode conter um dos seguintes valores: OPERATIONAL, CLOSED_TEMPORARILY, CLOSED PERMANENTLY.
  • getAttributions(): as atribuições que precisam ser mostradas ao usuário, se os dados do lugar forem usados.
  • 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(): a 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 o closeEvent será nulo.
  • getPhoneNumber(): o número de telefone do lugar.
  • getPhotoMetadatas(): os metadados associados a uma foto associada ao lugar, incluindo a imagem em bitmap.
  • getPlusCode(): a localização do PlusCode deste lugar.
  • getPriceLevel(): o nível de preço desse lugar, retornado como um número inteiro com valores que variam de 0 (mais barato) a 4 (mais caro).
  • getRating(): uma classificação agregada do lugar, retornada como um ponto flutuante com valores que variam de 1,0 a 5,0, com base nas avaliações agregadas de usuários.
  • getTypes(): uma lista de tipos de lugar que caracterizam esse lugar. Para ver uma lista de tipos de lugar disponíveis, consulte a documentação da interface Place.
  • getUserRatingsTotal(): o número total de avaliações de usuários do lugar.
  • getIconUrl(): o URL de uma máscara de ícone preto que representa o tipo de lugar.
  • getIconBackgroundColor: a cor de fundo do ícone para o tipo de lugar.
  • getUtcOffsetMinutes(): a diferença de UTC em minutos.
  • getViewport(): uma janela de visualização, retornada como um objeto LatLngBounds, útil para exibir o lugar em um mapa. Pode retornar nulo se o tamanho do lugar não for conhecido.
  • getWebsiteUri(): o URI do site do local, se conhecido. Esse é o site mantido pela empresa ou outra entidade associada ao lugar. Retorna null se nenhum site for conhecido.
  • isOpen(): um booleano indicando se o lugar está aberto. 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 o isOpen com 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

Um ID de local é um identificador 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 lugar 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 receber um lugar por ID, chame PlacesClient.fetchPlace(), enviando um FetchPlaceRequest.

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

O exemplo de código a seguir mostra a chamada de fetchPlace() para receber 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")
        }
    }

      

Exibir atribuições no seu aplicativo

Quando seu 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 lugar, mas um único local pode ter mais de um ID de lugar. Há outras circunstâncias que podem fazer com que um local receba um novo ID de lugar. Por exemplo, isso pode acontecer se uma empresa mudar de endereço.

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

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