Uma Text Search (Novo) retorna informações sobre um conjunto de lugares com base em uma string, por exemplo, "pizza em São Paulo", "loja de sapatos perto do Rio de Janeiro" ou "Avenida Brasil, 123". O serviço responde com uma lista de locais correspondentes à string de texto e a todos os direcionamentos de localização definidos.
O serviço é especialmente útil para fazer consultas de endereço ambíguas em um sistema automatizado, e componentes da string que não são de endereço podem corresponder a empresas e endereços. Exemplos de consultas de endereço ambíguas são endereços ou solicitações mal formatadas ou que incluem componentes que não fazem parte do endereço, como nomes de empresas. Solicitações como os dois primeiros exemplos na tabela a seguir podem não retornar resultados, a menos que um local, como região, restrição ou viés de local, seja definido.
"10 High Street, UK" ou "123 Main Street, EUA" | Várias "High Streets" no Reino Unido, várias "Main Street" nos EUA. A consulta não retorna os resultados desejáveis, a menos que uma restrição de local seja definida. |
"ChainRestaurant Nova York" | Vários locais do "ChainRestaurant" em Nova York, sem endereço ou nome da rua. |
"10 High Street, Escher UK" ou "123 Main Street, Pleasanton US" | Apenas uma "High Street" na cidade de Escher, no Reino Unido, e apenas uma "Main Street" na cidade de Pleasanton, nos EUA. |
"UniqueRestaurantName Nova York" | Apenas um estabelecimento com esse nome em Nova York, e não é necessário diferenciar o endereço. |
"pizzarias em São Paulo" | Essa consulta contém a restrição de local, e "pizzaria" é um tipo de lugar bem definido. A função retorna vários resultados. |
"+1 514-670-8700" | Esta consulta contém um número de telefone. Ela retorna vários resultados para lugares associados a esse número de telefone. |
Com o API Explorer, é possível fazer solicitações em tempo real para se familiarizar com a API e as opções dela:
Solicitações do Text Search
Uma solicitação Text Search é um HTTP POST com o seguinte formato:
https://places.googleapis.com/v1/places:searchText
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 '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \ 'https://places.googleapis.com/v1/places:searchText'
Respostas do Text Search (novo)
O Text Search (novo) retorna um objeto JSON como resposta. Na resposta:
- A matriz
places
contém todos os lugares correspondentes. - Cada lugar da matriz é representado por um objeto
Place
. O objetoPlace
contém informações detalhadas sobre um único local. - O FieldMask transmitido na solicitação especifica a lista de campos retornados no objeto
Place
.
O objeto JSON completo está no formato:
{ "places": [ { object (Place) } ] }
Parâmetros obrigatórios
-
FieldMask
Especifique a lista de campos a serem retornados na resposta criando uma máscara de campo de resposta. Transmita a máscara de campo de resposta para o método usando o parâmetro de URL
$fields
oufields
ou usando o cabeçalho HTTPX-Goog-FieldMask
. Não há uma lista padrão de campos retornados na resposta. Se você omitir a máscara de campo, o método retornará um erro.O mascaramento de campo é uma boa prática de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar cobranças de faturamento e tempo de processamento desnecessários.
Especifique uma lista separada por vírgulas de tipos de dados de lugar a serem retornados. Por exemplo, para recuperar o nome de exibição e o endereço do local.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Use
*
para recuperar todos os campos.X-Goog-FieldMask: *
Especifique um ou mais dos seguintes campos:
Os campos a seguir acionam a SKU Text Search (somente ID):
places.id
,places.name
*
* O campoplaces.name
contém o nome do recurso do lugar no formato:places/PLACE_ID
. Useplaces.displayName
para acessar o texto do lugar.Os campos a seguir acionam a SKU Text Search (Basic):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.location
,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
Os campos a seguir acionam a SKU Text Search (Advanced):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Os campos a seguir acionam a SKU Text Search (Preferencial):
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.servesBeer
,places.delivery
,places.delivery
,places.delivery
,places.delivery
,places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
textQuery
A string de texto para pesquisar, por exemplo: "restaurante", "123 Main Street" ou "melhor lugar para visitar em São Paulo". A API retorna correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância.
Parâmetros opcionais
includedType
Restringe os resultados aos lugares correspondentes ao tipo especificado definido pela Tabela A. Somente um tipo pode ser especificado. Exemplo:
"includedType":"bar"
"includedType":"pharmacy"
languageCode
O idioma no qual os resultados serão retornados.
- Consulte a lista de idiomas compatíveis. O Google atualiza os idiomas compatíveis com frequência, portanto, essa lista pode não estar completa.
-
Se
languageCode
não for fornecido, o padrão da API seráen
. Se você especificar um código de idioma inválido, a API retornará um erroINVALID_ARGUMENT
. - A API faz o possível para fornecer um endereço legível tanto para o usuário quanto para os locais. Para isso, ele retorna endereços no idioma local, transliterados para um script que pode ser lido pelo usuário, se necessário, seguindo o idioma preferido. Todos os outros endereços são retornados no idioma de preferência. Os componentes de endereço são todos retornados no mesmo idioma, escolhido no primeiro componente.
- Se um nome não estiver disponível no idioma preferencial, a API 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 são retornados. O geocodificador interpreta abreviações de maneiras diferentes dependendo do idioma, como abreviações de tipos de rua ou sinônimos, que podem ser válidos em um idioma, mas não em outro.
locationBias
Especifica uma área a ser pesquisada. Esse local serve como um viés, o que significa que resultados no local especificado podem ser retornados, incluindo resultados fora da área especificada.
É possível especificar
locationRestriction
oulocationBias
, mas não ambos. Pense emlocationRestriction
como uma especificação da região em que os resultados precisam estar, elocationBias
como uma região em que os resultados precisam estar próximos, mas que podem estar fora da área.Especifique a região 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 50.000,0. O valor padrão é 0,0. 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 pontos diagonalmente opostos abaixo e alto. O ponto baixo marca o canto sudoeste, e o ponto alto representa o canto nordeste.
Uma janela de visualização é considerada uma região fechada, ou seja, que inclui o limite dela. Os limites de latitude precisam variar de -90 a 90 graus, e os limites de longitude precisam variar de -180 a 180 graus:
- Se
low
=high
, a janela de visualização consiste nesse único ponto. - Se
low.longitude
>high.longitude
, o intervalo de longitude será invertido (a janela de visualização cruza a linha de longitude de 180 graus). - Se
low.longitude
= -180 graus ehigh.longitude
= 180 graus, a janela de visualização incluirá todas as longitudes. - Se
low.longitude
= 180 graus ehigh.longitude
= -180 graus, o intervalo de longitude ficará vazio. - Se
low.latitude
>high.latitude
, o intervalo de latitude estará vazio.
As colunas baixas e altas precisam ser preenchidas, e a caixa representada não pode ficar vazia. Uma janela de visualização vazia resulta em erro.
Por exemplo, esta janela de visualização abrange totalmente a cidade de Nova York:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Se
locationRestriction
Especifica uma área a ser pesquisada. Os resultados fora da área especificada não são retornados. Especifique a região como uma janela de visualização retangular. Consulte a descrição de
locationBias
para ver informações sobre como definir a janela de visualização.É possível especificar
locationRestriction
oulocationBias
, mas não ambos. Pense emlocationRestriction
como uma especificação da região em que os resultados precisam estar, elocationBias
como uma região em que os resultados precisam estar próximos, mas que podem estar fora da área.-
maxResultCount
Especifica o número máximo de resultados de lugares a serem retornados. Precisa estar entre 1 e 20 (padrão).
evOptions
Especifica parâmetros para identificar os conectores de carregamento de veículos elétricos (VE) e as taxas de carregamento disponíveis.
connectorTypes
Filtra pelo tipo de conector de carregamento de VE disponível em um lugar. Um local que não seja compatível com nenhum dos tipos de conector será filtrado. Os tipos compatíveis de conectores de carregamento de VE incluem carregadores combinados (CA e CC), carregadores Tesla, carregadores compatíveis com GB/T (para carregamento rápido de VE na China) e carregadores de tomada. Para saber mais, consulte a documentação de referência.
minimumChargingRateKw
Filtra lugares por taxa mínima de carregamento de VE em quilowatts (kW). Todos os lugares com uma taxa menor que a mínima são filtrados. Por exemplo, para encontrar carregadores de VE com taxas de carregamento de pelo menos 10 kW, defina esse parâmetro como "10".
minRating
Restringe os resultados apenas àqueles cuja avaliação média de usuários seja maior ou igual a esse limite. Os valores precisam estar entre 0,0 e 5,0 (inclusive) em incrementos de 0,5. Por exemplo: 0, 0,5, 1,0, ... , 5,0. Os valores são arredondados para a casa de 0,5 mais próxima. Por exemplo, um valor de 0,6 elimina todos os resultados com uma classificação menor que 1,0.
openNow
Se for
true
, retorne apenas os lugares que estão abertos no momento em que a consulta é enviada. Se forfalse
, retorna todas as empresas, independentemente do status aberto. Os locais que não especificam horário de funcionamento no banco de dados do Google Places vão ser retornados se você definir esse parâmetro comofalse
.-
priceLevels
Restrinja a pesquisa a lugares marcados com determinados níveis de preço. O padrão é selecionar todos os níveis de preço.
Especifique uma matriz de um ou mais valores definidos por
PriceLevel
.Exemplo:
"priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
rankPreference
Especifica como os resultados são classificados na resposta com base no tipo de consulta:
- Para uma consulta categórica como "Restaurantes em Nova York",
RELEVANCE
(classificar os resultados por relevância da pesquisa) é o padrão. Você pode definirrankPreference
comoRELEVANCE
ouDISTANCE
(classificar os resultados por distância). - Para uma consulta não categórica como "Mountain View, CA", recomendamos deixar
rankPreference
sem definição.
- Para uma consulta categórica como "Restaurantes em Nova York",
regionCode
O código regional usado para formatar a resposta, especificado como um valor de código CLDR de dois caracteres. Esse parâmetro também pode ter um efeito de viés nos resultados da pesquisa. Não há valor padrão.
Se o nome do país do campo
formattedAddress
na resposta corresponder aregionCode
, o código do país será omitido deformattedAddress
. Esse parâmetro não tem efeito emadrFormatAddress
, que sempre inclui o nome do país quando disponível, ou emshortFormattedAddress
, que nunca o inclui.A maioria dos códigos CLDR é 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"). O parâmetro pode afetar os resultados com base na legislação aplicável.
strictTypeFiltering
Usado com o parâmetro
includeType
. Quando definido comotrue
, apenas lugares que correspondem aos tipos especificados especificados porincludeType
são retornados. Quando falso, o padrão, a resposta pode conter lugares que não correspondem aos tipos especificados.
Exemplos do Text Search
Encontrar um lugar por string de consulta
O exemplo a seguir mostra uma solicitação de Pesquisa de texto para "Spicy Vegetarian Food in Sydney, Australia":
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \ 'https://places.googleapis.com/v1/places:searchText'
Observe que o cabeçalho X-Goog-FieldMask
especifica que a
resposta
contém os seguintes campos de dados: places.displayName,places.formattedAddress
.
A resposta está no formato:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, { "formattedAddress": "29 King St, Sydney NSW 2000, Australia", "displayName": { "text": "Peace Harmony", "languageCode": "en" } }, ... ] }
Adicione mais tipos de dados à máscara de campo para retornar mais informações.
Por exemplo, adicione places.types,places.websiteUri
para incluir o tipo de restaurante e o endereço da Web na resposta:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \ 'https://places.googleapis.com/v1/places:searchText'
A resposta agora está no formato:
{ "places": [ { "types": [ "vegetarian_restaurant", "vegan_restaurant", "chinese_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "websiteUri": "http://www.motherchusvegetarian.com.au/", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "types": [ "vegan_restaurant", "thai_restaurant", "vegetarian_restaurant", "indian_restaurant", "italian_restaurant", "american_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia", "websiteUri": "http://www.veggosizzle.com.au/", "displayName": { "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney", "languageCode": "en" } }, ... ] }
Filtrar lugares por nível de preço
Use a opção priceLevel
para filtrar os resultados e exibir os restaurantes
definidos como baratos ou moderadamente caros:
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia", "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"] }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \ 'https://places.googleapis.com/v1/places:searchText'
Este exemplo também usa o cabeçalho X-Goog-FieldMask
para adicionar o campo de dados places.priceLevel
à resposta para que fique no formato:
{ "places": [ { "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Mother Chu's Vegetarian Kitchen", "languageCode": "en" } }, { "formattedAddress": "115 King St, Newtown NSW 2042, Australia", "priceLevel": "PRICE_LEVEL_MODERATE", "displayName": { "text": "Green Mushroom", "languageCode": "en" } }, ... ] }
Adicione outras opções para refinar a pesquisa, como includedType
, minRating
, rankPreference
, openNow
e outros parâmetros descritos em Parâmetros opcionais.
Pesquisar lugares em uma área
Use locationRestriction
ou locationBias
,
mas não ambos, para restringir uma pesquisa a uma área. Pense em locationRestriction
como uma especificação da região dentro dos resultados e locationBias
como uma região em que os resultados precisam estar próximos, mas que podem estar fora da área.
O exemplo a seguir mostra uma solicitação do Text Search para "Spicy Vegetarian Food" com tendência a estar a 500 metros de um ponto no centro de São Francisco. Essa solicitação retorna apenas os 10 primeiros resultados de lugares que estão abertos.
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food", "openNow": true, "maxResultCount": 10, "locationBias": { "circle": { "center": {"latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } }, }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \ 'https://places.googleapis.com/v1/places:searchText'
Pesquisar carregadores de VE com taxa de carregamento mínima
Use minimumChargingRateKw
e connectorTypes
para
procurar lugares com carregadores disponíveis compatíveis com seu VE.
No exemplo a seguir, mostramos uma solicitação de conectores de carregamento de VE Tesla e J1772 tipo 1 com uma taxa de carregamento mínima de 10 kW em Mountain View, CA. Apenas quatro resultados são retornados.
curl -X POST -d '{ "textQuery": "EV Charging Station Mountain View", "maxResultCount": 4, "evOptions": { "minimumChargingRateKw": 10, "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"] } }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \ 'https://places.googleapis.com/v1/places:searchText'
A solicitação retorna a seguinte resposta:
{ "places": [ { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 16, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 100, "count": 8, "availableCount": 5, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 2, "availableCount": 2, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 6, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 6, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 100, "count": 4, "availableCount": 3, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 350, "count": 2, "availableCount": 0, "outOfServiceCount": 2, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "EVgo Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 5, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_J1772", "maxChargeRateKw": 3.5999999046325684, "count": 1, "availableCount": 0, "outOfServiceCount": 1, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CHADEMO", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" }, { "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1", "maxChargeRateKw": 50, "count": 2, "availableCount": 0, "outOfServiceCount": 0, "availabilityLastUpdateTime": "2024-01-10T19:10:00Z" } ] } }, { "displayName": { "text": "Electric Vehicle Charging Station", "languageCode": "en" }, "evChargeOptions": { "connectorCount": 10, "connectorAggregation": [ { "type": "EV_CONNECTOR_TYPE_OTHER", "maxChargeRateKw": 210, "count": 10 } ] } } ] }
Confira!
Com a API Explorer, você pode fazer solicitações de amostra para conhecer a API e as opções dela.
Selecione o ícone da API, , no lado direito da página.
Se quiser, expanda Mostrar parâmetros padrão e defina o parâmetro
fields
como a máscara de campo.Se quiser, edite o Corpo da solicitação.
Selecione o botão Executar. Na caixa de diálogo 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 dele.