Esta página foi traduzida pela API Cloud Translation.

Place Details

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

O SDK do Places para Android fornece ao seu app informações valiosas sobre lugares, incluindo o nome e o endereço deles, a localização geográfica especificada por coordenadas de latitude/longitude, o tipo de lugar (como casa noturna, 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. Você pode conseguir um objeto Place das seguintes maneiras:

Chame PlacesClient.fetchPlace(): consulte o guia sobre como acessar um lugar por código.
Chame PlacesClient.findCurrentPlace(): consulte o guia sobre como acessar o lugar atual.
Embora PlacesClient.fetchPlace() aceite todos os campos de dados de lugar, PlacesClient.findCurrentPlace() aceita apenas um subconjunto de campos de dados de lugar. Para ver a lista de campos NÃO compatíveis com findCurrentPlace(), consulte Suporte a campos do SDK do Places para Android.

Ao solicitar um local, é necessário especificar quais dados devem ser retornados. Para fazer 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 estar vazios, somente aqueles que têm informações são retornados. Por exemplo, se um lugar solicitado não tiver fotos, o campo photos não estará presente.

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 placeFields = Arrays.asList(Place.Field.NAME, Place.Field.RATING, Place.Field.OPENING_HOURS);

Acessar campos de dados do objeto do 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 no 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 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, 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(): 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 local. 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().

Observação : quando um lugar está sempre aberto, o período é representado como domingo à meia-noite, e closeEvent é 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 nos próximos sete dias.
isOpen(): um booleano que indica se o local está aberto no momento. Se nenhum horário 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, inclua os campos Place.Field.BUSINESS_STATUS e Place.Field.UTC_OFFSET na sua solicitação de lugar original. Quando a solicitação não é solicitada, presume-se que a empresa está funcionando. 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 aberto.

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

Acessar dados de lugar adicionados na versão 3.3.0

O SDK do Places para Android versão 3.3.0 adiciona novos dados a Place:

Tipos de lugares: novos valores de tipo associados a um lugar.
Avaliações: até cinco avaliações de um lugar.
Código do idioma do nome: o código do idioma do nome de um lugar.

As seções a seguir descrevem como acessar esses novos dados.

Observação : o novo SDK só oferece suporte aos novos dados do Place em Java.

Acesse novos tipos de lugares

Cada local pode ter um ou mais valores de type associados a ele. O SDK do Places para Android versão 3.3.0 adiciona muitos novos valores de tipo. Confira a lista completa em Tipos de lugar expandidos.

No SDK do Places para Android versão 3.2.0 e anteriores, você usou o método Place.getTypes() para acessar os valores de tipo associados a um lugar. Place.getTypes() retorna uma lista de tipos como valores de tipo enumerado definidos por Place.Types.

O método Place.getTypes() foi descontinuado a partir da versão 3.3.0 do SDK do Places para Android. Embora seja possível continuar a usá-lo durante o período de descontinuação, migre seus apps para o Place.getPlaceTypes().

O método Place.getPlaceTypes() retorna os valores de tipo como uma lista de valores de string. Os valores retornados dependem da sua versão do SDK do Places para Android:

SDK do Places para Android (novo): retorna as strings definidas pelas tabelas A e B exibidas em Tipos de lugar (novo), incluindo todos os tipos de lugar adicionados na versão 3.3.0.
SDK do Places para Android: retorna os tipos enumerados definidos por Place.Types, o que não inclui os novos tipos adicionados na versão 3.3.0.

Para saber as principais diferenças entre as duas versões do SDK, consulte Escolher a versão do SDK.

Acessar avaliações de lugares

O SDK do Places para Android (novo) adiciona a classe Review, que contém uma avaliação de um lugar. O objeto Place pode conter até cinco avaliações.

A classe Review também pode conter uma atribuição de autor. Se você exibir a avaliação no app, também vai precisar mostrar qualquer atribuição ou atribuição de autor. Para saber mais, consulte Mostrar uma avaliação.

Para preencher o objeto Place com avaliações, você precisa:

Ative o novo SDK quando você configurar seu projeto do Google Cloud.
Inicialize o novo SDK em uma atividade ou um fragmento.
Inclua Place.Field.REVIEWS na lista de campos da solicitação de detalhes do lugar.
Chame PlacesClient.fetchPlace(). O campo de avaliações não é compatível com PlacesClient.findCurrentPlace().
Use o método Place.getReviews() para acessar o campo de dados de avaliações no objeto Place.

Acessar o código de idioma do nome do lugar

O método Place.getName() retorna uma string de texto contendo o nome de um lugar. Para preencher o objeto Place com o nome do lugar, inclua o Place.Field.NAME na lista de campos da solicitação do Place Details.

O objeto Place agora contém o código do idioma para a string de nome. Para preencher o objeto Place com o código de idioma, faça o seguinte:

Ative o novo SDK quando você configurar seu projeto do Google Cloud.
Inicialize o novo SDK em uma atividade ou um fragmento.
Inclua o Place.Field.NAME na lista de campos da solicitação. Esse valor configura a resposta para incluir o nome do lugar e o código do idioma no objeto Place.
Chame PlacesClient.fetchPlace(). PlacesClient.findCurrentPlace() não oferece suporte ao campo de código de idioma.
Use o método Place.getNameLanguageCode() para acessar o campo de código de idioma no objeto Place.

Definir o código de região na versão 3.3.0

O SDK do Places para Android (novo) adiciona o parâmetro de solicitação de código de região ao Place Details. O código regional é usado para formatar a resposta, especificada como um valor de código CLDR de dois caracteres. Esse parâmetro também pode ter um efeito de viés sobre os resultados da pesquisa. Não há valor padrão. Ative o novo SDK para definir o código da região.

Se o nome do país do campo de endereço na resposta corresponder ao código da região, o código do país será omitido do endereço.

A maioria dos códigos CLDR é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente, para a entidade "Reino Unido da Grã-Bretanha e Irlanda do Norte"). O parâmetro pode afetar os resultados com base na legislação aplicável.

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 lugar 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 novamente mais tarde.

Para acessar 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 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 de aberto

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 a duração 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 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 nas chamadas para fetchPlace() de Place.Field.UTC_OFFSET e Place.Field.BUSINESS_STATUS. A SKU Contact Data do Places é cobrada nas chamadas para fetchPlace() de 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ê transmite apenas 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() em que 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 lugares, 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 só pode se referir a um local, mas um único local pode ter mais de um. Existem 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 local 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 dos IDs de lugar.