Place Autocomplete

Selecione a plataforma: Android iOS JavaScript Web Service

O serviço de preenchimento automático no SDK do Places para Android retorna previsões de locais em resposta a consultas de pesquisa do usuário. À medida que o usuário digita, o serviço de preenchimento automático retorna sugestões de lugares, como empresas, endereços, códigos Plus e pontos de interesse.

É possível adicionar o preenchimento automático no aplicativo das seguintes formas:

• Adicione um widget de preenchimento automático para economizar tempo de desenvolvimento e garantir uma experiência de usuário consistente.
• Receba sugestões de lugar programaticamente para criar uma experiência do usuário personalizada.

Adicionar um widget de preenchimento automático

O widget de preenchimento automático é uma caixa de diálogo de pesquisa com a funcionalidade de preenchimento automático integrada. Conforme o usuário insere termos de pesquisa, o widget apresenta uma lista de locais previstos para escolha. Quando o usuário faz uma seleção, uma instância de Place é retornada, que o app pode usar para receber detalhes sobre o lugar selecionado.

Há duas opções para se adicionar o widget de preenchimento automático ao seu aplicativo:

• Opção 1: incorporar um AutocompleteSupportFragment.
• Opção 2: usar uma intent para iniciar a atividade de preenchimento automático.

Opção 1: incorporar um AutocompleteSupportFragment

Para adicionar um AutocompleteSupportFragment ao app, siga estas etapas:

1. Adicione um fragmento ao layout XML da atividade.
2. Adicione um listener à atividade ou ao fragmento.

Adicionar AutocompleteSupportFragment a uma atividade

Para adicionar AutocompleteSupportFragment a uma atividade, adicione um novo fragmento a um layout XML. Exemplo:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />

• Por padrão, o fragmento não tem borda nem plano de fundo. Para criar uma aparência visual consistente, aninhe o fragmento em outro elemento de layout, como um CardView.
• Se você estiver usando o fragmento de preenchimento automático e precisar substituir onActivityResult, chame super.onActivityResult. Caso contrário, o fragmento não funcionará corretamente.

Adicionar um PlaceSelectionListener a uma atividade

O PlaceSelectionListener lida com o retorno de um lugar em resposta à seleção do usuário. O código a seguir mostra como criar uma referência ao fragmento e adicionar um listener ao AutocompleteSupportFragment:

Kotlin

    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

Java

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Opção 2: use uma intent para iniciar a atividade de preenchimento automático

Se você quiser que o app use um fluxo de navegação diferente (por exemplo, para ativar a experiência de preenchimento automático por um ícone em vez de por um campo de pesquisa), ele pode iniciar o preenchimento automático usando uma intent.

Observação: essas etapas não são necessárias se você estiver incorporando um fragmento.

Cuidado: NÃO inicie o AutcompleteActivity diretamente. Em vez disso, use uma intent para iniciar Autocomplete (PlaceAutocomplete na biblioteca de compatibilidade).

Para inicializar o widget de preenchimento automático usando um intent, faça o seguinte:

1. Use Autocomplete.IntentBuilder para criar uma intent, transmitindo o modo Autocomplete desejado.
2. Defina um iniciador de resultados de atividade registerForActivityResult que possa ser usado para iniciar a intent e processar a previsão de lugar selecionado do usuário no resultado.

Criar uma intent de preenchimento automático

O exemplo abaixo usa Autocomplete.IntentBuilder para criar um intent para iniciar o widget de preenchimento automático como um intent:

Kotlin

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startAutocomplete.launch(intent)

      

Java

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startAutocomplete.launch(intent);

      

Ao usar uma intent para iniciar o widget de preenchimento automático, você pode escolher entre os modos de exibição por sobreposição ou em tela cheia. As capturas de tela a seguir mostram cada modo de exibição respectivamente:

Figura 1: widget de preenchimento automático no modo OVERLAY

Figura 2: widget de preenchimento automático no modo FULLSCREEN

Registrar um callback para o resultado da intent

Para receber uma notificação quando o usuário selecionar um lugar, defina um iniciador registerForActivityResult(), que inicia a atividade e também processa o resultado, conforme mostrado no exemplo a seguir. Se o usuário tiver selecionado uma sugestão, ela será exibida na intent contida no objeto de resultado. Como a intent foi criada pelo Autocomplete.IntentBuilder, o método Autocomplete.getPlaceFromIntent() pode extrair o objeto Place dela.

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

Java

private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

Como receber previsões de lugar de forma programática

É possível criar uma IU de pesquisa personalizada como alternativa à IU fornecida pelo widget de preenchimento automático. Para isso, o app precisa receber sugestões de local programaticamente. O app pode receber uma lista de nomes e/ou endereços de locais sugeridos da API de preenchimento automático chamando PlacesClient.findAutocompletePredictions(), transmitindo um objeto FindAutocompletePredictionsRequest com os seguintes parâmetros:

