Preenchimento automático (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

Desenvolvedores do Espaço Econômico Europeu (EEE)

Se o endereço de faturamento estiver no Espaço Econômico Europeu, a partir de 8 de julho de 2025, os Termos de Serviço da Plataforma Google Maps para o EEE serão aplicáveis ao uso dos Serviços. A funcionalidade varia de acordo com a região. Saiba mais.

Importante:o uso dos dados retornados por esse endpoint está sujeito às políticas e atribuições aplicáveis da API Places.

Introdução

O preenchimento automático (novo) é um serviço da Web que retorna previsões de lugares e consultas em resposta a uma solicitação HTTP. Na solicitação, especifique uma string de pesquisa de texto e limites geográficos que controlam a área de pesquisa.

O Autocomplete (New) pode trazer palavras completas e substrings da entrada, sugerindo nomes e endereços de lugares, além de Plus Codes. À medida que a pessoa digita, os aplicativos enviam consultas e sugerem previsões de local e consulta instantaneamente.

A resposta do Autocomplete (novo) pode conter dois tipos de previsões:

• Previsões de lugares: lugares, como empresas, endereços e pontos de interesse, com base na string de texto de entrada e na área de pesquisa especificadas. As previsões de lugares são retornadas por padrão.
• Previsões de consulta: strings de consulta que correspondem à string de texto de entrada e à área de pesquisa. As previsões de consulta não são retornadas por padrão. Use o parâmetro de solicitação includeQueryPredictions para adicionar previsões de consulta à resposta.

Por exemplo, você chama o Autocomplete (novo) usando como entrada uma string que contém uma entrada parcial do usuário, "pizza siciliana", com a área de pesquisa limitada a São Francisco, CA. A resposta contém uma lista de previsões de lugares que correspondem à string de pesquisa e à área de pesquisa, como o restaurante "Sicilian Pizza Kitchen", além de detalhes sobre o lugar.

As previsões de lugar retornadas são projetadas para serem apresentadas ao usuário e ajudá-lo a selecionar o lugar desejado. Você pode fazer uma solicitação de Place Details (novo) para receber mais informações sobre qualquer uma das previsões de lugar retornadas.

A resposta também pode conter uma lista de previsões de consulta que correspondem à string e à área de pesquisa, como "Sicilian Pizza & Pasta". Cada previsão de consulta na resposta inclui o campo text, que contém uma string de Text Search recomendada. Use essa string como entrada para o Text Search (novo) para realizar uma pesquisa mais detalhada.

O APIs Explorer permite fazer solicitações em tempo real para que você se familiarize com a API e as opções dela:

Faça um teste

Solicitações do Autocomplete (New)

Uma solicitação de Autocomplete (New) é um HTTP POST para um URL no formato:

https://places.googleapis.com/v1/places:autocomplete

Transmita todos os parâmetros no corpo da solicitação JSON ou nos cabeçalhos como parte da solicitação POST. Exemplo:

curl -X POST -d '{
  "input": "pizza",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7937,
        "longitude": -122.3965
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Parâmetros aceitos

Parâmetro	Descrição
input*	String de texto para pesquisar (palavras completas, substrings, nomes de lugares, endereços, Plus Codes).
FieldMask (cabeçalho HTTP)	Lista separada por vírgulas que especifica quais campos retornar na resposta.
includedPrimaryTypes	Restringe os resultados a lugares que correspondem a um dos cinco tipos principais especificados.
includePureServiceAreaBusinesses	Se for verdadeiro, inclui empresas sem um local físico (empresas de serviço local). O padrão é "falso".
includeQueryPredictions	Se for verdadeiro, inclui previsões de lugar e de consulta na resposta. O padrão é "falso".
includedRegionCodes	Matriz de até 15 códigos de país de dois caracteres para restringir os resultados.
inputOffset	Deslocamento de caractere Unicode com base em zero da posição do cursor na string de entrada, influenciando as previsões. O padrão é o comprimento da entrada.
languageCode	Idioma preferido (código IETF BCP-47) para resultados. O padrão é o cabeçalho Accept-Language ou "en".
locationBias	Especifica uma área (círculo ou retângulo) para direcionar os resultados da pesquisa, permitindo resultados fora da área. Não pode ser usado com locationRestriction.
locationRestriction	Especifica uma área (círculo ou retângulo) para restringir os resultados da pesquisa. Os resultados fora dessa área são excluídos. Não pode ser usado com locationBias.
origin	Ponto de origem (latitude, longitude) usado para calcular a distância em linha reta (distanceMeters) até os destinos previstos.
regionCode	Código da região usado para formatar a resposta e sugestões de viés (por exemplo, "uk", "fr").
sessionToken	String gerada pelo usuário para agrupar chamadas do Autocomplete em uma sessão para fins de faturamento.

* Indica um campo obrigatório.

Sobre a resposta

O preenchimento automático (novo) retorna um objeto JSON como resposta. Na resposta:

• A matriz suggestions contém todos os lugares e consultas previstos em ordem com base na relevância percebida. Cada lugar é representado por um campo placePrediction, e cada consulta é representada por um campo queryPrediction.
• Um campo placePrediction contém informações detalhadas sobre uma única previsão de lugar, incluindo o ID de lugar e a descrição de texto.
  • Para corresponder melhor à entrada do usuário, conforme fornecido no parâmetro input, a descrição de texto de uma previsão de lugar pode incluir nomes alternativos para lugares, ruas e outros componentes de endereço. Esses nomes alternativos podem ser diferentes dos nomes retornados nos campos displayName e de endereço dos resultados do Place Details para o mesmo ID de lugar.
  • Nesse contexto, os nomes alternativos de alguns lugares podem estar em um idioma diferente do esperado com base no parâmetro languageCode, dependendo de quais nomes correspondem mais de perto à entrada do usuário.
• Um campo queryPrediction contém informações detalhadas sobre uma única previsão de consulta.

Observação:o Autocomplete (New) retorna cinco previsões no total, como placePredictions, queryPredictions ou uma combinação, dependendo da solicitação. Se a solicitação não definir includeQueryPredictions, a resposta vai incluir até cinco placePredictions. Se a solicitação definir includeQueryPredictions, a resposta vai incluir até cinco previsões em uma combinação de placePredictions e queryPredictions.

O objeto JSON completo está no formato:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }]
        },
      ...
    },
    {
      "queryPrediction": {
        "text": {
          "text": "Amoeba Music",
          "matches": [
            {
              "endOffset": 6
            }]
        },
        ...
    }
  ...]
}

