Place Autocomplete (legado)

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.

Observação: bibliotecas do lado do servidor e do cliente

A API Places também está disponível com o cliente Java, Python, Go e Node.js para serviços do Google Maps. A API Places e as bibliotecas de cliente são para uso em aplicativos de servidor.

Se você estiver criando um aplicativo do lado do cliente, confira o SDK do Places para Android (novo), o SDK do Places para iOS (novo) e a biblioteca Places da API Maps JavaScript.

O Place Autocomplete (legado) é um serviço da Web que retorna previsões de lugares em resposta a uma solicitação HTTP. A solicitação especifica uma string de pesquisa textual e limites geográficos opcionais. O serviço pode ser usado para fornecer funcionalidade de preenchimento automático para pesquisas geográficas baseadas em texto, retornando lugares como empresas, endereços e pontos de interesse conforme o usuário digita.

Solicitações do Place Autocomplete (legado)

O Place Autocomplete (legado) faz parte da API Places e compartilha uma chave de API e cotas com a API Places.

Observação:é possível usar o Place Autocomplete (legado) mesmo sem um mapa. Se você mostra um mapa, ele deve ser um mapa do Google. Ao mostrar previsões do Place Autocomplete (legado) sem um mapa, inclua o logotipo do Google exibido inline com o campo de pesquisa/resultados. Para mais informações, consulte Como mostrar o logotipo e as atribuições do Google.

O Place Autocomplete (legado) pode trazer palavras completas e substrings, 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 instantaneamente.

Você precisa formatar corretamente os Plus Codes. Isso significa que você precisa usar o escape de URL para o sinal de adição como %2B e para os espaços como %20.

• O código global é um código de área com quatro caracteres e um código local com, pelo menos, seis caracteres. Por exemplo, o código global de escape de URL 849VCWC8+R9 é 849VCWC8%2BR9.
• O código composto é um código local com, pelo menos, seis caracteres e um local explícito. Por exemplo, o código composto com escape de URL CWC8+R9 Mountain View, CA, USA é CWC8%2BR9%20Mountain%20View%20CA%20USA.

As previsões retornadas são projetadas para serem apresentadas ao usuário para ajudá-lo a selecionar o lugar que ele quer. É possível enviar uma solicitação de Place Details (legado) para mais informações sobre qualquer um dos lugares retornados.

Uma solicitação do Place Autocomplete (legado) é um URL HTTP do seguinte formato:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

em que output pode ser um dos seguintes valores:

• json (recomendado) indica a saída em JavaScript Object Notation (JSON)
• xml indica saída como XML

Alguns parâmetros são necessários para iniciar uma solicitação do Place Autocomplete (legado). Como é padrão em URLs, todos os parâmetros são separados usando o caractere E comercial (&). A lista de parâmetros e os valores possíveis estão enumerados abaixo.

Parâmetros obrigatórios

• entrada

  A string de texto em que a pesquisa será feita. O serviço Place Autocomplete retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância.

Parâmetros opcionais

• do Cloud

  Um agrupamento de lugares a que você quer restringir seus resultados. É possível usar componentes para filtrar até cinco países. Os países precisam ser transmitidos como um código de país de dois caracteres compatível com ISO 3166-1 Alfa-2. Por exemplo: components=country:fr restringe os resultados a lugares na França. Para transmitir vários países, é preciso usar vários filtros country:XX, com o caractere de barra vertical | como separador. Por exemplo, components=country:us|country:pr|country:vi|country:gu|country:mp restringe os resultados a lugares nos Estados Unidos e nos territórios organizados não incorporados.

  Observação:se você receber 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 (links em inglês).

• language

  O idioma em que os resultados serão retornados.

  • Consulte a lista de idiomas disponíveis. O Google atualiza os idiomas compatíveis com frequência, então esta lista pode não estar completa.
  • Se language não for fornecido, a API tentará usar o idioma preferido, conforme especificado no cabeçalho Accept-Language.
  • A API faz o possível para fornecer um endereço legível para o usuário e os moradores. Para isso, ele retorna endereços em português, transliterados para um script legível pelo usuário, se necessário, respeitando o idioma de preferência. Todos os outros endereços são retornados no idioma preferencial. Todos os componentes de endereço são retornados no mesmo idioma, que é escolhido no primeiro componente.
  • Se um nome não estiver disponível no idioma preferido, a API vai usar a correspondência mais próxima.
  • O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe retornar e na ordem em que eles são retornados. O geocodificador interpreta abreviações de maneira diferente dependendo do idioma, como as abreviações de tipos de rua ou sinônimos que podem ser válidos em um idioma, mas não em outro. Por exemplo, utca e tér são sinônimos de rua em húngaro.

