Preenchimento automático (novo)

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 de lugares, endereços e 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 do 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.

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 lugares 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 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.

5. Inicie a intent usando o placeAutocompleteActivityResultLauncher.

As amostras a seguir demonstram como adicionar o widget Place Autocomplete usando Kotlin e 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.
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)

// 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 de preenchimento automático, 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 do tema que não são substituídos usam os estilos padrão.

Você pode 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 referenciar os 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 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());
        })
    );

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 primário 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 o viés 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 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:

    • 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").

  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 Autocomplete 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 primary types 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());
        })
    );

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 Preenchimento automático (novo) da API Maps JavaScript, o widget Preenchimento automático (novo) do SDK do Places para Android ou o widget Preenchimento automático (novo) 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 (New), use máscaras de campo nos widgets Place Details (New) e Autocomplete (New) para retornar apenas os campos de dados do Autocomplete (New) necessários.

Otimização avançada de custos

Faça a implementação programática do Autocomplete (New) para acessar SKU: preços de solicitação do Autocomplete e peça resultados da API Geocoding sobre o lugar selecionado em vez do Place Details (New). 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/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.

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

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 preenchimento automático (novo) 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 (novo), 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 detalhes do lugar (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 subunidades, 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 preenchimento automático (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í.

Tendência 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 components para filtrar os resultados e mostrar apenas os lugares em um país específico.

Restrição de local

Restrinja os resultados a uma área especificada transmitindo um parâmetro locationRestriction.

Você também pode 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.