Parâmetros obrigatórios

• entrada

  A string de texto em que a pesquisa será feita. Especifique palavras completas e substrings, nomes de lugares, endereços e Plus Codes. O serviço Autocomplete (New) retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância.

Parâmetros opcionais

• FieldMask

  Especifique a lista de campos a serem retornados na resposta criando uma máscara de campo de resposta. Transmita a máscara de campo de resposta ao método usando o cabeçalho HTTP X-Goog-FieldMask.

  Especifique uma lista separada por vírgulas de campos de sugestão a serem retornados. Por exemplo, para recuperar o suggestions.placePrediction.text.text e o suggestions.queryPrediction.text.text da sugestão.

    X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text

  Observação : não é permitido usar espaços na lista de campos.

  Use * para recuperar todos os campos.

    X-Goog-FieldMask: *

• includeFutureOpeningBusinesses

  Se true, retorna empresas que devem abrir no futuro. O padrão é false.

• includedPrimaryTypes

  Um lugar só pode ter um único tipo principal entre os listados na Tabela A ou na Tabela B. Por exemplo, o tipo principal pode ser "mexican_restaurant" ou "steak_house".

  Por padrão, a API retorna todos os lugares com base no parâmetro input, independente do valor do tipo principal associado ao lugar. Restrinja os resultados a um ou mais tipos principais transmitindo o parâmetro includedPrimaryTypes.

  Use esse parâmetro para especificar até cinco valores de tipo da Tabela A ou da Tabela B. Um lugar precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.

  Esse parâmetro também pode incluir, em vez disso, um de (regions) ou (cities). A coleção de tipos (regions) filtra áreas ou divisões, como bairros e códigos postais. A coleção de tipos (cities) filtra os lugares que o Google identifica como uma cidade.

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

  • Mais de cinco tipos foram especificados.
  • Qualquer tipo é especificado além de (cities) ou (regions).
  • Todos os tipos não reconhecidos são especificados.
  Observação:o parâmetro includedPrimaryTypes funciona apenas no tipo principal do lugar, não em todos os tipos associados a ele. Embora todo lugar tenha um tipo principal, nem todos os tipos principais são compatíveis com a API Places (nova). Os tipos compatíveis incluem aqueles listados na Tabela A ou na Tabela B.

