Preenchimento automático (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

O Autocomplete (novo) retorna previsões de lugares em resposta a uma solicitação que inclui uma string de pesquisa de texto e limites geográficos que controlam a área de pesquisa. O preenchimento automático pode corresponder em palavras completas e substrings da entrada, resolvendo nomes de lugares, endereços e Plus Codes Seu aplicativo pode enviar consultas conforme o usuário digita, para fornecer previsões de local e consulta instantaneamente.

Por exemplo, você chama o Autocomplete usando como entrada uma string que contém uma entrada parcial do usuário, "Piz Sicilian", com a área de pesquisa limitada a São Francisco, CA. A resposta contém uma lista de locais previsões que correspondam à string de pesquisa e à área de pesquisa, como o restaurante chamada "Sicilian Pizza Kitchen".

As previsões de local retornadas são apresentadas ao usuário com o objetivo de ajudar na seleção do local desejado. Você pode fazer uma solicitação de Place Details (New) para receber mais informações sobre qualquer uma das previsões de local retornadas.

Solicitações de Autocomplete (novo)

Seu app pode conseguir uma lista de nomes de lugares previstos e/ou da API Autocomplete chamando PlacesClient.findAutocompletePredictions(), transmitir um FindAutocompletePredictionsRequest objeto. 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 Autocomplete (novo)

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

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

  • getFullText(CharacterStyle) retorna o texto completo da descrição de um lugar. Essa é uma combinação das como texto primário e secundário. Exemplo: "Torre Eiffel, Avenue Anatole France, Paris, França". Além disso, este método permite destacar as seções do descrições 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 algum 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, para 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 lugar é uma string identificador que identifica exclusivamente um local, que pode ser usado para recuperá-lo as Place novamente mais tarde. Para mais informações sobre IDs de lugar na Autocomplete, consulte Place Details (Novo). Para informações gerais informações sobre IDs de local, consulte a documentação ID de local geral.
  • 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 o 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 em sua 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; Tabela A ou Tabela B usada para filtrar os locais retornados na resposta. Um local precisa corresponder a um dos valores de tipo primário especificados para ser incluído na resposta.

    Um lugar só pode ter um tipo principal de tipos Tabela A ou a 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.
    • Quaisquer 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 os resultados da lista de países especificados, como uma lista de até 15 ccTLD ("domínio de nível superior") valores de dois caracteres. 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 estã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 caracteres 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á comprimento da consulta.

    Para definir o parâmetro de deslocamento de entrada, chame o método setInputOffset() ao criar o objeto FindAutocompletePredictionsRequest.

  • Viés de local ou restrição de local

    Você pode 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 especificar a região em que os resultados devem estar e o viés de localização especificando a região à qual os resultados devem estar próximos. A principal diferença é que com direcionamento de local, resultados fora da região especificada ainda poderão ser retornados.

    • Viés de local

      Especifica uma área a ser pesquisada. Esse local serve como um viés, não uma restrição, então os 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 o direcionamento de local ou a região de restrição de local como uma janela de visualização retangular ou em um círculo.

    • Um círculo é definido pelo ponto central e pelo raio em metros. O raio deve estar entre 0,0 e 50000,0, inclusive. O valor padrão é 0,0. Para a restrição de local, você deve definir o raio como um valor maior que 0,0. Caso contrário, a solicitação retorna nenhum resultado.

    • Um retângulo é uma janela de visualização de latitude e longitude, representada como dois diagonalmente ao lado de low e high pontos. Uma janela de visualização é considerada uma região fechada, ou seja, inclui seus limites. Os limites de latitude deve variar entre -90 e 90 graus, inclusive, e os limites de longitude deve variar entre -180 e 180 graus:

      • Se low = high, a janela de visualização consistirá nesse único ponto.
      • Se low.longitude > high.longitude, o intervalo de longitude está invertido (a janela de visualização cruza a linha de 180 graus de longitude).
      • Se low.longitude = -180 graus e high.longitude = 180 graus, a janela de visualização inclui todas as longitudes.
      • Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude está vazio.

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

  • Origem

    O ponto de origem a partir 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. 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 da região usado para formatar a resposta, inclusive a formatação do endereço, especificado como um ccTLD ("domínio de nível superior") um valor de dois caracteres. 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 os "Reino Unido da Grã-Bretanha e Irlanda do Norte").

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

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

  • Token da sessão

    Os tokens de sessão são strings geradas pelo usuário que rastreiam Autocomplete (novo) como "sessions". 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 para fins de faturamento. A sessão começa quando o usuário começa a digitar uma consulta e conclui quando seleciona um local. Cada sessão pode ter várias consultas, seguidas por uma seleção de local. Assim que uma sessão tiver for concluído, o token não será mais válido. o app precisa gerar um novo token para cada sessão. Recomendamos o uso de tokens de sessão para todas as transações sessões de preenchimento automá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 uma AutocompleteSessionToken para identificar cada sessão. Seu aplicativo deve passar um novo token de sessão após iniciar cada nova sessão e, em seguida, passar o mesmo token, junto com um ID de lugar, para a próxima chamada para fetchPlace() para recuperar detalhes do lugar 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 viés de local

O Autocomplete (novo) usa a polarização de IP por padrão para controlar a área de pesquisa. Com a polarização de IP, a API usa o endereço IP da dispositivo para influenciar os resultados. Opcionalmente, é possível usar location restrição ou viés de local, mas não para especificar uma área a ser pesquisada.

A restrição de local especifica a área a ser pesquisada. Resultados fora do especificado não serão retornadas. O exemplo a seguir usa a restrição de local para limitar a solicitação a um restrição de local circular com um raio de 5.000 metros centrado em São Francisco:

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

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

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

Com o direcionamento de localização, o local serve como um viés, o que significa que os resultados ao redor do local especificado pode ser retornado, incluindo resultados fora do área O próximo exemplo muda a solicitação anterior para usar a polarização de local:

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 principais para restringir os resultados de um sejam de um determinado tipo, como listado na Tabela A e Table B. É possível especificar uma matriz de até cinco valores. Se omitido, todos os tipos são retornados.

O exemplo a seguir especifica a string de consulta "Futebol" e usa o principal parâmetros de tipos 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ê pode não querer, 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 (acessado 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 Autocomplete (novo), mesmo sem um mapa. Se exibir um mapa, ele deve ser um mapa do Google. Quando você exibe previsões o serviço Autocomplete (novo) sem um mapa, deve incluir o logotipo do Google exibido alinhado com o campo de pesquisa/resultados. Para Para mais informações, consulte Como exibir o logotipo do Google e de atributos.