O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Preenchimento automático (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

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

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 trazer palavras completas e substrings da entrada, sugerindo 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 San Francisco, CA. A resposta contém uma lista de previsões de lugares que correspondem à string e à área de pesquisa, como o restaurante chamado "Sicilian Pizza Kitchen". As previsões de lugar retornadas são projetadas para serem apresentadas ao usuário para 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.

É possível integrar a funcionalidade do Autocomplete (New) 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 conforme 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.

Para oferecer uma experiência consistente de preenchimento automático de lugares, adicione o widget do Place Autocomplete ao seu app. O widget oferece uma interface dedicada em tela cheia que processa a entrada do usuário e mostra previsões de lugares para ele, além de retornar objetos AutocompletePrediction para o app. Em seguida, você pode fazer uma solicitação do Place Details (novo) para receber mais informações sobre qualquer uma das previsões de lugares.

Assim como ao receber previsões de lugares de forma programática, o widget do 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:

(Opcional) Defina um token de sessão. Se você não fornecer um token de sessão, o widget criará um para você.
Defina um autocompleteIntent com os parâmetros desejados e seu token de sessão.
Defina um ActivityResultLauncher para StartActivityForResult. Esse inicializador vai processar o resultado retornado da atividade de preenchimento automático.
Processe o resultado no callback do ActivityResultLauncher. Isso envolve extrair o AutocompletePrediction e o 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.
Inicie a intent usando o placeAutocompleteActivityResultLauncher.

Os exemplos a seguir mostram como adicionar o widget do 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);

Personalizar o tema

Ao instanciar uma experiência do Autocomplete, você pode especificar um tema que substitui qualquer um dos atributos de estilo padrão. É possível personalizar as cores, a tipografia, o espaçamento, as bordas e os cantos do componente Place Autocomplete. O padrão é PlacesMaterialTheme. Os atributos de tema que não forem modificados vão usar os estilos padrão.

É possível definir substituições de tema em …/res/values/themes.xml. Exemplo:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

Em seguida, é possível fazer referência aos estilos de substituição chamando setAutocompleteUiCustomization:

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

Receber previsões de lugares 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() e 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 como inicializar PlacesClient, consulte Inicializar o cliente da API Places.

Respostas do Autocomplete (New)

A API retorna um FindAutocompletePredictionsResponse em um Task. O FindAutocompletePredictionsResponse contém uma lista de até cinco AutocompletePrediction objetos 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. É 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 secundário 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, France" e "Sydney, New South Wales".
getPlaceId() retorna o ID de lugar previsto. O ID de lugar é um identificador textual que identifica um local de forma exclusiva. Ele pode ser usado para recuperar o objeto Place novamente mais tarde. Para mais informações sobre IDs de lugar no Autocomplete, consulte Place Details (New). Para informações gerais sobre IDs de lugar, consulte a visão geral de IDs de lugar.
getTypes() retorna a lista de tipos de lugar associados a esse lugar.
getDistanceMeters() retorna a distância em linha reta, em metros, entre esse 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 associado, que precisa ser da Tabela A ou da Tabela B. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house".

A solicitação será 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 ccTLD ("domínio de nível superior") de dois caracteres. 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 de caractere Unicode de base 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 polarização ou uma 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 polarização de local como a especificação da região em que os resultados precisam estar próximos. A principal diferença é que, com a polarização de local, 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 viés ou restrição de local como uma janela de visualização retangular ou um círculo.
- Um círculo é definido pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 50.000,0, inclusive. O valor padrão é 0,0. Para restrição de local, é necessário definir o raio como um valor maior que 0,0. Caso contrário, a solicitação não 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 limites de longitude precisam estar 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 só está disponível 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 cruzará a linha de longitude de 180 graus).
  - Se low.longitude = -180 graus e high.longitude = 180 graus, a janela de visualização inclui todas as longitudes.
  - Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude fica vazio.
  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 para 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 de região 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 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 de região, chame o método setRegionCode() ao criar o objeto FindAutocompletePredictionsRequest.
Token de sessão

Os tokens de sessão são strings geradas pelo usuário que rastreiam as chamadas do Autocomplete (novo), tanto as feitas pelo widget quanto as programáticas, como "sessões". O Autocomplete 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 inicia quando a pessoa começa a digitar uma consulta e termina quando seleciona um local. 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áticas (quando você incorpora um fragmento ou inicia o preenchimento automático usando uma intent, a API cuida disso automaticamente).

O Autocomplete usa um AutocompleteSessionToken para identificar cada sessão. O app precisa transmitir um novo token de sessão ao iniciar cada sessão e, em seguida, transmitir esse 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 do token de sessão, chame o método setSessionToken() ao criar o objeto FindAutocompletePredictionsRequest.

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

Exemplos do Autocomplete (novo)

Usar restrição e polarização de local