• Obrigatório:uma string query contendo o texto digitado pelo usuário.
• Recomendado:um AutocompleteSessionToken, que agrupa as fases de consulta e seleção de uma pesquisa 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 seleciona um lugar.
• Recomendado:um objeto RectangularBounds, que especifica limites de latitude e longitude para restringir os resultados à região especificada.
• Opcional:um ou mais códigos de país de duas letras (ISO 3166-1 Alfa-2), indicando o país ou os países a que os resultados devem ser restritos.

• Opcional:um TypeFilter, que pode ser usado para restringir os resultados ao tipo de lugar especificado. Os seguintes tipos de lugar são aceitos:

  • TypeFilter.GEOCODE: retorna apenas resultados de geocodificação, excluindo estabelecimentos. Use esta solicitação para desambiguar resultados em que o local especificado pode ser indeterminado.
  • TypeFilter.ADDRESS: retorna apenas resultados de preenchimento automático com um endereço preciso. Use este tipo quando sabe que o usuário está procurando um endereço totalmente especificado.
  • TypeFilter.ESTABLISHMENT: retorna apenas lugares que são empresas.

  • TypeFilter.REGIONS: retorna apenas lugares que correspondem a um dos seguintes tipos:

  • LOCALITY

  • SUBLOCALITY

  • POSTAL_CODE

  • COUNTRY

  • ADMINISTRATIVE_AREA_LEVEL_1

  • ADMINISTRATIVE_AREA_LEVEL_2

  • TypeFilter.CITIES: retorna apenas resultados que correspondem a LOCALITY ou ADMINISTRATIVE_AREA_LEVEL_3.

• Opcional:um LatLng que especifica o local de origem da solicitação. Quando você chama setOrigin(), o serviço retorna a distância em metros (distanceMeters) da origem especificada para cada previsão de preenchimento automático na resposta.

Para saber mais sobre os tipos de lugar, consulte o guia sobre tipos de lugar.

O exemplo abaixo mostra uma chamada completa para PlacesClient.findAutocompletePredictions().

Kotlin

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

      

Java

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

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

Para cada local previsto, você pode chamar os seguintes métodos para extrair detalhes do local:

• getFullText(CharacterStyle) retorna o texto completo de uma descrição de local. Essa é uma combinação dos textos principal e secundário. Exemplo: Eiffel Tower, Avenue Anatole France, Paris, France. Além disso, esse método permite destacar as seções da descrição que correspondem à pesquisa com o estilo que você quiser 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 local. Exemplos: Torre Eiffel e 123 Pitt Street.
• getSecondaryText(CharacterStyle) retorna o texto complementar de uma descrição de local. 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 local previsto. Um ID de local é um identificador textual que identifica um local de forma exclusiva, que pode ser usado para recuperar o objeto Place novamente mais tarde. Para mais informações sobre IDs de lugar no SDK do Places para Android, consulte os Detalhes do lugar. Para informações gerais sobre IDs de lugar, consulte a Visão geral do ID de lugar.
• getPlaceTypes() 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.

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

É possível usar um CancellationToken para tentar cancelar uma solicitação para qualquer uma das classes de solicitação (por exemplo, FetchPlaceRequest). O cancelamento é feito da melhor forma possível. Depois que um pedido de cancelamento é emitido, nenhuma resposta é retornada. Emitir um token de cancelamento NÃO garante que uma solicitação específica seja cancelada, e você ainda pode ser cobrado pela solicitação, mesmo que nenhuma resposta seja retornada.

Tokens de sessão

Os tokens de sessão agrupam 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 a pessoa começa a digitar uma consulta e termina quando seleciona um lugar. Cada sessão pode ter várias consultas, seguidas por uma seleção de lugar. Depois que uma sessão é concluída, o token perde a validade. Seu app precisa gerar um novo token para cada sessão. Recomendamos o uso de tokens de sessão para 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 SDK do Places para Android usa um AutocompleteSessionToken para identificar cada sessão. O app precisa transmitir um novo token de sessão ao iniciar cada nova sessão e transmitir esse mesmo token, junto com um ID de lugar, na chamada subsequente para fetchPlace() para extrair os detalhes do lugar selecionado pelo usuário.

Dica: se o app usa o widget Autocomplete, não é necessário implementar sessões porque o widget processa sessões automaticamente em segundo plano.

Saiba mais sobre os tokens de sessão.

Restringir resultados de preenchimento automático

É possível restringir os resultados do preenchimento automático a uma região geográfica específica e/ou filtrar os resultados para um ou mais tipos de local ou até cinco países. É possível aplicar essas restrições à atividade de preenchimento automático, AutocompleteSupportFragment e APIs de preenchimento automático programático.