• local

  O ponto em torno do qual as informações do lugar serão recuperadas. Precisa ser especificado como latitude,longitude. O parâmetro radius também precisa ser fornecido ao especificar um local. Se radius não for fornecido, o parâmetro location será ignorado.

  Ao usar a API Text Search, o parâmetro "location" poderá ser substituído se a consulta contiver um local explícito, como "Mercado em Barcelona".

• locationbias

  Prioriza resultados em uma área específica, especificando um raio mais lat/lng ou dois pares de lat/lng que representam os pontos de um retângulo. Se esse parâmetro não for especificado, a API vai usar a polarização de endereço IP por padrão.

  • Viés de IP: instrui a API a usar a tendência de endereço IP. Transmita a string ipbias. Essa opção não tem parâmetros adicionais.
  • Circular: uma string que especifica o raio em metros, além de latitude/longitude em graus decimais. Use o seguinte formato: circle:radius@lat,lng.
  • Retangular: uma string que especifica dois pares de latitude/longitude em graus decimais, representando os pontos sul/oeste e norte/leste de um retângulo. Use o seguinte formato:rectangle:south,west|north,east. Os valores leste/oeste são ajustados ao intervalo -180, 180, e os valores norte/sul são fixados no intervalo -90, 90.

• locationrestriction

  Restrinja os resultados a uma área especificada, informando um raio mais latitude/longitude ou dois pares de latitude/longitude que representam os pontos de um retângulo.

  • Circular: uma string que especifica o raio em metros, além de latitude/longitude em graus decimais. Use o seguinte formato: circle:radius@lat,lng.
  • Retangular: uma string que especifica dois pares de latitude/longitude em graus decimais, representando os pontos sul/oeste e norte/leste de um retângulo. Use o seguinte formato:rectangle:south,west|north,east. Os valores leste/oeste são ajustados ao intervalo -180, 180, e os valores norte/sul são fixados no intervalo -90, 90.

• offset

  A posição, no termo de entrada, do último caractere que o serviço usa para corresponder a previsões. Por exemplo, se a entrada for Google e o deslocamento for 3, o serviço vai corresponder a Goo. A string determinada pelo deslocamento é comparada apenas com a primeira palavra no termo de entrada. Por exemplo, se o termo de entrada for Google abc e o deslocamento for 3, o serviço vai tentar corresponder a Goo abc. Se nenhum deslocamento for fornecido, o serviço vai usar o termo inteiro. O deslocamento geralmente precisa ser definido como a posição do cursor de texto.

• origem

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

• raio

  Define a distância (em metros) dentro da qual os resultados de lugar serão retornados. Você pode influenciar os resultados de um círculo especificado ao transmitir um parâmetro location e radius. Isso instrui o serviço Places a preferir mostrar resultados dentro desse círculo. Os resultados fora da área definida ainda podem ser exibidos.

  O raio será automaticamente limitado a um valor máximo, dependendo do tipo de pesquisa e de outros parâmetros.

  • Preenchimento automático: 50.000 metros
  • Nearby Search:
    • com keyword ou name: 50.000 metros
    • sem keyword ou name
      • Até 50.000 metros, ajustado dinamicamente com base na densidade da área, independentemente do parâmetro rankby.
      • Ao usar rankby=distance, o parâmetro de raio não será aceito e resultará em um INVALID_REQUEST.
  • Query Autocomplete: 50.000 metros
  • Text Search: 50.000 metros

• região

  O código da regiã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 Irlanda do Norte").

• sessiontoken

  Uma string aleatória que identifica uma sessão de preenchimento automático para fins de faturamento.

  A sessão começa quando o usuário começa a digitar uma consulta e termina quando ele seleciona um lugar e uma chamada para o Place Details é feita. Cada sessão pode ter várias consultas, seguidas por uma seleção de lugar. As chaves de API usadas em cada solicitação de uma sessão precisam pertencer ao mesmo projeto do Console do Google Cloud. Após a conclusão de uma sessão, o token perde a validade. Seu aplicativo precisa gerar um novo token para cada sessão. Se o parâmetro sessiontoken for omitido ou você reutilizar um token de sessão, a sessão será cobrada como se nenhum token tivesse sido fornecido, e cada solicitação será faturada separadamente.

  Recomendamos as seguintes diretrizes:

  • Use tokens de sessão em todas as sessões de preenchimento automático.
  • Gere um novo token para cada sessão. Recomendamos usar um UUID da versão 4.
  • Verifique se as chaves de API usadas para todas as solicitações do Place Autocomplete e do Place Details em uma sessão pertencem ao mesmo projeto do console do Cloud.
  • Transmita um token de sessão exclusivo para cada sessão nova. Se você usar o mesmo token para mais de uma sessão, cada solicitação vai ser faturada individualmente.