• includePureServiceAreaBusinesses

  Se definido como true, a resposta inclui empresas que visitam ou entregam diretamente aos clientes, mas não têm um local físico. Se definido como false, a API retorna apenas empresas com um local físico.

• includeQueryPredictions

  Se true, a resposta vai incluir previsões de lugar e de consulta. O valor padrão é false, o que significa que a resposta inclui apenas previsões de lugar.

• includedRegionCodes

  Inclui apenas resultados da lista de regiões especificadas, apresentadas como uma matriz de até 15 valores de dois caracteres de ccTLD ("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:

      "includedRegionCodes": ["de", "fr"]

  Se você especificar locationRestriction e includedRegionCodes, os resultados vão estar na área de interseção das duas configurações.

  Observação: em caso de resultados inesperados com um código de país, verifique se o código usado inclui os países, territórios dependentes e áreas especiais de interesse geográfico. Para mais detalhes sobre códigos, acesse Wikipédia: Lista de códigos de país ISO 3166 ou a Plataforma de navegação on-line ISO.

• inputOffset

  O deslocamento de caracteres Unicode baseado em zero que indica a posição do cursor em input. A posição do cursor pode influenciar as previsões retornadas. Se estiver vazio, o padrão será o comprimento de input.

  Observação : na versão inicial de pré-lançamento restrito, essa propriedade era chamada de predictionTermOffset.

• languageCode

  O idioma preferido em que os resultados serão retornados. Os resultados podem estar em idiomas mistos se o idioma usado em input for diferente do valor especificado por languageCode ou se o lugar retornado não tiver uma tradução do idioma local para languageCode.

  • Use códigos de idioma IETF BCP-47 para especificar o idioma de preferência.
  • Se languageCode não for fornecido, a API vai usar o valor especificado no cabeçalho Accept-Language. Se nenhum for especificado, o padrão será en. Se você especificar um código de idioma inválido, a API vai retornar um erro INVALID_ARGUMENT.
  • O idioma preferido tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que eles são retornados. Isso também afeta a capacidade da API de corrigir erros de ortografia.
  • As previsões de lugar são formatadas de maneira diferente dependendo da entrada do usuário em cada solicitação.
    • Os termos correspondentes no parâmetro input são escolhidos primeiro, usando nomes alinhados com a preferência de idioma indicada pelo parâmetro languageCode quando disponível. Caso contrário, são usados nomes que melhor correspondem à entrada do usuário.
    • Os nomes de lugares podem ser formatados usando nomes alternativos para corresponder aos termos no parâmetro input, incluindo nomes em idiomas diferentes do indicado pelo parâmetro languageCode.
    • Os endereços são formatados no idioma local, em um script legível para o usuário, quando possível, somente depois que os termos correspondentes forem escolhidos para corresponder aos termos no parâmetro input.
    • Todos os outros endereços são retornados no idioma preferido, depois que os termos correspondentes são escolhidos para corresponder aos termos no parâmetro input. Se um nome não estiver disponível no idioma preferido, a API vai usar a correspondência mais próxima.

• locationBias ou locationRestriction

  É possível especificar locationBias ou locationRestriction, mas não ambos, para definir a área de pesquisa. Pense em locationRestriction como a especificação da região em que os resultados precisam estar e em locationBias como a especificação da região em que os resultados precisam estar próximos, mas podem estar fora da área.

  Observação : se você omitir locationBias e locationRestriction, o Preenchimento automático (novo) usará a polarização de IP por padrão. Com a inclusão de viés de IP, o preenchimento automático (novo) usa o endereço IP do dispositivo para incluir viés nos resultados.

  • locationBias

    Especifica uma área para pesquisar. Esse local serve como uma polarização, o que significa que resultados ao redor do local especificado podem ser retornados, incluindo resultados fora da área especificada.

  • locationRestriction

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

  Especifique a região locationBias ou locationRestriction como uma janela de visualização retangular ou como um círculo.

  • Um círculo é definido por um ponto central e um raio em metros. O raio precisa estar entre 0,0 e 50.000,0, incluindo esses dois valores. O valor padrão é 0,0. Para locationRestriction, é preciso definir o raio como um valor maior que 0,0. Caso contrário, a solicitação não retornará resultados.

    Exemplo:

    "locationBias": {
      "circle": {
        "center": {
          "latitude": 37.7937,
          "longitude": -122.3965
        },
        "radius": 500.0
      }
    }

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

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

    Por exemplo, esta janela de visualização inclui totalmente a cidade de Nova York:

    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 40.477398,
          "longitude": -74.259087
        },
        "high": {
          "latitude": 40.91618,
          "longitude": -73.70018
        }
      }
    }

