Preenchimento automático (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

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.

O Autocomplete (novo) retorna previsões de lugares em resposta a uma solicitação que inclui uma string de pesquisa de texto e limites geográficos que controlam a área de pesquisa. O preenchimento automático pode corresponder a palavras completas e substrings da entrada, resolvendo nomes e endereços de lugares, além de Plus Codes. Seu aplicativo pode enviar consultas à medida que o usuário digita, para fornecer previsões de lugar e consulta instantâneas.

Por exemplo, você chama o Autocomplete usando como entrada uma string que contém uma entrada parcial do usuário, "Sicilian piz", com a área de pesquisa limitada a São Francisco, CA. A resposta contém uma lista de previsões de lugares que correspondem à string de pesquisa e à área de pesquisa, como o restaurante "Sicilian Pizza Kitchen". As previsões de lugar retornadas são projetadas para serem apresentadas ao usuário e ajudá-lo a selecionar o lugar desejado. Você pode fazer uma solicitação de Place Details (novo) para receber mais informações sobre qualquer uma das previsões de lugar retornadas.

Você pode integrar a funcionalidade de preenchimento automático (novo) ao seu app de duas maneiras principais:

• Adicione o widget Place Autocomplete: oferece uma experiência de preenchimento automático de pesquisa pronta para uso pela classe PlaceAutocomplete, que mostra previsões à medida que o usuário digita.
• Receber previsões de lugares de forma programática: chame a API diretamente para recuperar previsões e mostrá-las em uma interface personalizada.

Observação: o recurso de preenchimento automático (novo) está disponível no SDK do Places para Android versão 3.5.0 e mais recentes. O widget Autocomplete (New) está disponível no SDK do Places para Android versão 4.3.1 e mais recentes. Para mais informações, consulte Escolher a versão do SDK. Para mais informações sobre o uso das APIs Kotlin adicionadas na versão 4.0.0, consulte a Visão geral da referência.

Adicionar o widget do Place Autocomplete

Para oferecer uma experiência de preenchimento automático de lugares consistente com mais facilidade, adicione o widget Place Autocomplete ao seu app. Ele oferece uma interface dedicada em tela cheia que processa a entrada do usuário e mostra previsões de lugares enquanto retorna objetos AutocompletePrediction ao app. Em seguida, faça uma solicitação Place Details (New) para receber mais informações sobre qualquer uma das previsões de lugares.

Assim como ao receber previsões de lugar de forma programática, o widget Place Autocomplete permite usar tokens de sessão para agrupar solicitações de preenchimento automático em uma sessão para fins de faturamento. É possível transmitir um token de sessão ao criar a intent para o widget chamando setAutocompleteSessionToken(). Se você não fornecer um token de sessão, o widget vai criar um para você, que pode ser acessado chamando getSessionTokenFromIntent(). Para mais informações sobre o uso de tokens de sessão, consulte Sobre tokens de sessão.

Para adicionar o widget do Place Autocomplete ao seu app:

1. (Opcional) Defina um token de sessão. Se você não fornecer um token de sessão, o widget vai criar um para você.

2. Defina um autocompleteIntent com os parâmetros desejados e seu token de sessão.

3. Defina um ActivityResultLauncher para StartActivityForResult. Esse iniciador vai processar o resultado retornado da atividade de preenchimento automático.

4. Processe o resultado no callback de ActivityResultLauncher. Isso envolve extrair AutocompletePrediction e AutocompleteSessionToken (se você não tiver fornecido os seus), processar erros e, opcionalmente, fazer uma solicitação fetchPlace() para receber mais detalhes sobre um lugar.

5. Inicie a intent usando o placeAutocompleteActivityResultLauncher.

Observação: o uso de tokens de sessão é opcional, mas recomendado.

Os exemplos a seguir demonstram como adicionar o widget Place Autocomplete usando Kotlin e Java:

Kotlin

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

Java

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

Receber previsões de lugar de forma programática

Seu app pode receber uma lista de nomes e/ou endereços de lugares previstos da API Autocomplete chamando PlacesClient.findAutocompletePredictions(), transmitindo um objeto FindAutocompletePredictionsRequest. O exemplo abaixo mostra uma chamada completa para PlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Observação:para mais informações sobre a inicialização de 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.

Respostas do Autocomplete (novo)

A API retorna um FindAutocompletePredictionsResponse em um Task. O FindAutocompletePredictionsResponse contém uma lista de até cinco objetos AutocompletePrediction que representam lugares previstos. A lista pode estar vazia se não houver um lugar conhecido que corresponda à consulta e aos critérios de filtro.

Para cada lugar previsto, é possível chamar os seguintes métodos para recuperar detalhes do lugar:

• getFullText(CharacterStyle) retorna o texto completo de uma descrição de lugar. Essa é uma combinação do texto principal e secundário. Exemplo: Torre Eiffel, Avenue Anatole France, Paris, França. Além disso, esse método permite destacar as seções da descrição que correspondem à pesquisa com um estilo de sua escolha, usando CharacterStyle. O parâmetro CharacterStyle é opcional. Defina como nulo se não precisar de destaque.
• getPrimaryText(CharacterStyle) retorna o texto principal que descreve um lugar. Geralmente é o nome do lugar. Exemplos: "Torre Eiffel" e "Rua Pitt, 123".
• getSecondaryText(CharacterStyle) retorna o texto complementar de uma descrição de lugar. Isso é útil, por exemplo, como uma segunda linha ao mostrar previsões de preenchimento automático. Exemplos: Avenue Anatole France, Paris, França e Sydney, Nova Gales do Sul.
• getPlaceId() retorna o ID do lugar previsto. O ID de lugar é um identificador textual que identifica um lugar de forma exclusiva. Ele pode ser usado para recuperar o objeto Place mais tarde. Para mais informações sobre IDs de lugar no Autocomplete, consulte Place Details (novo). Para informações gerais sobre IDs de lugar, consulte a visão geral de IDs de lugar.
• getTypes() retorna a lista de tipos de lugares associados a este lugar.
• getDistanceMeters() retorna a distância em linha reta em metros entre este lugar e a origem especificada na solicitação.

Parâmetros obrigatórios

• Consulta

  A string de texto em que a pesquisa será feita. Especifique palavras completas e substrings, nomes de lugares, endereços e Plus Codes. O serviço Autocomplete (New) retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância.

  Para definir o parâmetro de consulta, chame o método setQuery() ao criar o objeto FindAutocompletePredictionsRequest.

Parâmetros opcionais

• Tipos principais

  Uma lista de até cinco valores de tipo da Tabela A ou da Tabela B, usada para filtrar os lugares retornados na resposta. Um lugar precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.

  Um lugar só pode ter um tipo principal das tabelas A ou B associado a ele. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house".

  A solicitação é rejeitada com um erro INVALID_REQUEST se:

  • Mais de cinco tipos foram especificados.
  • Todos os tipos não reconhecidos são especificados.

  Para definir o parâmetro de tipos principais, chame o método setTypesFilter() ao criar o objeto FindAutocompletePredictionsRequest.

• Países

  Inclua apenas resultados da lista de países especificados, apresentados como uma lista de até 15 valores de dois caracteres ccTLD ("domínio de nível superior"). Se omitido, nenhuma restrição será aplicada à resposta. Por exemplo, para limitar as regiões à Alemanha e à França:

  Se você especificar locationRestriction e includedRegionCodes, os resultados vão estar na área de interseção das duas configurações.

  Para definir o parâmetro "countries", chame o método setCountries() ao criar o objeto FindAutocompletePredictionsRequest.

• Deslocamento de entrada

  O deslocamento do caractere Unicode com base em zero que indica a posição do cursor na consulta. A posição do cursor pode influenciar as previsões retornadas. Se estiver vazio, o padrão será o comprimento da consulta.

  Para definir o parâmetro de deslocamento de entrada, chame o método setInputOffset() ao criar o objeto FindAutocompletePredictionsRequest.

• Viés ou restrição de local

  É possível especificar uma tendência ou restrição de local, mas não ambas, para definir a área de pesquisa. Pense na restrição de local como a especificação da região em que os resultados precisam estar e na tendência de local como a especificação da região em que os resultados precisam estar próximos. A principal diferença é que, com a tendência de localização, os resultados fora da região especificada ainda podem ser retornados.

  • Viés de local

    Especifica uma área para pesquisar. Esse local serve como uma tendência, não uma restrição. Portanto, resultados fora da área especificada ainda podem ser retornados.

    Para definir o parâmetro de tendência de local, chame o método setLocationBias() ao criar o objeto FindAutocompletePredictionsRequest.

  • Restrição de local

    Especifica uma área para pesquisar. Os resultados fora da área especificada não são retornados.

    Para definir o parâmetro de restrição de local, chame o método setLocationRestriction() ao criar o objeto FindAutocompletePredictionsRequest.

  Especifique a região de restrição ou viés de local como uma janela de visualização retangular ou um círculo.

  • Um círculo é definido por um ponto central e um raio em metros. O raio precisa estar entre 0,0 e 50.000,0, incluindo esses dois valores. O valor padrão é 0,0. Para restrição de local, defina o raio como um valor maior que 0,0. Caso contrário, a solicitação não vai retornar resultados.

  • Um retângulo é uma janela de visualização de latitude-longitude, representada como dois pontos low e high diagonalmente opostos. Uma janela de visualização é considerada uma região fechada, ou seja, inclui o limite. Os limites de latitude precisam estar entre -90 e 90 graus, e os de longitude entre -180 e 180 graus:

    Observação:os tipos de viés aceitos variam de acordo com a versão do SDK que você está usando. O CircularBounds está disponível apenas no Autocomplete (novo).
    • Se low = high, a janela de visualização consiste nesse único ponto.
    • Se low.longitude > high.longitude, o intervalo de longitude será invertido (a janela de visualização cruza a linha de longitude de 180 graus).
    • Se low.longitude = -180 graus e high.longitude = 180 graus, a janela de visualização vai incluir todas as longitudes.
    • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude estará vazio.

    Os campos low e high precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma janela de visualização vazia resulta em um erro.

• Origem

  O ponto de origem de onde calcular a distância em linha reta até o destino (acessado usando getDistanceMeters()). Se esse valor for omitido, a distância em linha reta não será retornada. Precisa ser especificado como coordenadas de latitude e longitude:

  Para definir o parâmetro de origem, chame o método setOrigin() ao criar o objeto FindAutocompletePredictionsRequest.

• Código de região

  O código regional usado para formatar a resposta, incluindo a formatação de endereço, especificado como um valor de dois caracteres de ccTLD ("domínio de nível superior"). A maioria dos códigos de ccTLD é 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").

  Observação:o código de região representa a região de origem da solicitação, não necessariamente a região de destino da consulta.

  Se você especificar um código de região inválido, a API vai retornar um erro INVALID_ARGUMENT. O parâmetro pode afetar os resultados com base na legislação aplicável.

  Para definir o parâmetro de código da região, chame o método setRegionCode() ao criar o objeto FindAutocompletePredictionsRequest.

• Token da sessão

  Os tokens de sessão são strings geradas pelo usuário que rastreiam chamadas do Autocomplete (New), tanto as feitas pelo widget quanto as programáticas, como "sessões". O preenchimento automático usa tokens de sessão para agrupar as fases de consulta e seleção de uma pesquisa de preenchimento automático do usuário em uma sessão discreta para fins de faturamento. A sessão começa quando o usuário começa a digitar uma consulta e termina quando ele seleciona um lugar. Cada sessão pode ter várias consultas, seguidas por uma seleção de lugar. Após a conclusão de uma sessão, o token perde a validade. Seu app precisa gerar um novo token para cada sessão. Recomendamos o uso de tokens de sessão em todas as sessões de preenchimento automático programático (quando você incorpora um fragmento ou inicia o preenchimento automático usando uma intent, a API cuida disso automaticamente).

  O preenchimento automático usa um AutocompleteSessionToken para identificar cada sessão. Seu app precisa transmitir um novo token de sessão ao iniciar cada nova sessão e, em seguida, transmitir o mesmo token, junto com um ID de lugar, na chamada subsequente para fetchPlace() para recuperar os detalhes do lugar selecionado pelo usuário.

  Para definir o parâmetro de token de sessão, chame o método setSessionToken() ao criar o objeto FindAutocompletePredictionsRequest.

  Para mais informações, consulte Tokens de sessão.

Exemplos de preenchimento automático (novo)

Usar restrição e viés de local

O recurso Autocompletar (novo) usa a tendência de IP por padrão para controlar a área de pesquisa. Com a inclusão de tendência de IP, a API usa o endereço IP do dispositivo para influenciar os resultados. Você pode usar a restrição de local ou o vício de local, mas não os dois, para especificar uma área de pesquisa.

A restrição de local especifica a área a ser pesquisada. Os resultados fora da área especificada não são retornados. O exemplo a seguir usa a restrição de local para limitar a solicitação a uma restrição circular com um raio de 5.000 metros centrada em São Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Com o direcionamento por local, o local serve como um viés, o que significa que os resultados ao redor do local especificado podem ser retornados, incluindo resultados fora da área especificada. O exemplo a seguir muda a solicitação anterior para usar a tendência de localização:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Usar tipos principais

Use o parâmetro tipos principais para restringir os resultados de uma solicitação a um determinado tipo, conforme listado na Tabela A e na Tabela B. É possível especificar uma matriz de até cinco valores. Se omitido, todos os tipos serão retornados.

O exemplo a seguir especifica uma string de consulta "Soccer" e usa o parâmetro primarytypes para restringir os resultados a estabelecimentos do tipo "sporting_goods_store":

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Se você omitir o parâmetro de tipos principais, os resultados poderão incluir estabelecimentos de um tipo que você não quer, como "athletic_field".

Usar origem

Quando você inclui o parâmetro origin na solicitação, especificado como coordenadas de latitude e longitude, a API inclui na resposta a distância em linha reta da origem ao destino (acessada usando getDistanceMeters()). Este exemplo define a origem como o centro de São Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Atribuições

Você pode usar o recurso de preenchimento automático (novo) mesmo sem um mapa. Se você mostrar um mapa, ele terá que ser do Google. Quando você mostra previsões do serviço Autocomplete (New) sem um mapa, é necessário incluir o logotipo do Google inline com o campo/resultados da pesquisa. Para mais informações, consulte Como mostrar o logotipo do Google e as atribuições.