Pronto!

Para começar a desenvolver, acesse nossa documentação do desenvolvedor.

Ativar o serviço web da API do Google Places

Para começar, orientaremos você pelo Console do Desenvolvedor do Google para realizar algumas atividades:

  1. Criar ou selecionar um projeto
  2. Ativar o serviço web da API do Google Places
  3. Criar chaves apropriadas
Continuar

Place Autocomplete

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

Solicitações de Place Autocomplete

O serviço Place Autocomplete é parte do Google Places API Web Service e compartilha uma chave de API e cotas com o Google Places API Web Service.

O serviço Place Autocomplete pode corresponder a palavras completas e a substrings. Portanto, os aplicativos podem enviar consultas, à medida que o usuário digita, para fornecer previsões de local dinâmicas.

As previsões retornadas foram projetadas para serem apresentadas ao usuário para auxiliar na seleção do local desejado. É possível enviar uma solicitação de Place Details para obter mais informações sobre qualquer um dos locais retornados.

Uma solicitação de Place Autocomplete é um URL HTTP no 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 a saída como XML

Certos parâmetros são obrigatórios para iniciar uma solicitação de Place Autocomplete. 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

  • input — a string de texto a pesquisar. O serviço Place Autocomplete retornará correspondências possíveis com base nessa string e ordenará os resultados com base na relevância percebida.
  • key — a chave de API do aplicativo. Essa chave identifica o aplicativo para fins de gerenciamento de cotas. Consulte Obter uma chave para saber mais. Os clientes do Google Maps APIs Premium Plan devem usar o projeto de API criado como parte da compra do Premium Plan.

Parâmetros opcionais

  • offset — a posição do último caractere no termo de entrada que o serviço usa para corresponder às previsões. Por exemplo, se a entrada for “Google” e offset for 3, o serviço fará a correspondência em “Goo”. A string determinada por offset corresponde somente à primeira palavra no termo de entrada. Por exemplo, se a entrada for “Google abc” e offset for 3, o serviço tentará fazer a correspondência em “Goo abc”. Se nenhum offset for fornecido, o serviço usará o termo inteiro. O offset deve normalmente ser definido de acordo com a posição do cursor do texto.
  • location — o ponto em torno do qual deseja-se recuperar informações de local. Deve ser especificado como latitude,longitude.
  • radius — a distância (em metros) dentro da qual deve-se retornar resultados de local. Observe que definir um radius direciona os resultados para a área indicada, mas pode não restringir totalmente os resultados à área especificada. Leia Polarização de localidade e Restrição de localidade abaixo.
  • language — o código de idioma, indicando em que idioma os resultados devem ser retornados, se possível. As pesquisas também dão preferência ao idioma selecionado. Os resultados no idioma selecionado receberão uma classificação mais alta. Consulte a lista de idiomas permitidos e seus códigos. Observe que atualizamos com frequência os idiomas suportados, portanto, essa lista pode não estar completa. Se o idioma não for fornecido, o serviço Place Autocomplete tentará usar o idioma nativo do domínio de onde a solicitação for enviada.
  • types — os tipos de resultados de locais a retornar. Consulte Tipos de locais abaixo. Se nenhum tipo for especificado, todos serão retornados.
  • components — um agrupamento de locais ao qual se deseja restringir os resultados. Atualmente, é possível usar components para filtrar por país. O país deve ser passado como um código de país de dois caracteres, compatível com ISO 3166-1 Alpha-2. Por exemplo: components=country:fr restringiria os resultados a locais dentro da França.
  • strictbounds — retorna somente os locais que efetivamente estão dentro da região definida por location e radius. Essa é uma restrição, em vez de uma polarização, o que significa que os resultados de fora desta região não serão retornados, mesmo que correspondam à informação inserida pelo usuário.

Direcionamento de localização

Você pode direcionar resultados para um círculo especificado passando os parâmetros location e radius. Isso instrui o serviço Place Autocomplete a dar preferência a resultados dentro desse círculo. Os resultados fora da área definida ainda poderão ser exibidos. Pode-se usar o parâmetro components para filtrar os resultados e exibir apenas os locais dentro de um país especificado.

Dica: resultados de estabelecimentos normalmente não têm classificação alta o suficiente para serem exibidos em resultados quando a área de pesquisa é grande. Se a intenção é que estabelecimentos apareçam em resultados mistos de estabelecimento/código geográfico, é possível especificar um raio menor. Você também pode usar types=establishment para restringir os resultados somente a estabelecimentos.

Restrição de localidade

Você ainda pode restringir os resultados à região definida pelos parâmetros location e radius adicionando o parâmetro strictbounds. Assim, você instruirá o serviço Place Autocomplete a retornar somente os resultados de dentro dessa região.

Tipos de locais

É possível restringir os resultados de uma solicitação de Place Autocomplete para que sejam de determinado tipo passando um parâmetro types. O parâmetro especifica um tipo ou uma coleção de tipos, conforme listado nos tipos permitidos abaixo. Se nada for especificado, todos os tipos serão retornados. Em geral, somente um tipo é permitido. A exceção é que é possível combinar com segurança os tipos geocode e establishment, mas observe que isso terá o mesmo efeito que não especificar tipo nenhum. Os tipos permitidos são:

  • geocode instrui o serviço Place Autocomplete a retornar apenas resultados de geocodificação em vez de resultados de empresas. Geralmente, essa solicitação é usada para a desambiguação de resultados em que a localização especificada pode ser indeterminada.
  • address instrui o serviço Place Autocomplete a retornar apenas resultados de geocodificação com um endereço preciso. Geralmente, essa solicitação é usada quando se sabe que o usuário procurará um endereço totalmente especificado.
  • establishment instrui o serviço Place Autocomplete a retornar apenas resultados de empresas.
  • a coleção de tipos (regions) instrui o serviço Places a retornar qualquer resultado que corresponda aos seguintes tipos:
    • locality
    • sublocality
    • postal_code
    • country
    • administrative_area_level_1
    • administrative_area_level_2
  • a coleção de tipos (cities) instrui o serviço Places a retornar resultados que correspondam a locality ou administrative_area_level_3.