• origem

  O ponto de origem para calcular a distância em linha reta até o destino (retornado como distanceMeters). Se esse valor for omitido, a distância em linha reta não será retornada. Precisa ser especificado como coordenadas de latitude e longitude:

  "origin": {
      "latitude": 40.477398,
      "longitude": -74.259087
  }

• regionCode

  O código regional usado para formatar a resposta, especificado como um valor de dois caracteres ccTLD ("domínio de nível superior"). A maioria dos códigos de 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").

  As sugestões também são tendenciosas com base em códigos regionais. O Google recomenda definir o regionCode de acordo com a preferência regional do usuário.

  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.

• sessionToken

  Os tokens de sessão são strings geradas pelo usuário que rastreiam chamadas do Autocomplete (New) como "sessões". O Autocomplete (novo) 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. Para mais informações, consulte Tokens de sessão.

Escolher parâmetros para influenciar os resultados

Os parâmetros do preenchimento automático (novo) podem influenciar os resultados da pesquisa de maneiras diferentes. A tabela a seguir fornece recomendações para o uso de parâmetros com base no resultado pretendido.

Parâmetro	Recomendação de uso
regionCode	Definido de acordo com a preferência regional do usuário.
includedRegionCodes	Definido para limitar os resultados à lista de regiões especificadas.
locationBias	Use quando os resultados forem preferidos em uma região ou ao redor dela. Se aplicável, defina a região como a janela de visualização do mapa que o usuário está olhando.
locationRestriction	Use somente quando os resultados fora de uma região não puderem ser retornados.
origin	Use quando uma distância em linha reta para cada previsão for pretendida. Observação:a distância não estará disponível para todas as previsões. Consulte Distância ausente na resposta.

Exemplos do Autocomplete (novo)

Restringir a pesquisa a uma área usando locationRestriction

Observação:o Autocomplete (New) usa a polarização de IP por padrão para controlar a área de pesquisa. Com a inclusão de preferências de IP, o preenchimento automático (novo) usa o endereço IP do dispositivo para incluir preferências nos resultados. Você também pode usar locationRestriction ou locationBias, mas não ambos, para especificar uma área de pesquisa.

locationRestriction especifica a área a ser pesquisada. Os resultados fora da área especificada não são retornados. No exemplo a seguir, você usa locationRestriction para limitar a solicitação a um círculo de 5.000 metros de raio centralizado em São Francisco:

curl -X POST -d '{
  "input": "Art museum",
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Todos os resultados das áreas especificadas estão contidos na matriz suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "museum",
            "point_of_interest"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w",
          "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w",
          "text": {
            "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 15
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "de Young Museum",
              "matches": [
                {
                  "endOffset": 15
                }
              ]
            },
            "secondaryText": {
              "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA"
            }
          },
          "types": [
            "establishment",
            "point_of_interest",
            "tourist_attraction",
            "museum"
          ]
        }
      },
      /.../
    ]
  }

