Text Search retorna informações sobre um conjunto de locais com base em uma string. Por exemplo, "pizza em São Paulo", "loja de calçados perto de São Paulo" ou "Avenida Brasil, 123". O serviço responde com uma lista de locais que correspondem à string de texto e a qualquer viés de localização definido.
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.
"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. |
"Chain restaurante New York" (restaurante em cadeia de Nova York) | Vários locais de "rede de restaurantes" 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. |
Ver uma lista de lugares usando a pesquisa de texto
Faça uma solicitação do Text Search chamando GMSPlacesClient
searchByTextWithRequest:
, transmitindo um objeto GMSPlaceSearchByTextRequest
que define os parâmetros da solicitação e um método de callback do tipo GMSPlaceSearchByTextResultCallback
para processar a resposta.
O objeto GMSPlaceSearchByTextRequest
especifica todos os parâmetros obrigatórios e opcionais para a solicitação. Os parâmetros obrigatórios incluem:
- A lista de campos a serem retornados no objeto
GMSPlace
, também chamada de máscara de campo, conforme definido porGMSPlaceProperty
. Se você não especificar pelo menos um campo na lista ou omitir a lista, a chamada retornará um erro. - A consulta de texto.
Este exemplo de solicitação de pesquisa de texto especifica que os objetos GMSPlace
de resposta contêm o nome e o ID do lugar para cada objeto GMSPlace
nos resultados da pesquisa. Ele também filtra a resposta para retornar apenas locais do tipo "restaurante".
Swift
// Create the GMSPlaceSearchByTextRequest object. let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue} let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties) request.isOpenNow = true request.includedType = "restaurant" request.maxResultCount = 5 request.minRating = 3.5 request.rankPreference = .distance request.isStrictTypeFiltering = true request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0) // Array to hold the places in the response var placeResults: [GMSPlace] = [] let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } placeResults = results } GMSPlacesClient.shared().searchByText(with: request, callback: callback)
Objective-C
// Create the GMSPlaceSearchByTextRequest object. GMSPlaceSearchByTextRequest *request = [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]]; request.isOpenNow = YES; request.includedType = @"restaurant"; request.maxResultCount = 5; request.minRating = 3.5; request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance; request.isStrictTypeFiltering = YES; request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ]; request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0); // Array to hold the places in the response _placeResults = [NSArray array]; // Create the GMSPlaceSearchByTextRequest object. [_placesClient searchByTextWithRequest:request callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } else { if (placeResults.count > 0) { // Get list of places. _placeResults = placeResults; } } } ];
GooglePlacesSwift
let restriction = RectangularLocationRestriction( northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30), southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50) ) let searchByTextRequest = SearchByTextRequest( textQuery: "pizza in New York", placeProperties: [ .name, .placeID ], locationRestriction: restriction, includedType: .restaurant, maxResultCount: 5, minRating: 3.5, priceLevels: [ .moderate, .inexpensive ], isStrictTypeFiltering: true ) switch await placesClient.searchByText(with: searchByTextRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
Respostas do Text Search
A API Text Search retorna uma matriz de correspondências na forma de objetos GMSPlace
, com um objeto GMSPlace
por lugar correspondente.
Junto com os campos de dados, o objeto GMSPlace
na
resposta contém as seguintes funções de membro:
-
isOpen
calcula se um lugar está aberto no horário especificado. isOpenAtDate
calcula se um lugar está aberto em uma determinada data.
Parâmetros obrigatórios
Use o objeto GMSPlaceSearchByTextRequest
para especificar os parâmetros
necessários para a pesquisa.
-
Lista de campos
Especifique quais propriedades de dados de lugar serão retornadas. Transmita uma lista de propriedades
GMSPlace
especificando os campos de dados que serão retornados. Se você omitir a máscara de campo, a solicitação retornará um erro.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):
GMSPlacePropertyPlaceID
,GMSPlacePropertyName
Os campos a seguir acionam a SKU Text Search (Basic):
GMSPlacePropertyAddressComponents
,GMSPlacePropertyBusinessStatus
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyCoordinate
,GMSPlacePropertyPhotos
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyUTCOffsetMinutes
,GMSPlacePropertyViewport
eGMSPlacePropertyWheelchairAccessibleEntrance
Os campos a seguir acionam a SKU Text Search (Advanced):
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
Os campos a seguir acionam a SKU Text Search (Preferencial):
GMSPlacePropertyCurbsidePickup
,GMSPlacePropertyDelivery
,GMSPlacePropertyDineIn
,GMSPlacePropertyEditorialSummary
,GMSPlacePropertyReservable
,GMSPlacePropertyReviews
,GMSPlacePropertyServesBeer
,GMSPlacePropertyServesBreakfast
,GMSPlacePropertyServesBrunch
,GMSPlacePropertyServesDinner
,GMSPlacePropertyServesLunch
,GMSPlacePropertyServesVegetarianFood
,GMSPlacePropertyServesWine
eGMSPlacePropertyTakeout
-
textQuery
A string de texto em que pesquisar, por exemplo: "restaurante", "123 Main Street" ou "melhor lugar para visitar em São Paulo".
Parâmetros opcionais
Use o objeto GMSPlaceSearchByTextRequest
para especificar os parâmetros
opcionais da pesquisa.
includedType
Restringe os resultados aos lugares correspondentes ao tipo especificado definido pela Tabela A. Somente um tipo pode ser especificado. Exemplo:
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
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
.isStrictTypeFiltering
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.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:
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.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.
- 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).
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.
-
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:
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
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
como.relevance
ou.distance
(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 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.
Exibir atribuições no seu aplicativo
Quando o app exibe informações coletadas de
GMSPlacesClient
,
como fotos e avaliações, ele também precisa mostrar as atribuições necessárias.
Por exemplo, a propriedade reviews
do objeto GMSPlacesClient
contém uma matriz de até cinco
objetos
GMSPlaceReview
. Cada objeto GMSPlaceReview
pode conter atribuições e atribuições de autor.
Se você mostrar a avaliação no app, também vai ser necessário mostrar qualquer atribuição
ou de autor.
Para mais informações, consulte a documentação sobre atribuições.