• strictbounds

  Retorna apenas os lugares que estão estritamente dentro da região definida por location e radius. Essa é uma restrição, não uma tendência, o que significa que os resultados fora dessa região não serão retornados, mesmo que correspondam à entrada do usuário.

• tipos

  Você pode restringir os resultados de uma solicitação do Place Autocomplete a um determinado tipo transmitindo o parâmetro types. Esse parâmetro especifica um tipo ou uma coleção de tipos, conforme listado em Tipos de lugares. Se nada for especificado, todos os tipos serão retornados.

  Um lugar só pode ter um único tipo principal entre os tipos listados na Tabela 1 ou Tabela 2. Por exemplo, um hotel que serve comida pode ser retornado apenas com types=lodging, e não com types=restaurant.

  Para o valor do parâmetro types, é possível especificar:

  • Até cinco valores da Tabela 1 ou da Tabela 2. Para vários valores, separe cada um com uma | (barra vertical). Exemplo:

    types=book_store|cafe

  • Qualquer filtro único compatível na Tabela 3. Não é possível misturar coleções de tipos.

  Observação:embora geocode e establishment façam parte da Tabela 2, eles não podem ser combinados com nenhum outro tipo nas Tabelas 1, 2 ou 3 nos filtros de solicitação do Place Autocomplete.

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

  • Mais de cinco tipos foram especificados.
  • Há tipos não reconhecidos.
  • Qualquer tipo da Tabela 1 ou da Tabela 2 é misturado com qualquer um dos filtros da Tabela 3.
  Observação:o parâmetro types 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 (New). Os tipos aceitos incluem os listados na Tabela 1 ou na Tabela 2.

Exemplos do Place Autocomplete (legado)

Uma solicitação de estabelecimentos que contêm a string "Amoeba" em uma área centralizada em São Francisco, CA:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

A mesma solicitação, restrita a resultados em um raio de 500 metros de Ashbury St & Haight St, São Francisco:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

Uma solicitação de endereços contendo "Vict" com resultados em francês:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

Uma solicitação de cidades que contêm "Vict" com resultados em português do Brasil:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

Substitua a chave de API nesses exemplos pela sua.

Resposta do Place Autocomplete (legado)

As respostas do Place Autocomplete (Legacy) são retornadas no formato indicado pela flag output no caminho do URL da solicitação. Os resultados abaixo são indicativos do que pode ser retornado para uma consulta com os seguintes parâmetros:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

XML

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

   

PlacesAutocompleteResponse

Campo	Obrigatório	Tipo	Descrição
predictions	required	Array<PlaceAutocompletePrediction>	Contém uma matriz de previsões. Consulte PlaceAutocompletePrediction para mais informações.
status	required	PlacesAutocompleteStatus	Contém o status da solicitação e pode incluir informações de depuração para ajudar a rastrear o motivo da falha. Consulte PlacesAutocompleteStatus para mais informações.
error_message	opcional	string	Quando o serviço retorna um código de status diferente de OK<, pode haver um campo error_message adicional no objeto de resposta. Esse campo contém informações mais detalhadas sobre os motivos do código de status fornecido. Esse campo nem sempre é retornado, e o conteúdo dele está sujeito a mudanças.
info_messages	opcional	Array<string>	Quando o serviço retorna mais informações sobre a especificação da solicitação, pode haver um campo info_messages adicional no objeto de resposta. Esse campo só é retornado para solicitações bem-sucedidas. Ele nem sempre é retornado, e o conteúdo está sujeito a mudanças.

De especial interesse nos resultados estão os elementos place_id, que podem ser usados para solicitar detalhes mais específicos sobre o lugar usando uma consulta separada. Consulte Solicitações do Place Details (legado).

Uma resposta XML consiste em um único elemento <AutocompletionResponse> com dois tipos de elementos filhos:

• Um único elemento <status> contém metadados sobre a solicitação. Consulte Códigos de status abaixo.
• Zero ou mais elementos <prediction>, cada um contendo informações sobre um único lugar. Consulte Resultados do Place Autocomplete (Legacy) para mais informações sobre esses resultados. A API Places retorna até cinco resultados.