Também é possível usar locationRestriction para restringir as pesquisas a uma janela de visualização retangular. O exemplo a seguir limita a solicitação ao centro de São Francisco:

  curl -X POST -d '{
    "input": "Art museum",
    "locationRestriction": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Os resultados estão na matriz suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q",
          "text": {
            "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 6,
                "endOffset": 16
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Asian Art Museum",
              "matches": [
                {
                  "startOffset": 6,
                  "endOffset": 16
                }
              ]
            },
            "secondaryText": {
              "text": "Larkin Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "museum",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc",
          "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc",
          "text": {
            "text": "International Art Museum of America, Market Street, San Francisco, CA, USA",
            "matches": [
              {
                "startOffset": 14,
                "endOffset": 24
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "International Art Museum of America",
              "matches": [
                {
                  "startOffset": 14,
                  "endOffset": 24
                }
              ]
            },
            "secondaryText": {
              "text": "Market Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "museum",
            "point_of_interest",
            "tourist_attraction",
            "art_gallery",
            "establishment"
          ]
        }
      }
    ]
  }

Polarizar a pesquisa para uma área usando locationBias

Com locationBias, o local serve como um direcionamento, o que significa que os resultados ao redor do local especificado podem ser retornados, incluindo resultados fora da área especificada. No exemplo a seguir, você envia uma solicitação com viés para o centro de São Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Os resultados agora contêm muito mais itens, incluindo resultados fora do raio de 5.000 metros:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "store",
          "establishment",
          "home_goods_store"
        ]
      }
    },
    {
      "placePrediction": {
        "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
        "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
        "text": {
          "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Telegraph Avenue, Berkeley, CA, USA"
          }
        },
        "types": [
          "electronics_store",
          "point_of_interest",
          "establishment",
          "home_goods_store",
          "store"
        ]
      }
    },
    ...
  ]
}

Você também pode usar locationBias para direcionar as pesquisas a uma janela de visualização retangular. O exemplo a seguir limita a solicitação ao centro de São Francisco:

  curl -X POST -d '{
    "input": "Amoeba",
    "locationBias": {
      "rectangle": {
        "low": {
          "latitude": 37.7751,
          "longitude": -122.4219
        },
        "high": {
          "latitude": 37.7955,
          "longitude": -122.3937
        }
      }
    }
  }' \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  https://places.googleapis.com/v1/places:autocomplete

Embora os resultados da pesquisa na janela de visualização retangular apareçam na resposta, alguns resultados estão fora dos limites definidos devido à polarização. Os resultados também estão contidos na matriz suggestions:

  {
    "suggestions": [
      {
        "placePrediction": {
          "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
          "text": {
            "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Haight Street, San Francisco, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw",
          "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw",
          "text": {
            "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Telegraph Avenue, Berkeley, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
      {
        "placePrediction": {
          "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI",
          "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI",
          "text": {
            "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "structuredFormat": {
            "mainText": {
              "text": "Amoeba Music",
              "matches": [
                {
                  "endOffset": 6
                }
              ]
            },
            "secondaryText": {
              "text": "Hollywood Boulevard, Los Angeles, CA, USA"
            }
          },
          "types": [
            "point_of_interest",
            "store",
            "establishment"
          ]
        }
      },
    /.../
    ]
  }

Usar includedPrimaryTypes

Use o parâmetro includedPrimaryTypes para especificar até cinco valores de tipo da Tabela A, da Tabela B ou apenas (regions) ou (cities). Um lugar precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.

No exemplo a seguir, você especifica uma string input de "Soccer" e usa o parâmetro includedPrimaryTypes para restringir os resultados a estabelecimentos do tipo "sporting_goods_store":

curl -X POST -d '{
  "input": "Soccer",
  "includedPrimaryTypes": ["sporting_goods_store"],
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 500.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

Se você omitir o parâmetro includedPrimaryTypes, os resultados poderão incluir estabelecimentos de um tipo que você não quer, como "athletic_field".

Solicitar previsões de consultas

As previsões de consulta não são retornadas por padrão. Use o parâmetro de solicitação includeQueryPredictions para adicionar previsões de consulta à resposta. Exemplo:

curl -X POST -d '{
  "input": "Amoeba",
  "includeQueryPredictions": true,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

A matriz suggestions agora contém previsões de lugar e de consulta, como mostrado acima em Sobre a resposta. Cada previsão de consulta inclui o campo text contendo uma string de Text Search recomendada. É possível fazer uma solicitação de Text Search (novo) para mais informações sobre qualquer uma das previsões de consulta retornadas.

Observação:as previsões de consulta não são retornadas quando o parâmetro includedRegionCodes é definido.

Usar origem

Neste exemplo, inclua origin na solicitação como coordenadas de latitude e longitude. Quando você inclui origin, o preenchimento automático (novo) inclui o campo distanceMeters na resposta, que contém a distância em linha reta de origin até o destino. Este exemplo define a origem como o centro de São Francisco:

curl -X POST -d '{
  "input": "Amoeba",
  "origin": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.7749,
        "longitude": -122.4194
      },
      "radius": 5000.0
    }
  }
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete

A resposta agora inclui distanceMeters:

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
        "text": {
          "text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
          "matches": [
            {
              "endOffset": 6
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Amoeba Music",
            "matches": [
              {
                "endOffset": 6
              }
            ]
          },
          "secondaryText": {
            "text": "Haight Street, San Francisco, CA, USA"
          }
        },
        "types": [
          "home_goods_store",
          "establishment",
          "point_of_interest",
          "store",
          "electronics_store"
        ],
        "distanceMeters": 3012
      }
    }
  ]
}