Exemplo de solicitações de preenchimento automático

Uma solicitação de estabelecimentos contendo a string "Amoeba" dentro de uma área centralizada em São Francisco, CA:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

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

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY

Uma solicitação de endereços contendo "Vict" com resultados na França:

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

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

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

Observe que você precisará substituir a chave de API nesses exemplos pela sua própria chave.

Respostas de Place Autocomplete

As respostas de Place Autocomplete são retornadas no formato indicado pelo sinalizador output dentro do caminho da solicitação de URL. Os resultados abaixo são uma indicação do que pode ser retornado para uma consulta com os seguintes parâmetros:

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
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>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <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>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

Uma resposta JSON contém dois elementos raiz:

  • status contém os metadados da solicitação. Consulte Códigos de status abaixo.
  • predictions contém uma matriz de locais, com informações sobre cada um deles. Consulte Resultados de Place Autocomplete para obter informações sobre esses resultados. A Google Places API Web Service retorna até 5 resultados.

Os elementos place_id são de interesse particular dentro dos resultados, já que podem ser usados para solicitar detalhes mais específicos sobre o local em uma consulta separada. Consulte Solicitações de Place Details.

Consulte Processar JSON com JavaScript para obter ajuda com a análise de respostas JSON.

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

  • Um único elemento <status> contém metadados da solicitação. Consulte Códigos de status abaixo.
  • Zero ou mais elementos <prediction>, cada um contendo informações sobre um único local. Consulte Resultados de Place Autocomplete para obter informações sobre esses resultados. A Google Places API Web Service retorna até 5 resultados.

Recomendamos o uso de json como sinalizador de saída preferencial, a menos que o aplicativo exija xml por algum motivo. O processamento de árvores XML exige certo cuidado para referenciar os nós e elementos adequados. Consulte Analisar XML com XPath para obter ajuda com o processamento de XML.

Códigos de status

O campo status dentro do objeto de resposta de Place Autocomplete contém o status da solicitação e pode conter informações de depuração para ajudar a rastrear o motivo de falhas de solicitações de Place Autocomplete. O campo status pode conter os seguintes valores:

  • OK indica que nenhum erro ocorreu e que pelo menos um resultado foi retornado.
  • ZERO_RESULTS indica que a pesquisa foi bem-sucedida, mas não retornou resultados. Isso pode ocorrer se a pesquisa receber bounds em um local remoto.
  • OVER_QUERY_LIMIT indica que a cota foi ultrapassada.
  • REQUEST_DENIED indica que a solicitação foi negada, geralmente devido à falta de um parâmetro key válido.
  • INVALID_REQUEST geralmente indica que o parâmetro input está ausente.

Mensagens de erro

Quando o serviço Places retorna um código de status diferente de OK, pode haver um campo error_message adicional dentro do objeto da resposta. Esse campo contém informações mais detalhadas sobre os motivos por trás do código de status.

Resultados de Place Autocomplete

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 nenhum resultado (como quando location é remoto), ele ainda retornará uma matriz predictions vazia. Respostas XML consistem em zero ou mais elementos <prediction>.

Cada resultado de previsão contém os seguintes campos:

  • description contém o nome legível para o resultado retornado. Para resultados de establishment, esse é normalmente o nome da empresa.
  • place_id é um identificador textual que identifica um local de forma exclusiva. Para recuperar informações sobre o local, passe esse identificador no campo placeId de uma solicitação de Google Places API Web Service. Para saber mais sobre IDs de local, consulte a visão geral de IDs de local.
  • reference contém um token exclusivo que pode ser usado para recuperar informações adicionais sobre esse local em uma solicitação de Place Details. Apesar de esse token identificar o local de forma exclusiva, o inverso não é verdadeiro. Um local pode ter muitos tokens de referência válidos. Não é garantido que o mesmo token seja retornado para qualquer local entre diferentes pesquisas. Observação: o campo reference está obsoleto e foi substituído por place_id. Consulte o aviso de obsolescência nesta página.
  • id contém um identificador estável exclusivo indicando esse local. Esse identificador não pode ser usado para recuperar informações sobre esse local, mas pode ser usado para consolidar dados desse local e verificar sua identidade entre pesquisas separadas. Observação: o id está obsoleto e foi substituído por place_id. Consulte o aviso de obsolescência nesta página.
  • terms contém uma matriz de termos identificando cada seção da descrição retornada (uma seção da descrição é geralmente terminada com uma vírgula). Cada entrada na matriz tem um campo value, contendo o texto do termo, e um campo offset, definindo a posição inicial desse termo na descrição, medida em caracteres Unicode.
  • types contém uma matriz de tipos que se aplicam a esse local. Por exemplo: [ "political", "locality" ] ou [ "establishment", "geocode" ].
  • matched_substrings contém uma matriz com valor de offset e length. Eles descrevem a localização do termo inserido no texto de resultado da previsão para poder destacá-lo, se desejado.

O parâmetro sensor

A Google Places API Web Service anteriormente exigia a inclusão do parâmetro sensor para indicar se o aplicativo usou um sensor para determinar a localização do usuário. Esse parâmetro não é mais obrigatório.

Enviar comentários sobre…

location_on
Google Places API Web Service