O serviço de preenchimento automático (novo) é um serviço da Web que retorna lugares previsões e de consultas em resposta a uma solicitação HTTP. Na solicitação, especifique um texto string de pesquisa e limites geográficos que controlam a área de pesquisa.
O serviço Autocomplete (novo) pode encontrar correspondências em palavras completas e substrings da entrada, resolvendo nomes de lugares, endereços e Plus Codes Assim, os aplicativos podem enviar conforme o usuário digita, para fornecer previsões imediatas de locais e consultas.
A resposta da API Autocomplete (novo) pode conter dois tipos das previsões:
- Previsões de locais: lugares, como empresas, endereços e pontos de interesse, com base na string de texto de entrada e na área de pesquisa especificadas. As previsões de lugares são retornados por padrão.
- Previsões de consulta: strings de consulta que correspondem à string de texto de entrada e
área de pesquisa. As previsões de consulta não são retornadas por padrão. Use o
o parâmetro de solicitação
includeQueryPredictions
para adicionar previsões de consulta ao resposta.
Por exemplo, você chama a API usando como entrada uma string que contém uma entrada parcial do usuário, "Piz Sicilian", com a área de pesquisa limitada a São Francisco, CA. A resposta, então, contém uma lista de previsões de local que correspondem à string de pesquisa e à área de pesquisa, como o restaurante chamado "Sicilian Pizza Kitchen", com detalhes sobre o local.
As previsões de local retornadas são projetadas para serem apresentadas ao usuário com o objetivo de ajudar na seleção do local desejado. É possível fazer uma Place Details (novo) para obter mais informações sobre qualquer uma das previsões de local retornadas.
A resposta também pode conter uma lista de previsões de consulta que correspondam ao
string de pesquisa e área de pesquisa, como "Sicilian Pizza & Massa". Cada previsão de consulta no
A resposta inclui o campo text
, que contém uma string de pesquisa de texto recomendada. Use isso
string como entrada para
Text Search (novo)
para realizar uma pesquisa mais detalhada.
O APIs Explorer permite que você faça solicitações ativas para se familiarizar com a API e a Opções de API:
Faça um testeSolicitações de Autocomplete (novo)
Uma solicitação de Autocomplete (novo) é uma solicitação HTTP POST para um URL em o formulário:
https://places.googleapis.com/v1/places:autocomplete
Transmita todos os parâmetros no corpo da solicitação JSON ou nos cabeçalhos como parte da solicitação POST. Exemplo:
curl -X POST -d '{ "input": "pizza", "locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Sobre a resposta
O Autocomplete (novo) retorna um objeto JSON como resposta. Na resposta:
- A matriz
suggestions
contém todos os lugares e consultas previstos em ordem com base na relevância percebida. Cada local é representado por umaplacePrediction
e cada consulta é representada por um campoqueryPrediction
. - Um campo
placePrediction
contém informações detalhadas sobre um único previsão de lugar, incluindo o ID do lugar e a descrição em texto. - Um campo
queryPrediction
contém informações detalhadas sobre um único previsão da consulta.
O objeto JSON completo está no formato:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 }] }, ... }, { "queryPrediction": { "text": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 }] }, ... } ...] }
Parâmetros obrigatórios
-
entrada
A string de texto na qual pesquisar. Especifique palavras completas e substrings, nomes de lugares, endereços e Plus Codes. O serviço Autocomplete (novo) retorna correspondências possíveis de acordo com essa string e ordena os resultados com base em sua relevância percebida.
Parâmetros opcionais
-
includedPrimaryTypes
Um lugar só pode ter um único tipo principal dentre os listados em Tabela A ou Tabela B. Por exemplo: o tipo principal pode ser
"mexican_restaurant"
ou"steak_house"
.Por padrão, a API retorna todos os locais com base no parâmetro
input
, independentemente do valor do tipo principal associado ao lugar. Restringir os resultados para que correspondam a um determinado tipo primário ou principais, transmitindo o parâmetroincludedPrimaryTypes
.Use esse parâmetro para especificar até cinco valores de tipo da Tabela A ou Tabela B. Um lugar deve corresponder a um dos valores de tipo primário especificados a serem incluídos na resposta.
Em vez disso, esse parâmetro também pode incluir
(regions)
ou(cities)
. A coleção de tipos(regions)
filtra áreas ou divisões, como bairros e códigos postais. A coleção de tipos(cities)
filtra os lugares que o Google identifica como uma cidade.A solicitação será rejeitada com um erro
INVALID_REQUEST
se:- Mais de cinco tipos foram especificados.
- Qualquer tipo é especificado, além de
(cities)
ou(regions)
. - Todos os tipos não reconhecidos foram especificados.
-
includeQueryPredictions
Se
true
, a resposta inclui previsões de local e consulta. O padrão o valor éfalse
, o que significa que a resposta inclui apenas previsões de lugar. -
includedRegionCodes
Incluir apenas os resultados da lista de regiões especificadas, definidas como uma matriz de até 15 ccTLD ("domínio de nível superior") valores de dois caracteres. Se omitido, nenhuma restrição será aplicada à resposta. Por exemplo: para limitar as regiões à Alemanha e à França:
"includedRegionCodes": ["de", "fr"]
Se você especificar
locationRestriction
eincludedRegionCodes
, os resultados estão localizados na área de interseção das duas configurações. -
inputOffset
O deslocamento de caracteres Unicode baseado em zero que indica a posição do cursor em
input
. A posição do cursor pode influenciar quais previsões são retornadas. Se estiver vazio, o padrão será comprimento deinput
. -
languageCode
O idioma no qual os resultados serão retornados. Os resultados podem estar em idiomas mistos se o idioma usado no
input
for diferente do valor especificado porlanguageCode
ou se o lugar retornado não tiver uma tradução do idioma local paralanguageCode
.- Você deve usar o IETF Códigos de idioma BCP-47 para especificar o idioma preferido.
-
Se
languageCode
não for fornecido, a API usará o valor especificado no CabeçalhoAccept-Language
. Se nenhum deles for especificado, o padrão seráen
: Se você especificar um código de idioma inválido, a API retornará umaINVALID_ARGUMENT
erro. - O idioma preferido tem uma pequena influência no conjunto de resultados que a API escolhe retornar e a ordem em que eles são retornados. Isso também afeta a capacidade da API de corrigir erros de ortografia.
-
A API tenta fornecer um endereço que seja legível tanto para o usuário quanto para
população local e, ao mesmo tempo, reflete a entrada do usuário. As previsões de lugares são
formatados de forma diferente dependendo da entrada do usuário em cada solicitação.
-
Os termos correspondentes no parâmetro
input
são escolhidos primeiro, usando nomes alinhados com a preferência de idioma indicada pelo parâmetrolanguageCode
ao disponíveis. Caso contrário, são usados nomes que melhor correspondem à entrada do usuário. -
Os endereços são formatados no idioma local, em um script legível pelo usuário
quando possível, somente depois que termos correspondentes forem escolhidos para corresponder aos termos no
parâmetro
input
. -
Todos os outros endereços serão retornados no idioma de preferência, depois que os termos correspondentes forem
foram escolhidos para corresponder aos termos no parâmetro
input
. Se um nome não for disponível no idioma preferido, a API usa a correspondência mais próxima.
-
Os termos correspondentes no parâmetro
locationBias ou locationRestriction
É possível especificar
locationBias
oulocationRestriction
, mas não ambos, para definir a área de pesquisa. Pense emlocationRestriction
como uma forma de a região onde os resultados devem estar, elocationBias
como especificando a região a que os resultados precisam estar próximos, mas que podem estar fora na área.locationBias
Especifica uma área a ser pesquisada. Essa localização serve como um viés, o que significa resultados em torno do local especificado possam ser retornados, incluindo resultados fora da área especificada.
locationRestriction
Especifica uma área a ser pesquisada. Os resultados fora da área especificada não são retornados.
Especifique a região
locationBias
oulocationRestriction
como um uma janela de visualização retangular ou em um círculo.Um círculo é definido pelo ponto central e pelo raio em metros. O raio deve estar entre 0,0 e 50000,0, inclusive. O valor padrão é 0,0. Para o
locationRestriction
, você deve definir o raio como um valor maior que 0,0. Caso contrário, a solicitação retorna nenhum resultado.Exemplo:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Um retângulo é uma janela de visualização de latitude e longitude, representada como dois diagonalmente oposta a
low
e pontos altos. Uma janela de visualização é considerada uma região fechada, ou seja, inclui seus limites. Os limites de latitude deve variar entre -90 e 90 graus, inclusive, e os limites de longitude deve variar entre -180 e 180 graus:- Se
low
=high
, a janela de visualização consistirá nesse único ponto. - Se
low.longitude
>high.longitude
, o intervalo de longitude está invertido (a janela de visualização cruza a linha de 180 graus de longitude). - Se
low.longitude
= -180 graus ehigh.longitude
= 180 graus, a janela de visualização inclui todas as longitudes. - Se
low.longitude
= 180 graus ehigh.longitude
= -180 graus, o intervalo de longitude está vazio.
low
ehigh
precisam ser preenchidos, e a caixa representada não pode ficar em branco. Uma janela de visualização vazia resulta em erro.Por exemplo, esta janela de visualização abrange totalmente Nova York:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Se
-
origem
O ponto de origem a partir do qual calcular a distância em linha reta até o destino (retornado como
distanceMeters
). Se esse valor for omitido, a distância em linha reta não será retornada. Deve ser especificado como coordenadas de latitude e longitude:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
O código da região usado para formatar a resposta, especificado como um ccTLD ("domínio de nível superior") um valor de dois caracteres. 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 os "Reino Unido da Grã-Bretanha e Irlanda do Norte").
Se você especificar um código de região inválido, a API retornará um
INVALID_ARGUMENT
. erro. O parâmetro pode afetar os resultados com base na legislação aplicável. -
sessionToken
Os tokens de sessão são strings geradas pelo usuário que acompanham o preenchimento automático (Novo) chamadas como "sessões". O Autocomplete (novo) usa tokens de sessão para agrupar as fases de consulta e seleção de uma pesquisa de preenchimento automático do usuário em uma sessão discreta para para fins de cobrança. Para mais informações, consulte Tokens de sessão.
Exemplos de preenchimento automático (novo)
Usar locationRestriction e locationBias
A API usa a polarização de IP por padrão para controlar a área de pesquisa. Com a polarização de IP, a API usa o
o endereço IP do dispositivo para influenciar os resultados. Opcionalmente, você pode usar
locationRestriction
ou locationBias
, mas não ambos, para especificar uma área a ser pesquisada.
locationRestriction
especifica a área a ser pesquisada. Resultados fora da área especificada
não serão retornadas. No exemplo a seguir, você usa locationRestriction
para limitar o
solicitação para um círculo de 5.000 metros em um raio centrado em São Francisco:
curl -X POST -d '{ "input": "Amoeba", "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Todos os resultados das áreas especificadas estão contidos na matriz suggestions
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "store", "point_of_interest", "electronics_store" ] } } ] }
Com locationBias
, a localização serve como um viés, ou seja, os resultados ao redor do
local especificado pode ser retornado, incluindo resultados fora da área especificada. Nos próximos
exemplo, você altera a solicitação para usar locationBias
:
curl -X POST -d '{ "input": "Amoeba", "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Os resultados agora contêm muito mais itens, incluindo fora do raio de 5.000 metros:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
UsarincludedPrimaryTypes
Use o parâmetro includedPrimaryTypes
para especificar até cinco valores de tipo
Tabela A,
Tabela B,
ou apenas (regions)
ou apenas (cities)
. O lugar precisa corresponder a um dos
valores do tipo primário sejam incluídos na resposta.
No exemplo a seguir, você especifica uma string input
de
"Futebol" e usar o parâmetro includedPrimaryTypes
para restringir os resultados a
estabelecimentos do tipo "sporting_goods_store"
:
curl -X POST -d '{ "input": "Soccer", "includedPrimaryTypes": ["sporting_goods_store"], "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Se você omitir o parâmetro includedPrimaryTypes
, os resultados poderão incluir
estabelecimentos de um tipo que você não quer, como "athletic_field"
.
Solicitar previsões de consulta
As previsões de consulta não são retornadas por padrão. Usar a includeQueryPredictions
para adicionar previsões de consulta à resposta. Exemplo:
curl -X POST -d '{ "input": "Amoeba", "includeQueryPredictions": true, "locationBias": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
A matriz suggestions
agora contém previsões de lugares e consultas
conforme mostrado acima em Sobre a resposta. Cada previsão de consulta
inclui o campo text
, que contém uma string de pesquisa de texto recomendada. É possível fazer uma
Text Search (novo)
para obter mais informações sobre qualquer uma das previsões de consulta retornadas.
Usar origem
Neste exemplo, inclua origin
na solicitação como coordenadas de latitude e longitude.
Quando você inclui origin
, a API inclui o campo distanceMeters
na
resposta que contém a distância em linha reta do origin
até o destino.
Este exemplo define a origem como o centro de São Francisco:
curl -X POST -d '{ "input": "Amoeba", "origin": { "latitude": 37.7749, "longitude": -122.4194 }, "locationRestriction": { "circle": { "center": { "latitude": 37.7749, "longitude": -122.4194 }, "radius": 5000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
A resposta agora inclui distanceMeters
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
Confira!
Com o APIs Explorer, você pode fazer solicitações de amostra para se familiarizar com a API e as opções de API.
- Selecione o ícone da API,
, no lado direito da página.
- Como opção, expanda Mostrar parâmetros padrão e defina
O parâmetro
fields
à máscara de campo. - É possível editar o Corpo da solicitação.
- Selecione o botão Execute. No pop-up, escolha a conta que você quer usar para fazer a solicitação.
No painel do APIs Explorer, selecione o ícone de expansão,
para expandir a janela do APIs Explorer.