Place Autocomplete

Selecione a plataforma: Android iOS JavaScript Serviço da Web

O serviço de preenchimento automático no SDK do Places para Android retorna previsões de lugar em resposta a consultas de pesquisa do usuário. Conforme 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:

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. À medida que um usuário digita termos de pesquisa, o widget apresenta uma lista de locais previstos para escolha. Quando o usuário faz uma seleção, uma instância Place é retornada, e o app vai poder usá-la para ver 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

Para adicionar um AutocompleteSupportFragment ao seu app, siga estas etapas:

  1. Adicionar um fragmento ao layout XML da atividade
  2. Adicione um listener à sua atividade ou 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 ter uma aparência visual consistente, aninhe o fragmento em outro elemento de layout, como uma 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 processa o retorno de um lugar em resposta à seleção do usuário. O código a seguir mostra a criação de uma referência ao fragmento e a adição de um listener ao AutocompleteSupportFragment:

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);
        }
    });

      

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")
        }
    })

      

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

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

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. A intent precisa chamar startActivityForResult, transmitindo um código de solicitação que a identifica.
  2. Modifique o callback onActivityResult para receber o lugar selecionado.

Criar uma intent de preenchimento automático

O exemplo abaixo mostra o uso de Autocomplete.IntentBuilder para criar uma intent para iniciar o widget de preenchimento automático como uma intent:

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // 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);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // 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)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

Quando exibido no modo de sobreposição, o widget de preenchimento automático aparece sobreposto na IU de chamada.
Figura 1: widget de preenchimento automático no modo OVERLAY
Quando exibido no modo de tela cheia, o widget de preenchimento automático preenche a tela inteira.
Figura 2: widget de preenchimento automático no modo FULLscreen

Substituir o callback onActivityResult

Para receber uma notificação quando o usuário selecionar um lugar, seu app precisará substituir a onActivityResult() da atividade, verificando o código de solicitação transmitido para a intent, conforme mostrado no exemplo a seguir.

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

Receber previsões de lugares de maneira programática

Você pode criar uma IU de pesquisa personalizada como alternativa à IU fornecida pelo widget de preenchimento automático. Para fazer isso, seu app precisa receber previsões de lugar de forma programática. Seu app pode receber uma lista de nomes de lugares e/ou endereços previstos 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 de usuário em uma sessão distinta 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.
  • Recomendado:um objeto RectangularBounds, que especifica os 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 aos quais 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 compatíveis:

    • TypeFilter.GEOCODE: retorna apenas resultados de geocodificação, não de empresas. Use essa solicitação para diferenciar os resultados em que o local especificado pode ser indeterminado.
    • TypeFilter.ADDRESS: retorna apenas resultados de preenchimento automático com um endereço preciso. Use esse tipo quando souber 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 correspondentes 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 ver informações sobre os tipos de lugar, consulte o guia sobre tipos de lugar.

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

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")
        .setTypeFilter(TypeFilter.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());
        }
    });

      

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")
            .setTypeFilter(TypeFilter.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)
            }
        }

      

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

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

  • getFullText(CharacterStyle) retorna o texto completo de uma descrição do lugar. Essa é uma combinação do texto principal e secundário. Exemplo: "Torre Eiffel, Avenue Anatole France, Paris, França" Além disso, esse método permite destacar as seções da descrição que correspondem à pesquisa com um estilo de sua escolha usando CharacterStyle. O parâmetro CharacterStyle é opcional. Defina-o como nulo se você não precisar de nenhum destaque.
  • getPrimaryText(CharacterStyle) retorna o texto principal que descreve um lugar. Geralmente, é o nome do lugar. Exemplos: "Eiffel Tower" e "123 Pitt Street".
  • getSecondaryText(CharacterStyle) retorna o texto da subsidiária de uma descrição do lugar. Isso é útil, por exemplo, como uma segunda linha ao mostrar previsões de preenchimento automático. Exemplos: "Avenida Anatole França, Paris, França" e "Sydney, New South Wales".
  • getPlaceId() retorna o ID do lugar previsto. Um ID de lugar é um identificador textual que identifica um lugar 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 o Place Details. Para informações gerais sobre IDs de lugar, consulte a visão geral de IDs 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.

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 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 não será mais válido. Seu app precisa gerar um token novo para cada sessão. É recomendável usar tokens de sessão em todas as sessões de preenchimento automático programáticos (ao incorporar um fragmento ou iniciar 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 no início de cada nova sessão e, em seguida, transmitir esse mesmo token com um ID de lugar na chamada subsequente para fetchPlace() para recuperar o Place Details do lugar selecionado pelo usuário.

Saiba mais sobre 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 lugar ou para até cinco países. Você pode aplicar essas restrições à atividade de preenchimento automático, AutocompleteSupportFragment e às APIs de preenchimento automático programáticas.

Para restringir os resultados, faça o seguinte:

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

Viés dos resultados para uma região específica

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

Java


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

      

Kotlin


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

      

Restringir os resultados a uma região específica

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

Java


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

      

Kotlin


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

      

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

Filtrar resultados por tipo de lugar

É possível restringir os resultados de uma solicitação de preenchimento automático para que eles retornem apenas um determinado tipo de lugar. Se os resultados não forem restritos, todos os tipos serão retornados. Em geral, apenas um tipo é permitido. A exceção é que você pode mesclar com segurança os tipos GEOCODE e ESTABLISHMENT. No entanto, isso tem o mesmo efeito que especificar nenhum tipo.

Se quiser filtrar os resultados do preenchimento automático para um tipo de lugar específico, chame setTypeFilter() e defina o filtro a ser usado. Em seguida, passe o filtro a um fragmento ou intent.

O exemplo de código a seguir mostra a chamada de setTypeFilter() em um AutocompleteSupportFragment para definir um filtro que retorne apenas resultados com um endereço exato.

Java


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS);

      

