O serviço Autocomplete (novo) é um serviço da Web que retorna previsões de locais e de consultas em resposta a uma solicitação HTTP. Na solicitação, especifique uma string de pesquisa de texto e limites geográficos que controlam a área de pesquisa.
O serviço de preenchimento automático (novo) pode corresponder a palavras completas e substrings da entrada, resolvendo nomes de lugares, endereços e Plus Codes. Portanto, os aplicativos podem enviar consultas à medida que o usuário digita para fornecer previsões de local e consulta dinâmicas.
A resposta da API Autocomplete (novo) pode conter dois tipos de previsão:
- Previsões de lugares: lugares, como empresas, endereços e pontos de interesse, com base na string de texto de entrada especificada e na área de pesquisa. As previsões de lugares são retornadas 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 parâmetro de solicitação
includeQueryPredictions
para adicionar previsões de consulta à resposta.
Por exemplo, você chama a API usando como entrada uma string que contém uma entrada parcial do usuário, "Sicilian piz", com a área de pesquisa limitada a São Francisco, CA. A resposta contém uma lista de previsões de lugar que correspondem à string de pesquisa e à área de pesquisa, como o restaurante "Sicilian Pizza Kitchen", além de detalhes sobre o lugar.
As previsões de lugar retornadas foram projetadas para serem apresentadas ao usuário para ajudar na seleção do local desejado. É possível fazer uma solicitação de Place Details (New) para receber mais informações sobre qualquer uma das previsões de lugar retornadas.
A resposta também pode conter uma lista de previsões de consulta que correspondem à string de pesquisa e à área de pesquisa, como "Sicilian Pizza & Pasta". Cada previsão de consulta na
resposta inclui o campo text
, que contém uma string de pesquisa de texto recomendada. Use essa
string como entrada para a
Text Search (New)
para fazer uma pesquisa mais detalhada.
O API Explorer permite fazer solicitações em tempo real para que você se familiarize com a API e as opções dela:
Faça um testeSolicitações de preenchimento automático (novas)
Uma solicitação de Autocomplete (Nova) é uma solicitação HTTP POST para um URL no formato:
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 preenchimento automático (novo) retorna um objeto JSON como resposta. Na resposta:
- A matriz
suggestions
contém todas as consultas e lugares previstos em ordem com base na relevância percebida. Cada lugar é representado por um campoplacePrediction
, e cada consulta é representada por um campoqueryPrediction
. - Um campo
placePrediction
contém informações detalhadas sobre uma única previsão de lugar, incluindo o ID do lugar e a descrição do texto. - Um campo
queryPrediction
contém informações detalhadas sobre uma única previsão de 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 a pesquisar. Especifique palavras e substrings completas, 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 na relevância percebida.
Parâmetros opcionais
-
FieldMask
Crie uma máscara de campo de resposta para especificar a lista de campos a serem retornados na resposta. Transmita a máscara de campo de resposta para o método usando o cabeçalho HTTP
X-Goog-FieldMask
.Especifique uma lista separada por vírgulas de campos de sugestão a serem retornados. Por exemplo, para extrair o
suggestions.placePrediction.place
esuggestions.placePrediction.text
da sugestão.X-Goog-FieldMask: places.displayName,places.formattedAddress
Use
*
para recuperar todos os campos.X-Goog-FieldMask: *
-
includedPrimaryTypes
Um lugar só pode ter um único tipo principal dentre os listados na Tabela A ou na Tabela B. Por exemplo, o tipo principal pode ser
"mexican_restaurant"
ou"steak_house"
.Por padrão, a API retorna todos os lugares com base no parâmetro
input
, independentemente do valor do tipo principal associado ao lugar. Restringir os resultados a um determinado tipo principal ou tipos principais, transmitindo o parâmetroincludedPrimaryTypes
.Use esse parâmetro para especificar até cinco valores de tipo da Tabela A ou da Tabela B. Um lugar precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.
Em vez disso, esse parâmetro também pode incluir
(regions)
ou(cities)
. A coleção do tipo(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 são especificados.
-
includePureServiceAreaBusinesses
Se definido como
true
, a resposta inclui empresas que visitam ou entregam produtos diretamente aos clientes, mas não têm um local comercial físico. Se definido comofalse
, a API vai retornar apenas empresas com um local físico. -
includeQueryPredictions
Se for
true
, a resposta inclui previsões de lugar e de consulta. O valor padrão éfalse
, o que significa que a resposta inclui apenas previsões de lugares. -
includedRegionCodes
Incluir apenas os resultados da lista de regiões especificadas, especificadas como uma matriz de até 15 valores de dois caracteres de ccTLDs ("domínio de nível superior"). 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 serão localizados na área de interseção das duas configurações. -
inputOffset
O deslocamento do caractere Unicode com base 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á o comprimento deinput
. -
languageCode
O idioma preferencial em que os resultados são retornados. Os resultados podem estar em idiomas diferentes se o idioma usado em
input
for diferente do valor especificado porlanguageCode
ou se o lugar retornado não tiver uma tradução do idioma local paralanguageCode
.- Use os códigos de idioma IETF BCP-47 (em inglês) 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 vai retornar um erroINVALID_ARGUMENT
. - O idioma preferencial tem uma pequena influência no conjunto de resultados que a API escolhe para retornar e na ordem em que é retornado. Isso também afeta a capacidade da API de corrigir erros de ortografia.
-
A API tenta fornecer um endereço que seja legível para o usuário e para a população local, ao mesmo tempo em que reflete a entrada do usuário. As previsões de lugar são
formatadas de maneira 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 à preferência de idioma indicada pelo parâmetrolanguageCode
, quando disponível, ou usando nomes que melhor correspondam à 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 os termos correspondentes são escolhidos para corresponder aos do parâmetro
input
. -
Todos os outros endereços são retornados no idioma preferencial, depois que os termos correspondentes são escolhidos para corresponder aos termos no parâmetro
input
. Se um nome não estiver disponível no idioma preferencial, a API usará a correspondência mais próxima.
-
Os termos correspondentes no parâmetro
locationBias ou locationRestriction
Você pode especificar
locationBias
oulocationRestriction
, mas não ambos, para definir a área de pesquisa. Pense emlocationRestriction
como a especificação da região em que os resultados precisam estar e emlocationBias
como a especificação da região em que os resultados precisam estar próximos, mas podem estar fora da área.locationBias
Especifica uma área para pesquisar. Essa localização serve como um direcionamento que significa que resultados ao redor do local especificado podem 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 uma janela de visualização retangular ou um círculo.Um círculo é definido pelo ponto central e pelo raio em metros. O raio precisa estar entre 0,0 e 500.000,0. O valor padrão é 0,0. Para
locationRestriction
, defina o raio como um valor maior que 0,0. Caso contrário, a solicitação não retorna resultados.Exemplo:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Um retângulo é uma janela de visualização de latitude-longitude, representada como dois
low
e pontos altos diagonalmente opostos. Uma viewport é considerada uma região fechada, ou seja, ela inclui o limite. Os limites de latitude precisam variar entre -90 e 90 graus, e os limites de longitude precisam variar entre -180 a 180 graus:- Se
low
=high
, a viewport consiste nesse único ponto. - Se
low.longitude
>high.longitude
, o intervalo de longitude é invertido, ou seja, a janela de visualização cruza a linha de longitude de 180 graus. - Se
low.longitude
= -180 graus ehigh.longitude
= 180 graus, a viewport inclui todas as longitudes. - Se
low.longitude
= 180 graus ehigh.longitude
= -180 graus, o intervalo de longitude estará vazio.
low
ehigh
precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma viewport vazia resulta em um erro.Por exemplo, esta viewport inclui toda a cidade de 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 de região usado para formatar a resposta, especificado como um valor de ccTLD ("domínio de nível superior") 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 a entidade "Reino Unido da Grã-Bretanha e Irlanda do Norte").
Se você especificar um código de região inválido, a API vai retornar um erro
INVALID_ARGUMENT
. 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 rastreiam chamadas de preenchimento automático (novo) como "sessões". O preenchimento automático (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 fins de faturamento. Para mais informações, consulte Tokens de sessão.
Exemplos de preenchimento automático (novo)
Restringir a pesquisa a uma área usando locationRestriction
locationRestriction
especifica a área a ser pesquisada. Os resultados fora da área especificada não são retornados. No exemplo a seguir, use locationRestriction
para limitar a solicitação a um círculo de 5.000 metros de raio centrado em São Francisco:
curl -X POST -d '{ "input": "Art museum", "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/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "establishment", "museum", "point_of_interest" ] } }, { "placePrediction": { "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w", "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w", "text": { "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA", "matches": [ { "endOffset": 15 } ] }, "structuredFormat": { "mainText": { "text": "de Young Museum", "matches": [ { "endOffset": 15 } ] }, "secondaryText": { "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "tourist_attraction", "museum" ] } }, /.../ ] }
Também é possível usar locationRestriction
para restringir as pesquisas a uma janela de visualização retangular. O exemplo a seguir limita a solicitação ao centro de São Francisco:
curl -X POST -d '{ "input": "Art museum", "locationRestriction": { "rectangle": { "low": { "latitude": 37.7751, "longitude": -122.4219 }, "high": { "latitude": 37.7955, "longitude": -122.3937 } } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Os resultados estão contidos na matriz suggestions
:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "museum", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc", "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc", "text": { "text": "International Art Museum of America, Market Street, San Francisco, CA, USA", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "structuredFormat": { "mainText": { "text": "International Art Museum of America", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "secondaryText": { "text": "Market Street, San Francisco, CA, USA" } }, "types": [ "museum", "point_of_interest", "tourist_attraction", "art_gallery", "establishment" ] } } ] }
Polarizar a pesquisa em uma área usando locationBias
Com locationBias
, o local serve como uma polarização, o que significa que os resultados em torno do local especificado podem ser retornados, incluindo resultados fora da área especificada. No exemplo a seguir, você direciona a solicitação para o centro de São Francisco:
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 muitos outros itens, incluindo resultados 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" ] } }, ... ] }
Também é possível usar locationBias
para restringir as pesquisas a uma viewport
retangular. O exemplo a seguir limita a solicitação ao centro de São Francisco:
curl -X POST -d '{ "input": "Amoeba", "locationBias": { "rectangle": { "low": { "latitude": 37.7751, "longitude": -122.4219 }, "high": { "latitude": 37.7955, "longitude": -122.3937 } } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ https://places.googleapis.com/v1/places:autocomplete
Embora os resultados da pesquisa na janela de visualização retangular apareçam na resposta, alguns resultados estão
fora dos limites definidos devido à polarização. Os resultados também 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": [ "point_of_interest", "store", "establishment" ] } }, { "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": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI", "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI", "text": { "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Hollywood Boulevard, Los Angeles, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, /.../ ] }
Usar includedPrimaryTypes
Use o parâmetro includedPrimaryTypes
para especificar até cinco valores de tipo da Tabela A, da Tabela B, de apenas (regions)
ou somente (cities)
. Um lugar precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.
No exemplo a seguir, você especifica uma string input
de
"Soccer" e usa 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. Use o parâmetro de solicitação 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 lugar e previsões de consulta, como 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 solicitação de Text Search (novo) para receber 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.
Neste exemplo, a origem é definida 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!
O API Explorer permite fazer solicitações de amostra para que você se familiarize com a API e as opções dela.
- Selecione o ícone da API, , no lado direito da página.
- Opcionalmente, abra Mostrar parâmetros padrão e defina
o parâmetro
fields
para a máscara de campo. - Se preferir, edite o corpo da solicitação.
- Selecione o botão Executar. No pop-up, escolha a conta que você quer usar para fazer a solicitação.
No painel do API Explorer, selecione o ícone de expansão, , para abrir a janela do API Explorer.