O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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 Query Autocomplete (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 ela.

O Query Autocomplete (legado) permite adicionar previsões de consulta geográfica em tempo real ao seu aplicativo. Em vez de procurar um local específico, o usuário pode digitar uma pesquisa categórica, como "pizza perto de São Paulo", e o serviço responde com uma lista de consultas sugeridas que correspondem à string. Como o Query Autocomplete (legado) pode corresponder a palavras completas e substrings, os aplicativos podem enviar consultas conforme o usuário digita para fornecer previsões instantâneas.

Uma solicitação do Query Autocomplete (legado) é um URL HTTP no 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 do Query 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 possíveis valores 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 compatí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 vai tentar usar o idioma preferencial, conforme especificado no cabeçalho Accept-Language.
- A API faz o possível para fornecer um endereço que seja legível para o usuário e os moradores locais. Para isso, ele retorna endereços no idioma local, transliterados para um script legível pelo usuário, se necessário, de acordo com o idioma preferido. Todos os outros endereços são retornados no idioma preferencial. Os componentes de endereço são todos 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

Define um ponto, como coordenadas latitude,longitude, ao redor do qual a pesquisa será feita. O serviço Places usa o local para priorizar 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 poderá ser substituído se o query contiver um local explícito, como Market in Barcelona. O uso de aspas ao redor da consulta também pode influenciar o peso dado a location e radius.
offset

A posição, no termo de entrada, do último caractere que o serviço usa para corresponder às 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 do 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 deve ser definido como a posição do cursor de texto.
raio

Define a distância (em metros) para retornar resultados de lugares. 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 priorizar os resultados dentro desse círculo. Os resultados fora da área definida ainda podem ser exibidos.

O raio será fixado automaticamente em 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

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'

Nos exemplos, substitua a chave de API pela sua própria chave.

Resposta do Query Autocomplete (legado)

As respostas do 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 da solicitação. 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 alterações.
`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` extra no objeto de resposta. Esse campo é retornado apenas para solicitações bem-sucedidas. Ele pode não ser retornado sempre, e o conteúdo está sujeito a alterações.

PlacesAutocompleteStatus

Códigos de status retornados pelo serviço.

OK: indicando que a solicitação de API funcionou.
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.

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 desejado. 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	Matriz<PlaceAutocompleteTerm>	Contém uma matriz de termos que identificam cada seção da descrição retornada (uma seção da descrição geralmente é encerrada 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 que se aplicam a esse lugar. Por exemplo: `[ "political", "locality" ]` ou `[ "establishment", "geocode", "beauty_salon" ]`. A matriz 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	Local de início 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 o local 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.
`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 desejado. 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.

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`