Para restringir os resultados, faça o seguinte:

• Para preferir resultados dentro da região definida, chame setLocationBias(). Alguns resultados de fora da região definida ainda podem ser retornados.
• Para mostrar apenas resultados na região definida, chame setLocationRestriction(). Somente os resultados na região definida serão retornados.
• Para retornar apenas resultados que estejam em conformidade com um tipo de lugar específico, chame setTypesFilter(). Por exemplo, especificar TypeFilter.ADDRESS vai retornar apenas resultados com um endereço preciso.
• Para retornar apenas resultados em até cinco países especificados, chame setCountries(). Os países precisam ser transmitidos como um código de país de dois caracteres compatível com ISO 3166-1 Alfa-2.

Dar preferência a resultados de uma região específica

Para dar preferência a resultados de preenchimento automático de uma região geográfica específica, chame setLocationBias(), transmitindo um RectangularBounds. O exemplo de código a seguir mostra como chamar setLocationBias() em uma instância de fragmento para dar preferência a sugestões de preenchimento automático a uma região de Sydney, Austrália.

Kotlin

    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Java

    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Restringir os resultados a uma região específica

Para restringir os resultados de preenchimento automático a uma região geográfica específica, chame setLocationRestriction(), transmitindo um RectangularBounds. O exemplo de código a seguir mostra como chamar setLocationRestriction() em uma instância de fragmento para dar preferência a sugestões de preenchimento automático a uma região de Sydney, Austrália.

Kotlin

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Java

    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Observação:essa restrição é aplicada apenas a rotas inteiras. Os resultados sintéticos fora dos limites retangulares podem ser retornados com base em uma rota que se sobrepõe à restrição de local.

Filtrar resultados por tipos de lugar ou coleção de tipos

É possível restringir os resultados de uma solicitação de preenchimento automático para que eles retornem apenas um determinado tipo de lugar. Especifique um filtro usando os tipos de lugar ou uma coleção de tipos listada nas tabelas 1, 2 e 3 em Tipos de lugar. Se nada for especificado, todos os tipos serão retornados.

Para filtrar os resultados de preenchimento automático, chame setTypesFilter() para definir o filtro.

Para especificar um filtro de tipo ou de coleção de tipos:

• Chame setTypesFilter() e especifique até cinco valores de type da Tabela 1 e da Tabela 2 mostradas em Tipos de lugar. Os valores de tipo são definidos pelas constantes em PlaceTypes.

• Chame setTypesFilter() e especifique uma coleção de tipos da Tabela 3 mostrada em Tipos de lugares. Os valores da coleção são definidos pelas constantes em PlaceTypes.

  Somente um tipo da Tabela 3 é permitido na solicitação. Se você especificar um valor na Tabela 3, não vai ser possível fazer isso na Tabela 1 ou na 2. Se isso acontecer, um erro vai ocorrer.

O exemplo de código abaixo chama setTypesFilter() em um AutocompleteSupportFragment e especifica vários valores de tipo.

Kotlin

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

      

Java

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

O exemplo de código a seguir mostra como chamar setTypesFilter() em um AutocompleteSupportFragment para definir um filtro que retorna apenas resultados com um endereço preciso, especificando uma coleção de tipos.

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

O exemplo de código a seguir mostra como chamar setTypesFilter() em um IntentBuilder para definir um filtro que retorna apenas resultados com um endereço preciso, especificando uma coleção de tipos.

Kotlin

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

Java

    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

      

Filtrar resultados por país

Para filtrar os resultados de preenchimento automático para até cinco países, chame setCountries() para definir o código do país. Em seguida, passe o filtro a um fragmento ou intent. Os países precisam ser transmitidos como um código de país de dois caracteres compatível com ISO 3166-1 Alfa-2.

O exemplo de código a seguir mostra como chamar setCountries() em um AutocompleteSupportFragment para definir um filtro que retorna apenas resultados nos países especificados.

Kotlin

    autocompleteFragment.setCountries("AU", "NZ")

      

Java

    autocompleteFragment.setCountries("AU", "NZ");

      

Limites de uso

Seu uso da API Places, incluindo o SDK do Places para Android, não é mais limitado a um número máximo de solicitações por dia (QPD). No entanto, os seguintes limites de uso ainda se aplicam:

• O limite de taxa é de 6.000 QPM (solicitações por minuto). Ele é calculado como a soma das solicitações do lado do cliente e do servidor para todos os aplicativos que usam as credenciais do mesmo projeto.

Exibir atribuições no seu aplicativo

• Se o app usa o serviço de preenchimento automático programaticamente, a interface precisa exibir uma atribuição "Tecnologia do Google" ou aparecer em um mapa com a marca do Google.
• Se o app usa o widget de preenchimento automático, não é preciso fazer mais nada (a atribuição exigida é exibida por padrão).
• Se você recuperar e exibir informações adicionais do local depois de obter um local por ID, também terá que mostrar atribuições de terceiros.