Encontrar empresas que vão abrir no futuro

O exemplo a seguir mostra uma solicitação de preenchimento automático (novo) para empresas que vão abrir no futuro em New Meadows, Idaho:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
  "input": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:autocomplete"

A resposta inclui detalhes sobre o lugar, mas não a data de inauguração.

{
  "suggestions": [
    {
      "placePrediction": {
        "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
        "text": {
          "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA",
          "matches": [
            {
              "endOffset": 32
            }
          ]
        },
        "structuredFormat": {
          "mainText": {
            "text": "Roberts Greenhouse and Tree Farm",
            "matches": [
              {
                "endOffset": 32
              }
            ]
          },
          "secondaryText": {
            "text": "McLain Street, New Meadows, ID, USA"
          }
        },
        "types": [
          "garden_center",
          "establishment",
          "service",
          "store",
          "point_of_interest"
        ]
      }
    }
  ]
}

Distância ausente na resposta

Em alguns casos, distanceMeters está ausente do corpo da resposta, mesmo quando origin está incluído na solicitação. Isso pode acontecer nos seguintes cenários:

• distanceMeters não está incluído nas previsões de route.
• distanceMeters não será incluído quando o valor for 0, que é o caso de previsões que estão a menos de 1 metro do local origin fornecido.

As bibliotecas de cliente que tentarem ler o campo distanceMeters de um objeto analisado vão retornar um campo com o valor 0. Para evitar enganar os usuários, não mostre uma distância zero.

Otimização do Autocomplete (novo)

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

Aqui estão algumas diretrizes gerais:

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

Otimização avançada de custos

Faça a implementação programática do Autocomplete (novo) para acessar SKU: preços de solicitação do Autocomplete e pedir resultados da API Geocoding sobre o lugar selecionado em vez do Place Details (novo). 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 e longitude ou do endereço do local selecionado pelo usuário, a API Geocoding fornece essas informações por menos do que uma chamada do Place Details (New).
• 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 Autocomplete (New) 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 Autocomplete (novo) com base em sessões com o Place Details (novo).
Como seu aplicativo requer o Place Details (novo), como o nome do lugar, o status da empresa ou o horário de funcionamento, sua implementação do Autocomplete (novo) precisa usar um token de sessão (de forma programática ou integrado aos widgets do JavaScript, Android ou iOS) por sessão, além das SKUs do Places aplicáveis, dependendo dos campos de dados de lugar que você solicitar.¹

