Preenchimento automático (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

O preenchimento automático (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. O app pode enviar consultas à medida que o usuário digita para fornecer previsões de local e consulta dinâmicas.

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 lugar que correspondem à string de pesquisa e à área de pesquisa, como o restaurante "Sicilian Pizza Kitchen".

As previsões de lugar retornadas foram projetadas para serem apresentadas ao usuário para ajudar na seleção do local desejado. É possível fazer uma solicitação de Place Details (New) para receber mais informações sobre qualquer uma das previsões de lugar retornadas.

Observação: o preenchimento automático (novo) está disponível no SDK do Places para Android versão 3.5.0 e mais recentes. Para mais informações, consulte Escolher a versão do SDK. Para mais informações sobre o uso das APIs do Kotlin adicionadas na versão 4.0.0, consulte a Visão geral de referência.

Solicitações de preenchimento automático (novas)

O app pode receber uma lista de nomes e/ou endereços de locais sugeridos da API Autocompletar ao chamar 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());
        })
    );

Observação: as chamadas feitas usando widgets do Place Autocomplete sempre chamam o Place Autocomplete, não o Place Autocomplete (Novo). As chamadas de widget não são afetadas pelo método de inicializaçã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.

Respostas de preenchimento automático (novas)

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 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 destacar nada.
• 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 Preenchimento automático, consulte Detalhes do lugar (novo). Para informações gerais sobre IDs de lugar, consulte a Visão geral do ID de lugar.
• getTypes() retorna a lista de tipos de lugar associados a esse lugar.
• getDistanceMeters() retorna a distância em linha reta em metros entre esse lugar e a origem especificada na solicitação.

Parâmetros obrigatórios

• Consulta

  A string de texto a pesquisar. Especifique palavras e substrings completas, nomes de lugares, endereços e Plus Codes. O serviço Autocomplete (novo) retorna correspondências possíveis com base nessa string e ordena os resultados com base na relevância percebida.

  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 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 de Tabela A ou Tabela 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

  Incluir apenas resultados da lista de países especificados, especificada como uma lista de até 15 valores de dois caracteres de ccTLDs ("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 serã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 do caractere Unicode com base 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 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 limitação ou uma preferência 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 em que os resultados precisam estar e no viés de local como a especificação da região em que os resultados precisam estar próximos. A principal diferença é que, com a polarização por local, os resultados fora da região especificada ainda podem ser retornados.

  • Viés de localização

    Especifica uma área para pesquisar. Esse local serve como uma polarização, não uma restrição. Portanto, os resultados fora da área especificada ainda podem ser retornados.

    Para definir o parâmetro de viés de localização, chame o método setLocationBias() ao criar o objeto FindAutocompletePredictionsRequest.

  • Restrição de local

    Especifica uma área para pesquisar. Os resultados fora da área especificada não são retornados.

    Para definir o parâmetro de restrição de local, chame o método setLocationRestriction() ao criar o objeto FindAutocompletePredictionsRequest.

  Especifique a região de viés ou restrição de local como uma janela de visualização retangular ou um círculo.

  • Um círculo é definido pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 500.000,0. O valor padrão é 0,0. Para a restrição de local, defina o raio como um valor maior que 0,0. Caso contrário, a solicitação não retorna resultados.

  • Um retângulo é uma viewport de latitude-longitude, representada como dois pontos low e high diagonalmente opostos. Uma viewport é considerada uma região fechada, ou seja, ela inclui o limite. Os limites de latitude precisam variar entre -90 e 90 graus, e os limites de longitude precisam variar entre -180 e 180 graus:

    Observação:os tipos de viés aceitos variam de acordo com a versão do SDK que você está usando. O CircularBounds só está disponível no Autocomplete (novo).
    • Se low = high, a viewport consiste nesse único ponto.
    • Se low.longitude > high.longitude, o intervalo de longitude é invertido, ou seja, a janela de visualização cruza a linha de longitude de 180 graus.
    • Se low.longitude = -180 graus e high.longitude = 180 graus, a viewport inclui todas as longitudes.
    • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude estará vazio.

    low e high precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma viewport vazia resulta em um erro.

• Origem

  O ponto de origem a partir do qual a distância em linha reta até o destino é calculada (acessado usando getDistanceMeters()). Se esse valor for omitido, a distância em linha reta não será retornada. Deve ser especificado como coordenadas de latitude e longitude:

  Para definir o parâmetro de origem, chame o método setOrigin() ao criar o objeto FindAutocompletePredictionsRequest.

• Código de região

  O código de região usado para formatar a resposta, incluindo a formatação do endereço, especificado como um valor de dois caracteres de ccTLD ("domínio de nível superior"). A maioria dos códigos ccTLD é idêntica aos códigos ISO 3166-1, com algumas exceções notáveis. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente, para a entidade "Reino Unido da Grã-Bretanha e da Irlanda do Norte").

  Observação:o código de região representa a região de origem da solicitação, não necessariamente a região de destino da consulta.

  Se você especificar um código de região inválido, a API vai retornar um erro INVALID_ARGUMENT. O parâmetro pode afetar os resultados com base na legislação aplicável.

  Para definir o parâmetro de código de região, chame o método setRegionCode() ao criar o objeto FindAutocompletePredictionsRequest.

• Token da sessão

  Os tokens de sessão são strings geradas pelo usuário que rastreiam as chamadas do Autocomplete (Novo) 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 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 preenchimento automático 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, junto com um ID de lugar, na chamada subsequente para fetchPlace() para recuperar os detalhes do lugar selecionado pelo usuário.

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

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

Exemplos de preenchimento automático (novo)

Usar restrição de local e viés de local

O preenchimento automático (novo) usa a distorção de IP por padrão para controlar a área de pesquisa. Com a distorção de IP, a API usa o endereço IP do dispositivo para distorcer os resultados. Você pode usar a restrição de local ou a inclinação 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 de local 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 a omissão de localização, o local serve como uma omissão, o que significa que os resultados em torno do local especificado podem ser retornados, incluindo resultados fora da área especificada. O próximo exemplo muda a solicitação anterior para usar a preferê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 primários

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 de tipos primários 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 a origem

Quando você inclui o parâmetro origin na solicitação, especificado como coordenadas de latitude e longitude, a API inclui a distância em linha reta da origem até o destino na resposta (acessado usando getDistanceMeters()). Neste exemplo, a origem é definida 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 Autocomplete (Novo) mesmo sem um mapa. Se você mostrar um mapa, ele deve ser do Google. Ao mostrar previsões do serviço Autocomplete (novo) sem um mapa, é necessário incluir o logotipo do Google exibido inline com o campo de pesquisa/resultados. Para mais informações, consulte Como exibir o logotipo e as atribuições do Google.