Recomendamos que você use json como a flag de saída preferida, a menos que seu aplicativo exija xml por algum motivo. O processamento de árvores XML exige cuidado para que você faça referência aos nós e elementos corretos. Consulte Processamento de XML com XPath para receber ajuda.

O componente de endereço street_number às vezes não está presente nas respostas de Place Details (Legacy) para IDs de lugares em algumas previsões de preenchimento automático. Isso normalmente acontece quando o endereço não pode ser interpolado por um lugar. Nesses casos, "route" vai constar na matriz types da previsão. No caso de previsões de preenchimento automático com um número na descrição (correspondência da consulta de entrada), a resposta do Place Details (legado) para o ID de lugar só vai incluir o número do endereço se a matriz types da previsão tiver pelo menos um destes objetos:

• street_address
• premise
• establishment

PlacesAutocompleteStatus

Códigos de status retornados pelo serviço.

• OK: indicando que a solicitação de API foi concluída.
• ZERO_RESULTS, indicando que a pesquisa foi bem-sucedida, mas não retornou resultados. Isso pode ocorrer se a pesquisa recebeu limites em um local remoto.
• INVALID_REQUEST: indicando que a solicitação de API estava corrompida, geralmente devido à ausência do parâmetro input.
• OVER_QUERY_LIMIT indicando qualquer uma das seguintes opções:
  • Você excedeu os limites de QPS.
  • O faturamento não foi ativado na sua conta.
  • O crédito mensal de US $200 ou um limite de uso definido pelo próprio usuário foi excedido.
  • A forma de pagamento fornecida não é mais válida (por exemplo, o cartão de crédito expirou).
  Consulte as perguntas frequentes do Maps para mais informações sobre como resolver esse erro.
• REQUEST_DENIED indica que o pedido foi recusado, geralmente porque:
  • A solicitação não tem uma chave de API.
  • O parâmetro key é inválido.
• UNKNOWN_ERROR: indicando um erro desconhecido.

Quando o serviço Places retorna resultados JSON de uma pesquisa, ele os coloca em uma matriz predictions. Mesmo que o serviço não retorne resultados (por exemplo, se o location for remoto), ele ainda vai retornar uma matriz predictions vazia. As respostas XML consistem em zero ou mais elementos <prediction>.

PlaceAutocompletePrediction

Campo	Obrigatório	Tipo	Descrição
description	required	string	Contém o nome legível por humanos do resultado retornado. Para resultados de establishment, geralmente é o nome da empresa. O conteúdo precisa ser lido no estado em que se encontra. Não analise o endereço formatado de maneira programática.
matched_substrings	required	Array<PlaceAutocompleteMatchedSubstring>	Uma lista de substrings que descrevem o local do termo inserido no texto do resultado da previsão, para que o termo possa ser destacado, se escolhido. Consulte PlaceAutocompleteMatchedSubstring para mais informações.
structured_formatting	required	PlaceAutocompleteStructuredFormat	Fornece texto pré-formatado que pode ser mostrado nos resultados de preenchimento automático. O conteúdo precisa ser lido no estado em que se encontra. Não analise o endereço formatado de maneira programática. Consulte PlaceAutocompleteStructuredFormat para mais informações.
terms	required	Array<PlaceAutocompleteTerm>	Contém uma matriz de termos que identificam cada seção da descrição retornada. Uma seção da descrição geralmente termina com uma vírgula. Cada entrada na matriz tem um campo value, que contém o texto do termo, e um campo offset, que define a posição inicial desse termo na descrição, medida em caracteres Unicode. Consulte PlaceAutocompleteTerm para mais informações.
distance_meters	opcional	número inteiro	A distância em linha reta em metros da origem. Esse campo é retornado apenas para solicitações feitas com um origin.
place_id	opcional	string	um identificador textual que identifica um local de forma exclusiva. Para recuperar informações sobre o lugar, transmita esse identificador no campo placeId de uma solicitação de API do Places. Para mais informações sobre IDs de lugar, consulte a visão geral de IDs de lugar.
reference	opcional	string	O uso de reference foi descontinuado. Consulte place_id.
types	opcional	Array<string>	Contém uma matriz de tipos aplicáveis a este lugar. Por exemplo: [ "political", "locality" ] ou [ "establishment", "geocode", "beauty_salon" ]. O array pode conter vários valores. Saiba mais sobre os tipos de lugar.

PlaceAutocompleteMatchedSubstring

Campo	Obrigatório	Tipo	Descrição
length	required	número	Comprimento da substring correspondente no texto do resultado da previsão.
offset	required	número	Localização inicial da substring correspondente no texto do resultado da previsão.

PlaceAutocompleteStructuredFormat