Implementação do widget
O gerenciamento de sessões é integrado automaticamente aos widgets do JavaScript, Android ou iOS. Isso inclui as solicitações do Autocomplete (novo) e do Place Details (novo) na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos de dados do preenchimento automático (novo) necessários.

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

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

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

Sim

Implementar o Autocomplete (New) 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. Fazer quatro solicitações de preenchimento automático, além de uma chamada da API Geocoding sobre a previsão de lugar selecionada, custa menos do que o preenchimento automático por sessão (novo).¹

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 Autocomplete com base em sessões (novo) com o Place Details (novo).
Como o número médio de solicitações que você espera fazer antes que um usuário selecione uma previsão do Autocomplete (novo) excede o custo do preço por sessão, sua implementação do Autocomplete (novo) deve usar um token de sessão para as solicitações do Autocomplete (novo) e a solicitação associada do Place Details (novo) por 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 Autocomplete (novo) e do Place Details (novo) na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos necessários.

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

1. O ID de lugar da resposta do Autocomplete (novo)
2. O token de sessão usado na solicitação do Autocomplete (novo)
3. O parâmetro fields que especifica campos como endereço e geometria

Considere atrasar as solicitações do Autocomplete (New)
É possível adiar uma solicitação do Autocomplete (New) 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 de preenchimento automático (novo) para cada caractere depois que o usuário digita o terceiro caractere significa que, se o usuário digitar sete caracteres e selecionar uma previsão para a qual você faz uma solicitação da API Geocoding, o custo total será de quatro preenchimentos automáticos (novo) por solicitação + geocodificação.¹

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 Autocomplete (novo) 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. Para saber os custos, consulte as tabelas de preços da Plataforma Google Maps.

Práticas recomendadas de desempenho

As diretrizes a seguir descrevem como otimizar a performance do Autocomplete (New):

• Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Autocomplete (New). 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 Autocomplete (New) estiver acompanhado por um mapa, é possível direcionar o local por janela de visualização do mapa.
• Quando a pessoa não escolhe uma das previsões do Autocomplete (novo), geralmente porque nenhuma delas é o endereço que ela quer, você pode reutilizar a entrada do usuário original para tentar receber resultados mais relevantes:
  • Se quiser que o usuário insira apenas informações de endereço, reutilize a entrada do usuário original 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 de Place Details (novo). 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 subunidades, 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 Autocomplete (novo).
  • 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í.

Tendência de local

Influencie os resultados para uma área especificada transmitindo um parâmetro location e um parâmetro radius. Isso instrui o preenchimento automático (novo) a preferir mostrar resultados dentro da área definida. Os resultados fora da área definida ainda podem ser exibidos. Use o parâmetro includedRegionCodes para filtrar os resultados e mostrar apenas os lugares em um país específico.

Aviso:se radius não for fornecido, o parâmetro location será ignorado.

Os resultados de estabelecimentos geralmente não têm uma classificação alta o suficiente para aparecer nos resultados quando a área de pesquisa é grande. Se você quiser que os estabelecimentos apareçam em resultados mistos de estabelecimento/geocódigo, especifique um raio menor. Se preferir, use types=establishment para restringir os resultados apenas a estabelecimentos.

Restrição de local

Restrinja os resultados a uma área específica transmitindo um parâmetro locationRestriction.

Também é possível restringir os resultados à região definida por location e um parâmetro radius adicionando o parâmetro locationRestriction. Isso instrui o preenchimento automático (novo) a retornar apenas resultados nessa região.

Observação:as restrições de local são aplicadas apenas a rotas inteiras. Os resultados sintéticos de fora dela podem ser trazidos com base em uma rota que se sobreponha à restrição.

Confira!

Com o APIs Explorer, você pode fazer solicitações de amostra para se familiarizar com a API e as opções dela.

1. Selecione o ícone da API api no lado direito da página.

2. Se quiser, edite os parâmetros da solicitação.

3. Selecione o botão Executar. Na caixa de diálogo, escolha a conta que você quer usar para fazer a solicitação.

4. No painel do APIs Explorer, selecione o ícone de tela cheia fullscreen para expandir a janela do APIs Explorer.