O Text Search (novo) retorna informações sobre um conjunto de lugares com base em uma string, por exemplo, "pizza em São Paulo" ou "lojas de calçados", perto de Ottawa" ou "123 Main Street". O serviço responde com uma lista de locais correspondendo à string de texto e a qualquer polarização de localização que tenha sido definida.
O serviço é especialmente útil para fazer solicitações de endereços ambíguos consultas em um sistema automatizado, e componentes da string que não fazem parte do endereço podem corresponder a empresas, bem como endereços IP internos. Exemplos de consultas de endereço ambíguas são endereços mal formatados ou solicitações que incluem componentes não relacionados ao endereço, como nomes de empresas. Solicitações como os dois primeiros exemplos, pode retornar zero resultados, a menos que um local — como região, restrição de local ou viés de local, está definida.
O Text Search (novo) é semelhante ao Nearby Search (Novo). O principal a diferença entre os dois é que o Text Search (novo) permite especificar uma string de pesquisa arbitrária, enquanto o Nearby Search (novo) exige uma área específica na qual pesquisar.
"10 High Street, Reino Unido" ou "123 Main Street, US" | Várias "High Street" no Reino Unido; várias "Main Street" nos EUA. A consulta não retorna os resultados desejáveis, a menos que haja uma restrição de local definido. |
"ChainRestaurant New York" | Vários "ChainRestaurant" em Nova York. nenhum endereço ou até mesmo o nome da rua. |
"10 High Street, Escher Reino Unido" ou "123 Main Street, Pleasanton US" | Apenas uma "High Street" na cidade de Escher, do Reino Unido; apenas uma "Main Street" na cidade de Pleasanton, EUA. |
"UniqueRestaurantName New York" | Apenas um estabelecimento com este nome em Nova York; nenhum endereço necessário diferenciá-las. |
"pizzarias em São Paulo" | Essa consulta contém a restrição de local, e "pizzarias" é um tipo de lugar bem definido. Ela retorna vários resultados. |
"+55 (51) 4670-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 tem o seguinte 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ê:
Defina a lista de campos para incluir apenas
Place.Field.ID
ePlace.Field.NAME
. Isso significa que os objetosPlace
na resposta que representam cada correspondência local contêm apenas esses dois campos.Usar
SearchByTextRequest.Builder
para criarSearchByTextRequest
que define a pesquisa.Defina a string de consulta de texto como "Comida vegetariana picante".
Defina o número máximo de locais de resultados como 10. Os valores padrão e máximo é 20.
Restrinja a área de pesquisa ao retângulo definido pela latitude e coordenadas de longitude. Nenhuma correspondência fora desta área é retornada.
Adicione uma
OnSuccessListener
e acesse os lugares correspondentes doSearchByTextResponse
objeto.
Respostas do Text Search
O
SearchByTextResponse
representa a resposta de uma solicitação de pesquisa. Um SearchByTextResponse
contém:
Uma lista de objetos
Place
que representam todos os lugares correspondentes, com umPlace
objeto por lugar correspondente.Cada objeto
Place
contém apenas os campos definidos pela lista de campos passada 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 o Place.getId()
e Place.getName()
para acessar esses campos em cada objeto Place
.
Para mais exemplos de como acessar dados em um objeto Place
, consulte Acessar o Place
campos de dados de objetos
Parâmetros obrigatórios
Os parâmetros exigidos para
SearchByTextRequest
são:
-
Lista de campos
Especifique quais campos de dados de lugares devem ser retornados. Transmita uma lista de
Place.Field
valores especificando os campos de dados a serem retornados. Não existe uma lista padrão de retornados na resposta.As listas de campos são uma prática recomendada de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário e cobranças de faturamento adicionais.
Especifique um ou mais dos seguintes campos:
Os campos a seguir acionam a SKU do Text Search (somente ID):
Place.Field.ID
,Place.Field.NAME
Os campos a seguir acionam a SKU do 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
,Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
Os campos a seguir acionam a SKU do Text Search (avançado):
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 do 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
,Place.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 a ser pesquisada, por exemplo: "restaurante", "Avenida Brasil, 123" ou "melhor lugar para visitar em São Paulo". A API retorna as correspondências possíveis de acordo com essa string e ordena os resultados com base na relevância percebida deles.
Para definir o parâmetro de consulta de texto, chame o método
setTextQuery()
ao criar o objetoSearchByTextRequest
.
Parâmetros opcionais
Use o
SearchByTextRequest
para especificar os parâmetros opcionais de sua solicitação.
Tipo incluído
Restringe os resultados aos lugares correspondentes ao tipo especificado definido pelo Tabela A. Só é possível especificar um tipo. 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. 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.
Você pode especificar a restrição ou o direcionamento de local, mas não os dois. Pense na restrição de local como a especificação região em que os resultados devem estar e o viés de localização especificando a região a que os resultados precisam estar próximos, mas que podem estar fora na área.
Especifique a região como uma janela de visualização retangular ou como um círculo.
Um círculo é definido pelo ponto central e pelo raio em metros. O raio deve estar entre 0,0 e 50.000,0, inclusive. 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 em diagonal opostos a pontos baixo e alto. O ponto baixo marca o sudoeste e o ponto alto representa a região nordeste canto do retângulo.
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á em nesse único ponto. - Se
low.longitude
>high.longitude
, os o intervalo de longitude é invertido (a janela de visualização cruza o intervalo de 180 graus (linha de longitude). - Se
low.longitude
= -180 graus ehigh.longitude
= 180 graus, a janela de visualização inclui todos longitudes. - Se
low.longitude
= 180 graus ehigh.longitude
= -180 graus, o intervalo de longitude é vazio. - Se
low.latitude
>high.latitude
, os o intervalo de latitude está vazio.
Os valores baixo e alto precisam ser preenchidos, e a caixa representada não pode ser vazio. Uma janela de visualização vazia resulta em erro.
Por exemplo, em uma janela de visualização retangular, veja Solicitações do Text Search.
Para definir o parâmetro de direcionamento 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 do Viés de local para informações sobre como definir a janela de visualização.
Você pode especificar a restrição ou o direcionamento de local, mas não os dois. Pense na restrição de local como a especificação região em que os resultados devem estar e o viés de localização especificando a região a que os resultados precisam estar próximos, mas que podem estar fora na á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 lugar 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 que ou iguais a esse limite. Os valores devem estar entre 0,0 e 5,0 (inclusive) incrementos de 0,5. Por exemplo: 0, 0,5, 1,0, ... , 5,0. Os valores são arredondado para a casa decimal mais próxima. Por exemplo, um valor de 0,6 elimina todas as resultados com uma classificação inferior a 1,0.
Para definir o parâmetro de classificação mínima, chame o método
setMinRating()
ao criar o objetoSearchByTextRequest
.Aberto agora
Se
true
, retorna apenas os lugares que estão abertos para funcionamento no momento em que a consulta é enviada. Sefalse
, mostrar todas as empresas independentemente do status aberto. Locais que não especificam horário de funcionamento no banco de dados do Google Places são retornado 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 em todos os níveis de preço. Para restringir resultados para incluir apenas lugares em níveis de preços específicos, você pode passar uma lista de valores inteiros que correspondem aos níveis de preço para os 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",
O padrão é
SearchByTextRequest.RankPreference.RELEVANCE
(classificar os resultados por relevância da pesquisa). 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 não definido.
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",
O padrão é
Código de região
O código da região usado para formatar a resposta, especificado como um 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, o código do país é 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 os "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 do código da região, 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
, somente lugares que correspondem aos tipos especificados especificados por incluem são retornados. Quando forfalse
, o padrão, a resposta poderá conter locais que 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
.