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 fazer correspondências com palavras completas e substrings da entrada, resolvendo nomes, endereços e Plus Codes de lugares. À medida que a pessoa digita, seu aplicativo pode enviar consultas para fornecer previsões de local e consulta instantaneamente.

Por exemplo, você chama o preenchimento automático usando como entrada uma string que contém uma entrada parcial do usuário, "piz siciliano", com a área de pesquisa limitada a São Francisco, CA. A resposta contém uma lista de sugestões de lugar que correspondem à string e à área de pesquisa, como o restaurante chamado "Sicilian Pizza Kitchen".

As previsões de lugares retornadas são projetadas para serem apresentadas ao usuário com o objetivo de ajudar na escolha do lugar que você quer. Você pode fazer uma solicitação Place Details (New) para receber mais informações sobre qualquer uma das previsões de lugar retornadas.

Solicitações de Autocomplete (novas)

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

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

Respostas de preenchimento automático (nova)

A API retorna um FindAutocompletePredictionsResponse em uma Task. O objeto 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 correspondente à consulta e aos critérios de filtro.

Chame os métodos abaixo para extrair detalhes de cada lugar previsto:

  • getFullText(CharacterStyle) retorna o texto completo de uma descrição de lugar. Essa é uma combinação dos textos 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 o estilo que você quiser usando CharacterStyle. O parâmetro CharacterStyle é opcional. Defina-o como nulo se você não precisar de destaque.
  • getPrimaryText(CharacterStyle) retorna o texto principal que descreve um lugar. Geralmente é o nome do lugar. Exemplos: "Torre Eiffel" e "123 Pitt Street".
  • 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: "A Avenue Anatole France, Paris, França" e "Sydney, Nova Gales do Sul".
  • getPlaceId() retorna o ID do lugar previsto. Um ID de lugar é um identificador textual que identifica um local de forma exclusiva, que você pode usar 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 dos IDs de lugar.
  • getTypes() retorna a lista de tipos de lugar associados a esse lugar.
  • getDistanceMeters() retorna a distância em linha reta em metros entre o lugar e a origem especificada na solicitação.

Parâmetros obrigatórios

  • Consulta

    A string de texto na qual pesquisar. Especifique palavras completas e substrings, nomes de lugares, endereços e Plus Codes. O serviço Autocomplete (novo) retorna 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 dos tipos Tabela A ou Tabela B usada para filtrar os locais retornados na resposta. Um local precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.

    Um local só pode ter um único tipo principal dos tipos Tabela A ou Tabela B associadas a ele. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house".

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

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

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

  • Países

    Incluir apenas resultados da lista de países especificados, definidos como uma lista de até 15 valores de ccTLD ("domínio de nível superior") de dois caracteres. Se omitida, 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 ficarão localizados na área de interseção das duas configurações.

    Para definir o parâmetro de países, chame o método setCountries() ao criar o objeto FindAutocompletePredictionsRequest.

  • Deslocamento de entrada

    O deslocamento de caractere Unicode baseado em zero que indica a posição do cursor na consulta. A posição do cursor pode influenciar quais previsões são retornadas. Se estiver vazio, o padrão será o tamanho 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 um direcionamento ou restrição de local, mas não ambos, para definir a área de pesquisa. Pense na restrição de local como a especificação da região dentro dos resultados, e o viés de localização como a especificação da região à qual os resultados precisam estar próximos. A principal diferença é que, com o viés de localização, resultados fora da região especificada ainda podem ser retornados.

    • Viés de local

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

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

    • Restrição de local

      Especifica uma área a ser pesquisada. 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 tendência de local ou a região de restrição de local como uma janela de visualização retangular ou como um círculo.

    • Um círculo é definido pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 50.000,0. 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 retornará resultados.

    • Um retângulo é uma janela de visualização de latitude e longitude, representada como dois pontos diagonalmente opostos low e high. Uma janela de visualização é considerada uma região fechada, ou seja, que inclui o limite dela. Os limites de latitude precisam variar de -90 a 90 graus, e os limites de longitude precisam variar de -180 a 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 incluirá todas as longitudes.
      • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude ficará vazio.

      Preencha low e high, e a caixa representada não pode ficar vazia. Uma janela de visualização vazia resulta em erro.

  • Origem

    O ponto de origem do qual 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 ccTLD ("domínio de nível superior"). A maioria dos códigos ccTLD é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente, para a entidade "Reino Unido da Grã-Bretanha e Irlanda do Norte").

    Se você especificar um código de região inválido, a API 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 regional, 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 de preenchimento automático (novas) como "sessões". O Autocomplete usa tokens de sessão para agrupar as fases de consulta e seleção de uma pesquisa de preenchimento automático do usuário em uma sessão discreta para fins de faturamento. A sessão começa quando o usuário 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. Após a conclusão de uma sessão, o token não é mais válido, e seu aplicativo 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 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 esse mesmo token com um ID de lugar na chamada seguinte para fetchPlace() a fim de recuperar o Place Details para o local que foi selecionado pelo usuário.

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

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

Exemplos de preenchimento automático (novo)

Usar restrição de local e direcionamento de local

Por padrão, o Autocomplete (novo) usa a polarização de IP para controlar a área de pesquisa. Com o direcionamento de IP, a API usa o endereço IP do dispositivo para direcionar os resultados. Também é possível usar a restrição de local ou a viés de local, mas não ambas, para especificar uma área a ser pesquisada.

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

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

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

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

Com o viés de localização, a localização serve como viés, o que significa que é possível retornar resultados ao redor do local especificado, incluindo resultados fora da área especificada. O próximo exemplo altera a solicitação anterior para usar o viés 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 de tipos primários 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 são retornados.

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

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

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

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

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

Se você omitir o parâmetro de tipos principais, os resultados poderão incluir estabelecimentos de um tipo que 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 a distância em linha reta da origem ao destino na resposta (acessada usando getDistanceMeters()). Este exemplo define a origem como o centro de São Francisco:

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

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

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

Atribuições

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