Campo	Obrigatório	Tipo	Descrição
main_text	required	string	Contém o texto principal de uma previsão, geralmente o nome do lugar.
main_text_matched_substrings	required	Array<PlaceAutocompleteMatchedSubstring>	Contém uma matriz com o valor offset e length. Eles descrevem a localização do termo inserido no texto do resultado da previsão para que ele possa ser destacado se for escolhido. Consulte PlaceAutocompleteMatchedSubstring para mais informações.
secondary_text	opcional	string	Contém o texto secundário de uma previsão, geralmente o local do lugar.
secondary_text_matched_substrings	opcional	Array<PlaceAutocompleteMatchedSubstring>	Contém uma matriz com o valor offset e length. Eles descrevem o local do termo inserido no texto do resultado da previsão para que o termo possa ser destacado, se escolhido. Consulte PlaceAutocompleteMatchedSubstring para mais informações.

PlaceAutocompleteTerm

Campo	Obrigatório	Tipo	Descrição
offset	required	número	Define a posição inicial desse termo na descrição, medida em caracteres Unicode.
value	required	string	O texto do termo.

Otimização do Place Autocomplete (legado)

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

Aqui estão algumas diretrizes gerais:

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

Otimização avançada de custos

Faça a implementação programática do Place Autocomplete (legado) para acessar SKU: Autocomplete – preços por solicitação e peça resultados da API Geocoding sobre o lugar selecionado em vez do Place Details (legado). O preço por solicitação combinado com a API Geocoding é 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 (legado).
• Se os usuários selecionarem uma previsão de preenchimento automático em média com quatro solicitações de Place Autocomplete (Legacy) ou menos, 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 Place Autocomplete (legado) 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 Place Autocomplete (legado) com base em sessões com o Place Details (legado).
Como seu aplicativo requer o Place Details (Legacy), como o nome do lugar, o status da empresa ou o horário de funcionamento, sua implementação do Place Autocomplete (Legacy) deve usar um token de sessão (programaticamente ou integrado aos widgets do JavaScript, Android ou iOS) por sessão, além das SKUs de dados 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 Place Autocomplete (legado) e do Place Details (legado) na previsão selecionada. Especifique o parâmetro fields para garantir que você está pedindo apenas os campos de dados do Place Autocomplete (Legacy) necessários.

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

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

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

Sim

Implemente o Place Autocomplete (legado) de forma programática sem tokens de sessão e chame 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: por solicitação mais uma chamada da API Geocoding sobre a previsão de lugar selecionada é menor que o custo por sessão do Place Autocomplete (legado) por sessão.¹

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 Place Autocomplete com base em sessões (legado) com o Place Details (legado).
Como o número médio de solicitações que você espera fazer antes que um usuário selecione uma previsão do Place Autocomplete (legado) excede o custo do preço por sessão, sua implementação do Place Autocomplete (legado) deve usar um token de sessão para as solicitações do Place Autocomplete (legado) e a solicitação associada do Place Details (legado) 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 Place Autocomplete (Legacy) e do Place Details (Legacy) 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 Place Autocomplete (legado). Ao solicitar Place Details (legado) sobre a previsão selecionada, inclua os seguintes parâmetros:

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

Considere atrasar as solicitações do Place Autocomplete (legado)
É possível adiar uma solicitação do Place Autocomplete (legado) 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 do Place Autocomplete (legado) 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 de API da API Geocoding, o custo total será de quatro solicitações do Place Autocomplete (legado) por solicitação + Geocoding.¹

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 Place Autocomplete (legado) 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 Place Autocomplete (legado):

• Adicione restrições de país, direcionamento de local e preferência de idioma (para implementações programáticas) à implementação do Place Autocomplete (legado). 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 Place Autocomplete (Legacy) 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 Place Autocomplete (legado), geralmente porque nenhuma delas é o endereço que ela quer, você pode reutilizar a entrada 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 (legado). 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 subinstalações, como endereços de unidades ou apartamentos específicos em um prédio. Por exemplo, o endereço tcheco "Stroupežnického 3191/17, Praha" gera uma previsão parcial no Place Autocomplete (legado).
  • 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

Direcione os resultados para uma área específica transmitindo um parâmetro location e um parâmetro radius. Isso instrui o Place Autocomplete (legado) 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 informado, 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 especificada transmitindo um parâmetro locationRestriction.

Você também pode restringir os resultados à região definida por location e um parâmetro radius adicionando o parâmetro strictbounds. Isso instrui o Place Autocomplete (legado) a retornar apenas resultados dentro dessa 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.