Este produto ou recurso está no status Legado. Para mais informações sobre o status Legado, consulte Produtos e recursos legados. Para migrar para a API Places (nova), consulte o guia de migração.

Preenchimento automático de consulta (legado)

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

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

A API Places também está disponível com os clientes 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, API Maps JavaScript.

O preenchimento automático de consultas (legado) pode ser usado para fornecer uma previsão de consulta para pesquisas geográficas baseadas em texto, retornando consultas sugeridas conforme você digita.

Solicitações do Query Autocomplete (legado)

O Query Autocomplete (legado) faz parte da API Places (legada) e compartilha uma chave de API e uma cota com a API Places (legada).

Com o Query Autocomplete (legado), é possível adicionar previsões de consultas geográficas em tempo real ao seu aplicativo. Em vez de pesquisar um local específico, o usuário pode digitar uma pesquisa por categoria, como "pizza perto de São Paulo", e o serviço responde com uma lista de consultas sugeridas que correspondem à string. Como o preenchimento automático de consultas (legado) pode corresponder a palavras completas e substrings, os aplicativos podem enviar consultas enquanto o usuário digita para fornecer previsões instantâneas.

Uma solicitação de preenchimento automático de consultas (legado) é um URL HTTP do seguinte formato:

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

em que output pode ser json ou xml.

Alguns parâmetros são obrigatórios para iniciar uma solicitação de preenchimento automático de consultas (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

language

O idioma em que os resultados serão retornados.
- Consulte a lista de idiomas disponíveis. O Google atualiza os idiomas aceitos 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 locais. Para isso, ele retorna endereços em português, transliterados para um script legível pelo usuário, se necessário, observando o idioma preferido. Todos os outros endereços são retornados no idioma preferido. 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 usará a correspondência mais próxima.
- 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. 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

Define um ponto, como coordenadas latitude,longitude, ao redor do qual pesquisar. O serviço Places usa o local para direcionar a pesquisa e mostrar resultados na área definida por location e radius. Os resultados fora da área definida ainda podem ser exibidos.

O parâmetro location pode ser substituído se o query contiver um local explícito, como Market in Barcelona. O uso de aspas na consulta também pode influenciar o peso atribuído a location e radius.
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 ajuste é comparada apenas com a primeira palavra do termo de entrada. Por exemplo, se o termo de entrada for Google abc e o deslocamento for 3, o serviço tentará fazer a correspondência com Goo abc. Se nenhum valor for fornecido, o serviço usará todo o termo. O deslocamento geralmente precisa ser definido como a posição do cursor de texto.
raio

Define a distância (em metros) dentro da qual os resultados de lugares 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, ajustados dinamicamente com base na densidade da área, independente 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

Exemplos de Query Autocomplete (legado)

URL

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'

Uma solicitação "Pizza perto de Par", com resultados em francês:

URL

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &language=fr
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&language=fr&key=YOUR_API_KEY'

Substitua a chave de API nesses exemplos pela sua.

Resposta do Query Autocomplete (legado)

As respostas do recurso de preenchimento automático de consultas (legado) são retornadas no formato indicado pela flag output no caminho da solicitação de URL. Os resultados abaixo são retornados para uma consulta com os seguintes parâmetros:

URL

https://maps.googleapis.com/maps/api/place/queryautocomplete/json
  ?input=pizza%20near%20par
  &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/queryautocomplete/json?input=pizza%20near%20par&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "pizza near Paris, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Paris, France",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Paris" },
            { "offset": 18, "value": "France" },
          ],
      },
      {
        "description": "pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Pari Chowk" },
            { "offset": 23, "value": "NRI City" },
            { "offset": 33, "value": "Omega II" },
            { "offset": 43, "value": "Noida" },
            { "offset": 50, "value": "Uttar Pradesh" },
            { "offset": 65, "value": "India" },
          ],
      },
      {
        "description": "pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 22 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Disneyland Park, Disneyland Drive, Anaheim, CA, USA",
            "secondary_text_matched_substrings":
              [{ "length": 3, "offset": 16 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Disneyland Park" },
            { "offset": 28, "value": "Disneyland Drive" },
            { "offset": 46, "value": "Anaheim" },
            { "offset": 55, "value": "CA" },
            { "offset": 59, "value": "USA" },
          ],
      },
      {
        "description": "pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 36 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France",
            "secondary_text_matched_substrings":
              [{ "length": 3, "offset": 30 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Cathédrale Notre-Dame de Paris" },
            { "offset": 43, "value": "Parvis Notre-Dame - place Jean-Paul-II" },
            { "offset": 83, "value": "Paris" },
            { "offset": 90, "value": "France" },
          ],
      },
      {
        "description": "pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France",
        "matched_substrings":
          [{ "length": 5, "offset": 0 }, { "length": 3, "offset": 11 }],
        "structured_formatting":
          {
            "main_text": "pizza",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France",
            "secondary_text_matched_substrings": [{ "length": 3, "offset": 5 }],
          },
        "terms":
          [
            { "offset": 0, "value": "pizza" },
            { "offset": 6, "value": "near" },
            { "offset": 11, "value": "Paris Beauvais Airport" },
            { "offset": 35, "value": "Route de l'Aéroport" },
            { "offset": 56, "value": "Tillé" },
            { "offset": 63, "value": "France" },
          ],
      },
    ],
  "status": "OK",
}