O Autocomplete (novo) usa a polarização de IP por padrão para controlar a área de pesquisa. Com a inclusão de viés de IP, a API usa o endereço IP do dispositivo para incluir viés nos resultados. Você pode usar a restrição de local ou a polarização de local, mas não ambas, 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 centralizado 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 local:

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 primários

Use o parâmetro primary types 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 de tipos principais 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 talvez não queira, 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 a distância em linha reta da origem até o destino na resposta (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());
        })
    );

Otimização do Autocomplete (novo)

Esta seção descreve as práticas recomendadas para você aproveitar ao máximo o serviço Autocomplete (New).

Aqui estão algumas diretrizes gerais:

A maneira mais rápida de desenvolver uma interface do usuário funcional é usar o widget do Autocomplete (New) da API Maps JavaScript, o widget do Autocomplete (New) do SDK do Places para Android ou o widget do Autocomplete (New) do SDK do Places para iOS.
Entender os campos de dados essenciais do preenchimento automático (novo) desde o início.
Os campos de direcionamento de local e restrição de local são opcionais, mas podem afetar bastante a performance do preenchimento automático.
Use o tratamento de erros para garantir que o aplicativo faça uma degradação simples se a API retornar um erro.
Verifique se o app continua funcionando quando não há seleção e que oferece às pessoas uma maneira de continuar.

Práticas recomendadas de otimização de custos

Otimização básica de custos

Para otimizar o custo do uso do serviço Autocomplete (novo), use máscaras de campo nos widgets Place Details (novo) e Autocomplete (novo) para retornar apenas os campos de dados do Autocomplete (novo) necessários.

Otimização avançada de custos

Faça a implementação programática do Autocomplete (novo) para acessar SKU: preços de solicitação do Autocomplete e pedir resultados da API Geocoding sobre o lugar selecionado em vez do Place Details (novo). O preço por solicitação combinado com a API Geocoding vai ser mais econômico que o preço por sessão se as duas condições a seguir forem atendidas:

Se você só precisa da latitude e longitude ou do endereço do local selecionado pela pessoa, a API Geocoding fornece essas informações por menos do que uma chamada do Place Details (New).
Se os usuários selecionarem uma previsão de preenchimento automático em média com quatro solicitações desse tipo, o preço por solicitação poderá ser mais econômico que o custo por sessão.

Se quiser ajuda para escolher a implementação do Autocomplete (New) de acordo com o que você precisa, selecione a guia correspondente à resposta à pergunta abaixo.

Seu aplicativo requer outras informações além do endereço e da latitude/longitude da previsão selecionada?

Sim, mais detalhes são necessários

Use o Autocomplete (novo) com base em sessões com o Place Details (novo).
Como seu aplicativo exige o Place Details (novo), como nome do lugar, status da empresa ou horário de funcionamento, sua implementação do Autocomplete (novo) precisa usar um token de sessão (de forma programática ou integrado aos widgets JavaScript, Android ou iOS) por sessão, além das SKUs do Places aplicáveis, dependendo dos campos de dados de lugar que você solicita.¹

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Autocomplete (novo) e do Place Details (novo) na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos de dados do Autocomplete (New) necessários.

Implementação programática
Use um token de sessão com suas solicitações do Autocomplete (novo). Ao solicitar Place Details (New) sobre a previsão selecionada, inclua os seguintes parâmetros:

O ID de lugar da resposta do Autocomplete (novo)
O token de sessão usado na solicitação do Autocomplete (novo)
O parâmetro fields especificando os campos de dados do preenchimento automático (novo) necessários.

Não, apenas o endereço e o local são necessários

A API Geocoding pode ser uma opção mais econômica que o Place Details (novo) para seu aplicativo, dependendo da performance do Autocomplete (novo). A eficiência do Autocomplete (New) de cada aplicativo varia de acordo com o que as pessoas inserem, onde o aplicativo está sendo usado e se as práticas recomendadas de otimização de performance foram seguidas.

Para responder à pergunta a seguir, analise quantos caracteres a pessoa digita em média antes de selecionar uma previsão do Autocomplete (New) no seu aplicativo.

As pessoas selecionam, em média, uma previsão do Autocomplete (novo) em até quatro solicitações?

Sim

Implementar o Autocomplete (New) de forma programática sem tokens de sessão e chamar a API Geocoding na previsão de lugar selecionada.
A API Geocoding oferece endereços e coordenadas de latitude/longitude. Fazer quatro solicitações de preenchimento automático, além de uma chamada da API Geocoding sobre a previsão de lugar selecionada, custa menos do que o preço por sessão do preenchimento automático (novo).¹

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.

Não

Use o Autocomplete com base em sessões (novo) com o Place Details (novo).
Como o número médio de solicitações que você espera fazer antes que um usuário selecione uma previsão do Autocomplete (novo) excede o custo do preço por sessão, sua implementação do Autocomplete (novo) deve usar um token de sessão para as solicitações do Autocomplete (novo) e a solicitação associada do Place Details (novo) por sessão. ¹

