O SDK do Places para Android oferece ao seu app mais informações sobre lugares, incluindo nome e endereço, localização geográfica especificada como coordenadas de latitude/longitude, tipo de lugar (como casa noturna, pet shop, museu) e muito mais. Para acessar essas informações de um local 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 conseguir 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 conseguir um lugar por ID.
Ao solicitar um local, especifique 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 aqueles que contêm dados são retornados. Por exemplo, se um local 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 ListplaceFields = 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)
Depois de receber o objeto Place
, use os métodos do objeto para acessar os campos de dados especificados na solicitação. Se o campo estiver ausente do objeto Place
, o método relacionado retornará nulo. 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()
: umList
de componentes de endereço para esse lugar. Esses componentes são fornecidos 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, chamegetAddress()
, 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()
: oOpeningHours
do lugar. ChameOpeningHours.getWeekdayText()
para retornar uma lista de strings que representam os horários de abertura e fechamento para cada dia da semana. ChameOpeningHours.getPeriods()
para retornar uma lista de objetosperiod
com informações mais detalhadas que sejam equivalentes aos dados fornecidos porgetWeekdayText()
.O objeto
Place
também contém o métodogetCurrentOpeningHours()
, que retorna o horário de funcionamento de um lugar nos próximos sete dias egetSecondaryOpeningHours()
, que retorna o horário de funcionamento secundário de um local nos próximos sete dias.isOpen()
: um booleano que indica se o lugar está aberto. Se nenhum tempo for especificado, o padrão será agora.isOpen
só será retornado sePlace.Field.UTC_OFFSET
ePlace.Field.OPENING_HOURS
estiverem disponíveis. Para garantir resultados precisos, solicite os camposPlace.Field.BUSINESS_STATUS
ePlace.Field.UTC_OFFSET
na sua solicitação de lugar original. Se não for solicitado, será considerado que a empresa está funcionando. Veja este vídeo para saber como usar oisOpen
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 e ao filtro de pesquisa fornecidos. Você pode armazenar o ID de lugar e usá-lo para recuperar o objeto Place
novamente mais tarde.
Para ver um local por ID, chame PlacesClient.fetchPlace()
, transmitindo 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 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") } }
Ver status aberto
O método PlacesClient.isOpen(IsOpenRequest request)
retorna um objeto IsOpenResponse
indicando 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. - Um valor de tempo opcional que especifica o tempo em milissegundos de 1970-01-01T00:00:00Z. Se nenhum tempo for especificado, o padrão será agora.
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 usará PlacesClient.fetchPlace()
para buscá-los. Para mais informações sobre como criar o objeto do Place com os campos necessários, consulte Detalhes do lugar.
O exemplo a seguir determina se um lugar está aberto. Neste exemplo, você só transmite o ID de lugar para 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()); // ...
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 } // ...
O próximo exemplo mostra a chamada de isOpen()
em que você transmite um objeto Place
.
O objeto Place
precisa conter um ID de lugar válido:
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()); // ... }); // ...
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 } // ... } // ...
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 local pode referir-se 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 se mudar para outro local.
Ao solicitar um local especificando um ID de local, você tem a certeza de que sempre receberá o mesmo lugar na resposta (se o lugar ainda existir). No entanto, a resposta pode conter um ID de local diferente daquele na sua solicitação.
Para mais informações, consulte a visão geral do ID de lugar.