XML

      
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>pizza near Paris, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>11</offset>
  </term>
  <term>
   <value>France</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Paris, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Pari Chowk</value>
   <offset>11</offset>
  </term>
  <term>
   <value>NRI City</value>
   <offset>23</offset>
  </term>
  <term>
   <value>Omega II</value>
   <offset>33</offset>
  </term>
  <term>
   <value>Noida</value>
   <offset>43</offset>
  </term>
  <term>
   <value>Uttar Pradesh</value>
   <offset>50</offset>
  </term>
  <term>
   <value>India</value>
   <offset>65</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Pari Chowk, NRI City, Omega II, Noida, Uttar Pradesh, India</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Disneyland Park</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Disneyland Drive</value>
   <offset>28</offset>
  </term>
  <term>
   <value>Anaheim</value>
   <offset>46</offset>
  </term>
  <term>
   <value>CA</value>
   <offset>55</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>59</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>22</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Disneyland Park, Disneyland Drive, Anaheim, CA, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>16</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Cathédrale Notre-Dame de Paris</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Parvis Notre-Dame - place Jean-Paul-II</value>
   <offset>43</offset>
  </term>
  <term>
   <value>Paris</value>
   <offset>83</offset>
  </term>
  <term>
   <value>France</value>
   <offset>90</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>36</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Cathédrale Notre-Dame de Paris, Parvis Notre-Dame - place Jean-Paul-II, Paris, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>30</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>pizza near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</description>
  <term>
   <value>pizza</value>
   <offset>0</offset>
  </term>
  <term>
   <value>near</value>
   <offset>6</offset>
  </term>
  <term>
   <value>Paris Beauvais Airport</value>
   <offset>11</offset>
  </term>
  <term>
   <value>Route de l'Aéroport</value>
   <offset>35</offset>
  </term>
  <term>
   <value>Tillé</value>
   <offset>56</offset>
  </term>
  <term>
   <value>France</value>
   <offset>63</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <matched_substring>
   <offset>11</offset>
   <length>3</length>
  </matched_substring>
  <structured_formatting>
   <description>pizza</description>
   <subdescription>near Paris Beauvais Airport, Route de l'Aéroport, Tillé, France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
   <subdescription_matched_substring>
    <offset>5</offset>
    <length>3</length>
   </subdescription_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

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>.

PlacesQueryAutocompleteResponse

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 conter 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 por trás do código de status fornecido. Esse campo nem sempre é retornado, e o conteúdo dele está sujeito a mudanças.
`info_messages`	opcional	Matriz<string>	Quando o serviço retorna mais informações sobre a especificação da solicitação, pode haver um campo `info_messages` extra 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.

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 malformada, geralmente devido à ausência do parâmetro input.
OVER_QUERY_LIMIT indicando 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 indicando que o pedido foi recusado, geralmente porque:
- Está faltando uma chave de API na solicitação.
- 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 (como se o location fosse remoto), ele ainda retorna 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 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 a localização do termo inserido no texto do resultado da previsão, para que o termo possa ser destacado se desejado. Consulte PlaceAutocompleteMatchedSubstring para mais informações.
`structured_formatting`	required	PlaceAutocompleteStructuredFormat	Fornece texto pré-formatado que pode ser mostrado nos resultados do 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 só é retornado 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 `reference` foi descontinuado. Consulte place_id.
`types`	opcional	Matriz<string>	Contém uma matriz de tipos aplicáveis a este lugar. Por exemplo: `[ "political", "locality" ]` ou `[ "establishment", "geocode", "beauty_salon" ]`. A matriz pode conter vários valores. Saiba mais sobre 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 desejado. 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 a localização do termo inserido no texto do resultado da previsão para que ele possa ser destacado, se desejado. Consulte PlaceAutocompleteMatchedSubstring para mais informações.

PlaceAutocompleteTerm

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

Preenchimento automático de consulta (legado) Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Solicitações do Query Autocomplete (legado)

Parâmetros obrigatórios

entrada

Parâmetros opcionais

language

local

offset

raio

Exemplos de Query Autocomplete (legado)

URL

curl

URL

curl

Resposta do Query Autocomplete (legado)

URL

curl

JSON

XML

PlacesQueryAutocompleteResponse

predictions

status

error_message

info_messages

PlacesAutocompleteStatus

PlaceAutocompletePrediction

description

matched_substrings

structured_formatting

terms

distance_meters

place_id

reference

types

PlaceAutocompleteMatchedSubstring

length

offset

PlaceAutocompleteStructuredFormat

main_text

main_text_matched_substrings

secondary_text

secondary_text_matched_substrings

PlaceAutocompleteTerm

offset

value

Preenchimento automático de consulta (legado)

`predictions`

`status`

`error_message`

`info_messages`

`description`

`matched_substrings`

`structured_formatting`

`terms`

`distance_meters`

`place_id`

`reference`

`types`

`length`

`offset`

`main_text`

`main_text_matched_substrings`

`secondary_text`

`secondary_text_matched_substrings`

`offset`

`value`