Local atual

Desenvolvedores do Espaço Econômico Europeu (EEE)

Se o endereço de faturamento estiver no Espaço Econômico Europeu, a partir de 8 de julho de 2025, os Termos de Serviço da Plataforma Google Maps para o EEE vão se aplicar ao uso dos Serviços. A funcionalidade varia de acordo com a região. Saiba mais.

Descontinuado:o método PlacesClient.findCurrentPlace() foi descontinuado. Use PlacesClient.searchNearby(). Para usar PlacesClient.searchNearby(), ative a API Places (nova) na sua chave de API no console do Google Cloud.

Com o SDK do Places para Android, é possível descobrir o local na localização informada no dispositivo naquele momento. Exemplos de lugares incluem empresas locais, pontos de interesse e localizações geográficas.

Observação : para conferir um tutorial prático e guiado, consulte o tutorial "Lugar atual".

Permissões

Para usar a biblioteca, não é necessário declarar outras permissões no manifesto do app, já que a biblioteca declara todas as permissões que usa no manifesto dela. No entanto, se o app usar PlacesClient.findCurrentPlace(), você precisa solicitar permissões de localização durante a execução.

Se o app não usar PlacesClient.findCurrentPlace(), remova explicitamente as permissões ACCESS_FINE_LOCATION e ACCESS_COARSE_LOCATION introduzidas pela biblioteca adicionando o seguinte ao manifesto:

<manifest ... xmlns:tools="http://schemas.android.com/tools">
    ...
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove"/>
    ...
</manifest>

Leia mais sobre permissões e considere usar o EasyPermissions para começar.

Obter localização atual

Para encontrar a empresa local ou outro lugar onde o dispositivo está localizado, siga estas etapas:

1. Chame ContextCompat.checkSelfPermission para verificar se o usuário concedeu permissão para acessar a localização do dispositivo. Seu app também precisa incluir código para pedir permissão ao usuário e processar o resultado. Consulte Solicitar permissões do app para mais detalhes.
2. Crie um FindCurrentPlaceRequest, transmitindo um List de Place.Fields, especificando os tipos de dados de lugar que seu app deve solicitar.
3. Chame PlacesClient.findCurrentPlace(), transmitindo o FindCurrentPlaceRequest criado na etapa anterior.
4. Extraia a lista de PlaceLikelihoods do FindCurrentPlaceResponse.

Observação:embora PlacesClient.fetchPlace() seja compatível com todos os detalhes do lugar, PlacesClient.findCurrentPlace() aceita apenas um subconjunto deles. Para conferir a lista de campos NÃO compatíveis com findCurrentPlace(), consulte Suporte a campos do SDK do Places para Android.

Os campos correspondem aos resultados da Pesquisa de lugar e são divididos em três categorias de faturamento: Basic, Contact e Atmosphere. Os campos "Basic" são faturados na taxa básica e não geram cobranças extras. Os campos "Contact" e "Atmosphere" são faturados em uma taxa maior. Para mais informações sobre como as solicitações de dados de lugar são faturadas, consulte Uso e faturamento.

A API retorna um FindCurrentPlaceResponse em um Task. O FindCurrentPlaceResponse contém uma lista de objetos PlaceLikelihood que representam lugares onde o dispositivo provavelmente está localizado. Para cada lugar, o resultado inclui uma indicação da probabilidade de que o lugar seja o certo. A lista pode estar vazia se não houver um lugar conhecido correspondente à localização do dispositivo.

Você pode chamar PlaceLikelihood.getPlace() para recuperar um objeto Place e PlaceLikelihood.getLikelihood() para receber a classificação de probabilidade do lugar. Um valor mais alto significa uma probabilidade maior de que o lugar seja a melhor correspondência.

O exemplo de código a seguir recupera a lista de lugares onde o dispositivo provavelmente está localizado e registra o nome e a probabilidade de cada lugar.

Kotlin

// Use fields to define the data types to return.
val placeFields: List<Place.Field> = listOf(Place.Field.NAME)

// Use the builder to create a FindCurrentPlaceRequest.
val request: FindCurrentPlaceRequest = FindCurrentPlaceRequest.newInstance(placeFields)

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, permission.ACCESS_FINE_LOCATION) ==
    PackageManager.PERMISSION_GRANTED) {

    val placeResponse = placesClient.findCurrentPlace(request)
    placeResponse.addOnCompleteListener { task ->
        if (task.isSuccessful) {
            val response = task.result
            for (placeLikelihood: PlaceLikelihood in response?.placeLikelihoods ?: emptyList()) {
                Log.i(
                    TAG,
                    "Place '${placeLikelihood.place.name}' has likelihood: ${placeLikelihood.likelihood}"
                )
            }
        } else {
            val exception = task.exception
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }
    }
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission()
}

      

Java

// Use fields to define the data types to return.
List<Place.Field> placeFields = Collections.singletonList(Place.Field.NAME);

// Use the builder to create a FindCurrentPlaceRequest.
FindCurrentPlaceRequest request = FindCurrentPlaceRequest.newInstance(placeFields);

// Call findCurrentPlace and handle the response (first check that the user has granted permission).
if (ContextCompat.checkSelfPermission(this, ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED) {
    Task<FindCurrentPlaceResponse> placeResponse = placesClient.findCurrentPlace(request);
    placeResponse.addOnCompleteListener(task -> {
        if (task.isSuccessful()){
            FindCurrentPlaceResponse response = task.getResult();
            for (PlaceLikelihood placeLikelihood : response.getPlaceLikelihoods()) {
                Log.i(TAG, String.format("Place '%s' has likelihood: %f",
                    placeLikelihood.getPlace().getName(),
                    placeLikelihood.getLikelihood()));
            }
        } else {
            Exception exception = task.getException();
            if (exception instanceof ApiException) {
                ApiException apiException = (ApiException) exception;
                Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            }
        }
    });
} else {
    // A local method to request required permissions;
    // See https://developer.android.com/training/permissions/requesting
    getLocationPermission();
}

      

Observações sobre os valores de probabilidade:

• A probabilidade fornece uma probabilidade relativa de o lugar ser a melhor correspondência na lista de lugares retornados para uma única solicitação. Não é possível comparar probabilidades em solicitações diferentes.
• O valor da verossimilhança estará entre 0,0 e 1,0.

Por exemplo, para representar uma probabilidade de 55% de que o lugar correto seja o lugar A e uma probabilidade de 35% de que seja o lugar B, a resposta tem dois membros: lugar A com uma probabilidade de 0, 55 e lugar B com uma probabilidade de 0,35.

Observação:para mais informações sobre como inicializar PlacesClient, consulte Inicializar o cliente da API Places.

Você pode usar um CancellationToken para tentar cancelar uma solicitação a qualquer uma das classes de solicitação (por exemplo, FetchPlaceRequest). O cancelamento é feito da melhor maneira possível. Depois que um pedido de cancelamento é emitido, nenhuma resposta é retornada. A emissão de um token de cancelamento NÃO garante que uma solicitação específica será cancelada, e você ainda poderá receber uma cobrança por ela mesmo que nenhuma resposta seja retornada.

Exibir atribuições no seu aplicativo

Quando seu app mostra informações obtidas de PlacesClient.findCurrentPlace(), ele também precisa mostrar atribuições. Consulte a documentação sobre atribuições.