O 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 que correspondem à 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 endereços podem corresponder a empresas e endereços. Exemplos de consultas de endereço ambíguas são endereços ou solicitações mal formatados que incluem componentes que não fazem parte do endereço, como nomes de empresas. Solicitações como os dois primeiros exemplos podem não retornar resultados, a menos que um local, como região, restrição de local ou viés de local, seja definido.
O Text Search (novo) é semelhante ao Nearby Search (New). A principal diferença entre os dois é que o Text Search (novo) permite especificar uma string de pesquisa arbitrária, enquanto a Nearby Search (New) exige uma área específica para pesquisar.
"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. |
Solicitações do Text Search
Uma solicitação do Text Search está no formato:
// Specify the list of fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Define latitude and longitude coordinates of the search area. LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874); LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572); // Use the builder to create a SearchByTextRequest object. final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields) .setMaxResultCount(10) .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build(); // Call PlacesClient.searchByText() to perform the search. // Define a response handler to process the returned List of Place objects. placesClient.searchByText(searchByTextRequest) .addOnSuccessListener(response -> { List<Place> places = response.getPlaces(); });
Neste exemplo, você fará o seguinte:
Defina a lista de campos para incluir apenas
Place.Field.ID
ePlace.Field.NAME
. Isso significa que os objetosPlace
na resposta que representam cada local correspondente contêm apenas esses dois campos.Use
SearchByTextRequest.Builder
para criar um objetoSearchByTextRequest
que defina a pesquisa.Defina a string de consulta de texto como "Spicy Vegetarian Food".
Defina o número máximo de casas do resultado como 10. O padrão e o máximo são 20.
Restrinja a área de pesquisa ao retângulo definido pelas coordenadas de latitude e longitude. Nenhuma correspondência fora desta área é retornada.
Adicione um
OnSuccessListener
e receba os lugares correspondentes do objetoSearchByTextResponse
.
Respostas do Text Search
A classe
SearchByTextResponse
representa a resposta de uma solicitação de pesquisa. Um objeto SearchByTextResponse
contém:
Uma lista de objetos
Place
que representam todos os lugares correspondentes, com um objetoPlace
por lugar correspondente.Cada objeto
Place
contém apenas os campos definidos pela lista de campos transmitidos na solicitação.
Por exemplo, na solicitação, você definiu uma lista de campos como:
// Specify the list of fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
Essa lista de campos significa que cada objeto Place
na resposta contém apenas o ID e o nome de cada local correspondente. Em seguida, use os métodos Place.getId()
e Place.getName()
para acessar esses campos em cada objeto Place
.
Para mais exemplos de acesso a dados em um objeto Place
, consulte Acessar campos de dados do objeto Place
Parâmetros obrigatórios
Os parâmetros obrigatórios para
SearchByTextRequest
são:
-
Lista de campos
Especifique quais campos de dados do lugar serão retornados. Transmita uma lista de valores de
Place.Field
especificando os campos de dados que serão retornados. Não há uma lista padrão de campos retornados na resposta.As listas de campo são uma boa prática de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento e cobranças de faturamento desnecessários.
Especifique um ou mais dos seguintes campos:
Os campos a seguir acionam a SKU Text Search (somente ID):
Place.Field.ID
,Place.Field.NAME
Os campos a seguir acionam a SKU Text Search (Basic):
Place.Field.ADDRESS_COMPONENTS
,Place.Field.BUSINESS_STATUS
,Place.Field.ADDRESS
,Place.Field.ICON_BACKGROUND_COLOR
,Place.Field.ICON_URL
,Place.Field.LAT_LNG
,Place.Field.PHOTO_METADATAS
,Place.Field.PLUS_CODE
,Place.Field.TYPES
,Place.Field.UTC_OFFSET
,Place.Field.VIEWPORT
ePlace.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
Os campos a seguir acionam a SKU Text Search (Advanced):
Place.Field.CURRENT_OPENING_HOURS
,Place.Field.SECONDARY_OPENING_HOURS
,Place.Field.PHONE_NUMBER
,Place.Field.PRICE_LEVEL
,Place.Field.RATING
,Place.Field.OPENING_HOURS
,Place.Field.USER_RATINGS_TOTAL
,Place.Field.WEBSITE_URI
Os campos a seguir acionam a SKU Text Search (Preferencial):
Place.Field.CURBSIDE_PICKUP
,Place.Field.DELIVERY
,Place.Field.DINE_IN
,Place.Field.EDITORIAL_SUMMARY
,Place.Field.RESERVABLE
,Place.Field.REVIEWS
,Place.Field.SERVES_BEER
,Place.Field.SERVES_BREAKFAST
,Place.Field.SERVES_BRUNCH
,Place.Field.SERVES_DINNER
,Place.Field.SERVES_LUNCH
,Place.Field.SERVES_VEGETARIAN_FOOD
,Place.Field.SERVES_WINE
ePlace.Field.TAKEOUT
Para definir o parâmetro da lista de campos, chame o método
setPlaceFields()
ao criar o objetoSearchByTextRequest
. -
Consulta de texto
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.
Para definir o parâmetro de consulta de texto, chame o método
setTextQuery()
ao criar o objetoSearchByTextRequest
.
Parâmetros opcionais
Use o objeto SearchByTextRequest
para especificar os parâmetros opcionais da sua solicitação.
Tipo incluído
Restringe os resultados aos lugares correspondentes ao tipo especificado definido pela Tabela A. Somente um tipo pode ser especificado. Exemplo:
setIncludedType("bar")
setIncludedType("pharmacy")
Para definir o parâmetro do tipo incluído, chame o método
setIncludedType()
ao criar o objetoSearchByTextRequest
.Viés de local
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 a restrição ou o direcionamento de local, mas não ambos. Pense na restrição de local como a especificação da região em que os resultados precisam estar, e o viés de localização como a especificação da 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. Exemplo:
// Define latitude and longitude coordinates of the center of the search area. LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874); // Use the builder to create a SearchByTextRequest object. // Set the radius of the search area to 500.0 meters. final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields) .setMaxResultCount(10) .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();
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, de uma janela de visualização retangular, consulte as Solicitações do Text Search.
Para definir o parâmetro de viés de local, chame o método
setLocationBias()
ao criar o objetoSearchByTextRequest
.- Se
Restrição de local
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 Viés de local para informações sobre como definir a janela de visualização.
É possível especificar a restrição ou o direcionamento de local, mas não ambos. Pense na restrição de local como a especificação da região em que os resultados precisam estar, e o viés de localização como a especificação da região em que os resultados precisam estar próximos, mas que podem estar fora da área.
Para definir o parâmetro de restrição de local, chame o método
setLocationRestriction()
ao criar o objetoSearchByTextRequest
.-
Contagem máxima de resultados
Especifica o número máximo de resultados de lugares a serem retornados. Precisa estar entre 1 e 20 (padrão).
Para definir o parâmetro de contagem máxima de resultados, chame o método
setMaxResultCount()
ao criar o objetoSearchByTextRequest
. Classificação mínima
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.
Para definir o parâmetro de nota mínima, chame o método
setMinRating()
ao criar o objetoSearchByTextRequest
.Aberto agora
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
.Para definir o parâmetro "open now", chame o método
setOpenNow()
ao criar o objetoSearchByTextRequest
.-
Níveis de preço
Por padrão, os resultados incluem lugares que oferecem serviços com todos os níveis de preço. Para que os resultados incluam apenas lugares em níveis de preços específicos, transmita uma lista de valores inteiros que correspondam aos níveis de preço dos lugares que você quer retornar:
1
: o lugar oferece serviços baratos.2
: o lugar oferece serviços com preços moderados.3
: o lugar oferece serviços caros.4
: o lugar oferece serviços muito caros.
Para definir o parâmetro de níveis de preço, chame o método
setPriceLevels()
ao criar o objetoSearchByTextRequest
. Preferência de classificação
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",
SearchByTextRequest.RankPreference.RELEVANCE
(classificar os resultados por relevância da pesquisa) é o padrão. Você pode definir a preferência de classificação comoSearchByTextRequest.RankPreference.RELEVANCE
ouSearchByTextRequest.RankPreference.DISTANCE
(classifique os resultados por distância). - Para uma consulta não categórica, como "Mountain View, CA", recomendamos deixar o parâmetro de preferência de classificação indefinido.
Para definir o parâmetro de preferência de classificação, chame o método
setRankPreference()
ao criar o objetoSearchByTextRequest
.- Para uma consulta categórica como "Restaurantes em Nova York",
Código de região
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 de endereço na resposta corresponder ao código regional, esse código será omitido do endereço.
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.
Para definir o parâmetro de código regional, chame o método
setRegionCode()
ao criar o objetoSearchByTextRequest
.Filtragem de tipo restrito
Usado com o parâmetro de tipo de inclusão. Quando definido como
true
, apenas lugares que correspondem aos tipos especificados especificados pelo tipo de inclusão são retornados. Quandofalse
, o padrão, a resposta pode conter lugares que não correspondem aos tipos especificados.Para definir o parâmetro de filtragem de tipo restrito, chame o método
setStrictTypeFiltering()
ao criar o objetoSearchByTextRequest
.