O ID de lugar da resposta do Autocomplete (novo)
O token de sessão usado na solicitação do Autocomplete (novo)
O parâmetro fields que especifica campos como endereço e geometria

Considere atrasar as solicitações do Autocomplete (New)
É possível adiar uma solicitação do Autocomplete (New) até que a pessoa digite os três ou quatro primeiros caracteres, fazendo com que o aplicativo gere menos solicitações. Por exemplo, fazer solicitações de preenchimento automático (novo) para cada caractere depois que o usuário digita o terceiro caractere significa que, se o usuário digitar sete caracteres e selecionar uma previsão para a qual você faz uma solicitação da API Geocoding, o custo total será de quatro preenchimentos automáticos (novo) por solicitação + geocodificação.¹

Se for possível usar o atraso de solicitações para deixar sua solicitação programática média abaixo de quatro, siga as orientações para ter uma performance eficiente no Autocomplete (New) com a API Geocoding. Atrasar solicitações pode ser percebido como latência pelo usuário, que talvez queira ver previsões a cada vez que pressionar uma nova tecla.

Convém usar as práticas recomendadas de performance para ajudar as pessoas a conseguir a previsão que querem usando ainda menos caracteres.

Para saber os custos, consulte as tabelas de preços da Plataforma Google Maps.

Práticas recomendadas de desempenho

As diretrizes a seguir descrevem como otimizar a performance do Autocomplete (novo):

Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Autocomplete (New). A preferência de idioma não é necessária com widgets porque eles usam o que está definido no navegador ou no dispositivo móvel do usuário.
Se o Autocomplete (New) estiver acompanhado por um mapa, é possível direcionar o local por janela de visualização do mapa.
Quando a pessoa não escolhe uma das previsões do Autocomplete (New), geralmente porque nenhuma delas é o endereço que ela quer, você pode reutilizar a entrada original para tentar receber resultados mais relevantes:
- Se quiser que o usuário insira apenas informações de endereço, reutilize a entrada original dele em uma chamada para a API Geocoding.
- Se quiser que o usuário insira consultas para um lugar específico por nome ou endereço, use uma solicitação de Place Details (novo). Se os resultados forem esperados apenas em uma região específica, use o direcionamento de local.
Outros cenários em que é melhor voltar para a API Geocoding são:
- Usuários que inserem endereços de subinstalações, como endereços de unidades ou apartamentos específicos em um prédio. Por exemplo, o endereço tcheco "Stroupežnického 3191/17, Praha" gera uma previsão parcial no Autocomplete (novo).
- Usuários que digitam endereços com prefixos de trechos de via, como "23-30 29th St, Queens", na cidade de Nova York, ou "47-380 Kamehameha Hwy, Kaneohe", na ilha de Kauai, no Havaí.

Enviesamento de local

Influencie os resultados para uma área especificada transmitindo um parâmetro location e um parâmetro radius. Isso instrui o preenchimento automático (novo) a preferir mostrar resultados dentro da área definida. Os resultados fora da área definida ainda podem ser exibidos. Use o parâmetro includedRegionCodes para filtrar os resultados e mostrar apenas os lugares em um país específico.

Aviso:se radius não for fornecido, o parâmetro location será ignorado.

Os resultados de estabelecimentos geralmente não têm uma classificação alta o suficiente para aparecer nos resultados quando a área de pesquisa é grande. Se você quiser que os estabelecimentos apareçam em resultados mistos de estabelecimento/geocódigo, especifique um raio menor. Ou use types=establishment para restringir os resultados apenas a estabelecimentos.

Restrição de local

Restrinja os resultados a uma área específica transmitindo um parâmetro locationRestriction.

Também é possível restringir os resultados à região definida por location e um parâmetro radius adicionando o parâmetro locationRestriction. Isso instrui o preenchimento automático (novo) a retornar apenas resultados nessa região.

Preenchimento automático (novo) Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Adicionar o widget do Place Autocomplete

Kotlin

Java

Personalizar o tema

Receber previsões de lugares de forma programática

Respostas do Autocomplete (New)

Parâmetros obrigatórios

Consulta

Parâmetros opcionais

Tipos principais

Países

Deslocamento de entrada

Viés ou restrição de local

Viés de local

Restrição de local

Origem

Código de região

Token de sessão

Exemplos do Autocomplete (novo)

Usar restrição e polarização de local

Usar tipos primários

Usar origem

Otimização do Autocomplete (novo)

Práticas recomendadas de otimização de custos

Otimização básica de custos

Otimização avançada de custos

Sim, mais detalhes são necessários

Não, apenas o endereço e o local são necessários

Sim

Não

Práticas recomendadas de desempenho

Enviesamento de local

Restrição de local

Preenchimento automático (novo)