Para mais detalhes, consulte a documentação sobre atribuições.

Otimização do Place Autocomplete

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

Aqui estão algumas diretrizes gerais:

• A maneira mais rápida de desenvolver uma interface do usuário funcional é usar o widget do Autocomplete da API Maps JavaScript, o widget do Autocomplete do SDK do Places para Android ou Controle de IU do Autocomplete do SDK do Places para iOS.
• Entender os campos de dados essenciais do Place Autocomplete 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 Place Autocomplete, use máscaras de campo nos widgets Place Details e Place Autocomplete para retornar apenas os campos de dados de lugar necessários.

Otimização avançada de custos

Faça a implementação programática do Place Autocomplete para acessar preços por solicitação e pedir resultados da API Geocoding sobre o lugar selecionado em vez do Place Details. 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.
• 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 Place Autocomplete 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 Place Autocomplete com base em sessões com o Place Details.
Como seu app exige detalhes do lugar, como nome, status comercial ou horário de funcionamento, a implementação do preenchimento automático precisa usar um token de sessão (de forma programática ou integrada aos widgets do JavaScript, Android ou iOS) a um total de US$ 0,017 por sessão, além de SKU de dados do Places relevantes, dependendo dos campos de dados de lugares 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 Place Autocomplete e do Place Details na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos de dados de lugares necessários.

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

1. O ID de lugar da resposta do Place Autocomplete
2. O token de sessão usado na solicitação do Place Autocomplete
3. O parâmetro fields especificando os campos de dados de lugar 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 para seu aplicativo, dependendo da performance do Place Autocomplete. A eficiência do preenchimento automático 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 Place Autocomplete no seu aplicativo.

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

Sim

Implementar o Place Autocomplete 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 por US$ 0,005 a cada solicitação. Fazer quatro solicitações de Place Autocomplete: por solicitação custa US$ 0,01132. Portanto, o custo total de quatro solicitações, além de uma chamada da API Geocoding sobre a previsão de lugar selecionada, é de US$ 0,01632, menor que o preço de preenchimento automático por sessão de US$ 0,017.¹

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 Place Autocomplete com base em sessões com o Place Details.
Como a média de solicitações que você espera fazer antes de alguém selecionar uma previsão do Place Autocomplete é maior que o custo do preço por sessão, a implementação do Place Autocomplete precisa usar um token de sessão para as solicitações do Place Autocomplete e a respectiva solicitação do Place Details por um total de US$ 0,017 a cada sessão.¹

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Place Autocomplete e do Place Details na previsão selecionada. Especifique o parâmetro fields para garantir a solicitação apenas dos campos de dados básicos.

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

1. O ID de lugar da resposta do Place Autocomplete
2. O token de sessão usado na solicitação do Place Autocomplete
3. O parâmetro fields que especifica campos de dados básicos como endereço e geometria

Considere atrasar as solicitações do Place Autocomplete
É possível adiar uma solicitação do Place Autocomplete 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 do Place Autocomplete para cada caractere depois que o usuário digita o terceiro caractere significa que, se ele digitar 7 caracteres e selecionar uma previsão em que você fez uma solicitação da API Geocoding, o custo total vai ser de US$ 0,01632 (4 × US$ 0,00283 do Autocomplete por solicitação + US$ 0,005 do Geocoding).¹

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 Place Autocomplete 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.

---

1. Os custos listados aqui estão em USD. Consulte a página Faturamento da Plataforma Google Maps para saber tudo sobre os preços.

Práticas recomendadas de performance

As diretrizes a seguir descrevem como otimizar a performance do Place Autocomplete:

• Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Place Autocomplete. 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 Place Autocomplete estiver acompanhado por um mapa, é possível direcionar o local por janela de visualização do mapa.
• Quando um usuário não escolhe uma das previsões do Autocomplete, geralmente porque nenhuma delas é o endereço que ele quer, você pode reutilizar a entrada original para tentar receber resultados mais relevantes:
  • Se você espera 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 do Find Place. 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 subpredial, como endereços de unidades ou apartamentos específicos em um edifício. Por exemplo, o endereço tcheco "Stroupežnického 3191/17, Praha" gera uma previsão parcial no Place Autocomplete.
  • 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í.

Solução de problemas

Embora possam ocorrer diversos erros, geralmente a maioria deles que pode acontecer no app é causada por erros de configuração (por exemplo, uso da chave de API incorreta ou configuração incorreta dela) ou de cota (cota excedida). Consulte Limites de uso para mais informações sobre cotas.

Os erros que podem ocorrer pelo uso dos controles de preenchimento automático são retornados no retorno de chamada de onActivityResult(). Chame Autocomplete.getStatus() para receber a mensagem de status do resultado.