Place Details

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

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

Detalhes do lugar

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

Ao solicitar um local, é necessário especificar quais dados devem ser retornados. Para isso, transmita uma lista de valores de Place.Field que especificam os dados a serem retornados. Essa lista é importante porque afeta o custo de cada solicitação.

Como os resultados de dados de lugar não podem ficar vazios, somente aqueles com informações são retornados. Por exemplo, se um lugar solicitado não tiver fotos, o campo photos não vai 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:

Kotlin

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

Java

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

Acessar campos de dados do objeto Place

Depois de conseguir o objeto Place, use os métodos dele para acessar os campos de dados especificados na solicitação. Se o campo estiver ausente no objeto Place, o método relacionado retornará um valor nulo. Confira 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 local em formato legível.
  • getAddressComponents(): uma List de componentes de endereço para esse local. Esses componentes são fornecidos com o objetivo de extrair informações estruturadas sobre o endereço de um local, como encontrar a cidade em que ele 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 local. Leia mais sobre IDs de local no restante desta página.
  • getLatLng(): a localização geográfica do lugar, especificada por coordenadas de latitude e longitude.
  • getName(): o nome do local.
  • 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 são equivalentes aos dados fornecidos por getWeekdayText().

    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 do local 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á agora. isOpen será retornado apenas 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. Caso não seja solicitado, presume-se que a empresa está em funcionamento. Assista a este vídeo para saber como usar isOpen com o Place Details.

Alguns exemplos simples:

Kotlin



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

      

Java


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

      

Obter local por ID

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

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

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

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

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

      

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

      

Receber status

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.
  • Um valor de hora opcional que especifica o tempo em milissegundos de 1970-01-01T00:00:00Z. Se nenhum horário 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 informados 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.

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 = "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
}
// ...

      

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

      

O próximo exemplo mostra como chamar isOpen() quando você transmite 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 = "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
    }
    // ...
}
// ...

      

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

      

Exibir atribuições no seu aplicativo

Quando seu app exibe informações de locais, incluindo avaliações, ele também precisa mostrar quaisquer 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 é o mesmo identificador usado na API Places. Cada ID de local pode se referir a apenas um local, mas um único local pode ter mais de um ID de local. Existem outras circunstâncias que podem fazer com que um local receba um novo ID. Por exemplo, isso acontece quando uma empresa se muda para um novo local.

Ao solicitar um local especificando um ID de local, 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 lugar diferente daquele usado na solicitação.

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