Kotlin


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS)

      

O exemplo de código a seguir mostra a chamada de setTypeFilter() em um IntentBuilder para definir um filtro que retorne apenas resultados com um endereço exato.

Java


    Intent intent = new Autocomplete.IntentBuilder(
        AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

Para ver informações sobre os tipos de lugar, consulte o guia sobre tipos de lugar.

Filtrar os resultados por país

Se quiser filtrar os resultados do 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 a chamada de setCountries() em um AutocompleteSupportFragment para definir um filtro que retorne apenas resultados nos países especificados.

Java


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

      

Kotlin


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

      

Limites de uso

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

  • A limitação de taxa é de 100 solicitações por segundo (QPS). Ele é calculado como a soma das solicitações do lado do cliente e do servidor para todos os aplicativos usando as credenciais do mesmo projeto.

Exibir atribuições no seu aplicativo

  • Se o app usa o serviço de preenchimento automático de maneira programática, a IU precisa exibir uma atribuição 'Com tecnologia do Google' ou aparecer em um mapa da marca Google.
  • Se o app usa o widget de preenchimento automático, nenhuma outra ação é necessária, a atribuição necessária é exibida por padrão.
  • Se você recuperar e exibir outras informações do local depois de conseguir um lugar por ID, também precisará exibir 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 ajudar você a aproveitar ao máximo o serviço Place Autocomplete.

Veja 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 o controle da 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 viés de local e restrição de local são opcionais, mas podem ter um impacto significativo no desempenho do preenchimento automático.
  • Use o tratamento de erros para garantir que o app faça uma degradação suave se a API retornar um erro.
  • Verifique se o app processa quando não há seleção e oferece aos usuários 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 de Place Details e Place Autocomplete para retornar apenas os campos de dados de lugar necessários.

Otimização avançada de custos

Considere a implementação programática do Place Autocomplete para acessar preços por solicitação e solicitar resultados da API Geocoding sobre o lugar selecionado em vez do Place Details. O preço por solicitação combinado à API Geocoding é mais econômico que o preço por sessão (com base na sessão) se as duas condições a seguir forem atendidas:

  • Se você precisar apenas da latitude/longitude ou do endereço do lugar selecionado pelo usuário, a API Geocoding fornecerá essas informações para menos do que uma chamada de 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.
Para receber ajuda para escolher a implementação do Place Autocomplete adequada às suas necessidades, selecione a guia que corresponde à resposta à pergunta abaixo.

Seu aplicativo requer outras informações que não sejam o endereço e a latitude/longitude da previsão selecionada?

Sim, precisa de mais detalhes

Use o Place Autocomplete com base em sessões com o Place Details.
Como seu aplicativo exige o Place Details, como nome do local, status de negócios ou horário de funcionamento, a implementação do Place Autocomplete deve usar um token de sessão (de maneira programática ou integrada aos widgets JavaScript, Android ou iOS) por um custo total de US $0,017 por sessão, além de SKUs de dados do Places aplicáveis, dependendo dos campos de dados de local solicitados.

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ê esteja solicitando apenas os campos de dados de lugar necessários.

Implementação programática
Use um token de sessão com suas solicitações de 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, precisa apenas do endereço e local

A API Geocoding pode ser uma opção mais econômica que o Place Details para seu aplicativo, dependendo do desempenho do uso do Place Autocomplete. A eficiência do preenchimento automático de todos os aplicativos varia de acordo com o que os usuários estão inserindo, onde o aplicativo está sendo usado e se as práticas recomendadas de otimização de desempenho foram implementadas.

Para responder à pergunta a seguir, analise quantos caracteres um usuário digita em média antes de selecionar uma previsão do Place Autocomplete no seu aplicativo.

Os usuários selecionam, em média, uma previsão do Place Autocomplete em quatro solicitações ou menos?

Sim

Implementar o Place Autocomplete de forma programática sem tokens de sessão e chamar a API Geocoding na previsão de local selecionada.
A API Geocoding fornece endereços e coordenadas de latitude/longitude por US $0,005 por solicitação. Fazer quatro solicitações de Place Autocomplete - Per Request custa US $0,01132, portanto, o custo total de quatro solicitações, além de uma chamada da Geocoding API sobre a previsão de local selecionada, é de US $0,01632, o que é menor que o preço de preenchimento automático por sessão de US $0,017 por sessão.1

Considere usar as práticas recomendadas de desempenho para ajudar os usuários a conseguir a previsão que estão procurando em ainda menos caracteres.

No

Use o Place Autocomplete com base em sessões com o Place Details.
Como o número médio de solicitações que você espera fazer antes que um usuário selecione uma previsão do Place Autocomplete excede o custo do preço por sessão, a implementação desse recurso deve usar um token de sessão para as solicitações do Place Autocomplete e para as solicitações associadas do Place Details, com um custo total de US $0,017 por sessão.1

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ê esteja solicitando apenas os campos de dados básicos.

Implementação programática
Use um token de sessão com suas solicitações de 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. Parâmetro fields que especifica os campos de dados básicos, como endereço e geometria

Considere atrasar solicitações do Place Autocomplete
É possível empregar estratégias como adiar uma solicitação do Place Autocomplete até que o usuário digite os três ou quatro primeiros caracteres para que o aplicativo faça 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 sete caracteres e depois selecionar uma previsão para uma solicitação da API Geocoding, o custo total será de US $0,01632 (4 * US$ 0,00283 Autocomplete por solicitação + US $0,005 Geocoding).1

Se o atraso de solicitações puder receber uma solicitação programática média inferior a quatro, siga as orientações para implementar o Place Autocomplete com a API Geocoding. Observe que o atraso de solicitações pode ser percebido como latência pelo usuário, que pode esperar ver previsões a cada nova pressionamento de tecla.

Considere usar as práticas recomendadas de desempenho para ajudar os usuários a conseguir a previsão que eles procuram em menos caracteres.


  1. Os custos listados aqui estão em USD. Consulte a página Faturamento da Plataforma Google Maps para ver as informações completas.

Práticas recomendadas de desempenho

As diretrizes a seguir descrevem maneiras de otimizar o desempenho do Place Autocomplete:

  • Adicione restrições de país, viés 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 escolhem as preferências de idioma no navegador ou no dispositivo móvel do usuário.
  • Se o Place Autocomplete estiver acompanhado por um mapa, você poderá influenciar o local por janela de visualização do mapa.
  • Em situações em que um usuário não escolhe uma das previsões do Autocomplete, geralmente porque nenhuma dessas previsões é o endereço do resultado desejado, você pode reutilizar a entrada original do usuário para tentar receber resultados mais relevantes:
    • Se você espera que o usuário insira apenas informações de endereço, reutilize a entrada original do usuário em uma chamada para a API Geocoding.
    • Se você espera 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 a viés de local.
    Outros cenários em que é melhor voltar para a API Geocoding incluem:
    • Usuários que inserem endereços de sublocal em países que não sejam a Austrália, a Nova Zelândia ou o Canadá. Por exemplo, o endereço dos EUA "123 Bowdoin St #456, Boston MA, EUA" não é suportado pelo Autocomplete. O Autocomplete é compatível com endereços de sublocal somente na Austrália, na Nova Zelândia e no Canadá. Os formatos de endereço aceitos nesses três países incluem "9/321 Pitt Street, Sydney, New South Wales, Austrália" ou "14/19 Langana Avenue, Browns Bay, Auckland, New Zealand" ou "145-112 Renfrew Dr, Markham, Ontario, Canada".
    • Usuários que inserem endereços com prefixos de trechos de via, como "23-30 29th St, Queens" em Nova York ou "47-380 Kamehameha Hwy, Kaneohe" na ilha de Kauai, no Havaí.

Solução de problemas

Embora possa ocorrer uma grande variedade de erros, a maioria dos erros prováveis do seu app geralmente é causada por erros de configuração, por exemplo, a chave de API errada foi usada ou a chave de API foi configurada incorretamente, ou erros de cota (o app excedeu a cota). Consulte Limites de uso para mais informações sobre cotas.

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