O serviço Autocomplete (novo) é uma API para iOS que retorna sugestões de lugares em resposta a uma solicitação. Na solicitação, especifique uma string de pesquisa de texto e limites geográficos que controlam a área de pesquisa.
O serviço Autocomplete (novo) pode corresponder palavras completas e substrings da entrada, resolvendo nomes de lugares, endereços e Plus Codes. À medida que o usuário digita, os aplicativos enviam consultas e sugerem locais instantaneamente.
As sugestões de lugares são lugares, como empresas, endereços e pontos de interesse, com base na string de texto de entrada e na área de pesquisa especificadas.
Por exemplo, você chama a API usando como entrada uma string que contém uma entrada parcial do usuário, "Spagh", com a área de pesquisa limitada à cidade de Nova York. A resposta contém uma lista de sugestões de lugares que correspondem à string e à área de pesquisa, como o restaurante "Cafe Spaghetti", além de detalhes sobre o lugar.
As sugestões de lugares retornadas são apresentadas ao usuário para que ele possa selecionar o lugar que ele quer. Você pode fazer uma solicitação de Place Details (novo) para ver mais informações sobre qualquer uma das sugestões de lugares retornadas.
Solicitações de Autocomplete (novo)
Crie uma solicitação de preenchimento automático chamando um método no
GMSPlaceClient
.
É possível transmitir parâmetros no
objeto
GMSAutocompleteRequest
. A resposta fornece sugestões de preenchimento automático em um objeto GMSAutocompletePlaceSuggestion
.
A chave de API e os parâmetros query
são obrigatórios. Também é possível incluir
GMSAutocompleteSessionToken
para associar solicitações a uma sessão de faturamento e
GMSAutocompleteFilter
para aplicar aos resultados.
Para mais informações sobre os parâmetros obrigatórios e opcionais, consulte a seção de parâmetros deste documento.
Swift
let token = GMSAutocompleteSessionToken() let northWestBounds = CLLocationCoordinate2DMake(40.921628, -73.700051) let southEastBounds = CLLocationCoordinate2DMake(40.477398, -74.259087) let filter = GMSAutocompleteFilter() filter.types = [kGMSPlaceTypeRestaurant] filter.locationBias = GMSPlaceRectangularLocationOption(northWestBounds, southEastBounds) let request = GMSAutocompleteRequest(query:"Spagh") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))") } } })
Objective-C
CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137); CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023); GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.types = @[ kGMSPlaceTypeRestaurant ]; filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest); GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
GooglePlacesSwift
let center = (37.3913916, -122.0879074) let northEast = (37.388162, -122.088137) let southWest = (37.395804, -122.077023) let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest) let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias) let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): // Handle suggestions. case .failure(let placesError): // Handle error. }
Respostas de Autocomplete (novo)
O preenchimento automático retorna uma matriz de até cinco instâncias de GMSAutocompleteSuggestion
. A matriz contém:
placeID
types
: tipos que se aplicam a este lugar.distanceMeters
: distância da origem.attributedFullText
: texto completo legível por humanos de uma sugestão.attributedPrimaryText
: texto principal legível por humanos de uma sugestão.attributedSecondaryText
: texto secundário legível por humanos de uma sugestão.structuredFormat
: o nome específico e o texto que não tem ambiguidade, como cidade ou região.
Parâmetros obrigatórios
consulta
A string de texto na qual pesquisar. Especifique palavras completas e substrings, nomes de lugares, endereços e Plus Codes. O serviço Autocomplete (novo) retorna correspondências possíveis com base nessa string e ordena os resultados com base na relevância percebida.
Parâmetros opcionais
Tipos
Um lugar só pode ter um único tipo principal associado aos tipos Tabela A ou B.
Por exemplo, o tipo principal pode ser mexican_restaurant
ou steak_house
.
Por padrão, a API retorna todos os locais com base no parâmetro input
, seja qual for o valor do tipo principal associado ao lugar. Restrinja os resultados
para que sejam de um determinado tipo primário ou principais, transmitindo o
parâmetro types
.
Use esse parâmetro para especificar até cinco valores de tipo da Tabela A ou da Tabela B. Um local precisa corresponder a um dos valores de tipo primário especificados para ser incluído na resposta.
A solicitação será rejeitada com um erro INVALID_REQUEST
se:
- Mais de cinco tipos foram especificados.
- Todos os tipos não reconhecidos foram especificados.
países
Inclua somente os resultados da lista de regiões especificadas, definidas como uma matriz de até 15 valores de dois caracteres ccTLD ("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:
Swift
let filter = GMSAutocompleteFilter() filter.countries = ["DE", "FR"]
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.countries = @[ @"DE", @"FR" ];
GooglePlacesSwift
let filter = AutocompleteFilter(countries: ["DE", "FR"])
Se você especificar locationRestriction
e countries
, os resultados serão localizados na área de interseção das duas configurações.
inputOffset
O deslocamento de caracteres Unicode baseado 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
esvaziado, o padrão é o comprimento de input
.
locationBias ou locationRestriction
Para definir a área de pesquisa, especifique locationBias
ou locationRestriction
, mas não ambos. Pense em locationRestriction
como a especificação da região em que os resultados precisam estar e locationBias
como a especificação da região a que os resultados precisam estar próximos, mas que podem estar fora da área.
locationBias
especifica uma área a ser pesquisada. Essa localização serve como um viés, o 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
ou locationRestriction
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 precisa estar entre 0,0 e 50.000,0. O valor padrão é 0,0. Para locationRestriction
, você precisa definir o raio como um valor maior que 0,0.
Caso contrário, a solicitação não retornará resultados.
Exemplo:
Swift
let center = CLLocationCoordinate2DMake(40.730610, -73.935242) let radius = 1000.0 filter.locationBias = GMSPlaceCircularLocationOption(center, radius)
Objective-C
CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242); radius = 1000.0; GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
GooglePlacesSwift
let center = CLLocationCoordinate2DMake(40.477398, -74.259087) let bias = CircularCoordinateRegion(center: center, radius: 1000.0) let filter = AutocompleteFilter(coordinateRegionBias: bias)
Um retângulo é uma janela de visualização de latitude e longitude, representada como dois pontos diagonalmente opostos low
e high
. Uma janela de visualização é considerada
uma região fechada, ou seja, inclui seus limites. 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 janela de visualização consistirá nesse único ponto. - Se
low.longitude
>high.longitude
, o intervalo de longitude é invertido (a janela de visualização cruza a linha de 180 graus de longitude). - Se
low.longitude
= -180 graus ehigh.longitude
= 180 graus, a janela de visualização vai incluir todas as longitudes. - Se
low.longitude
= 180 graus ehigh.longitude
= -180 graus, o intervalo de longitude fica vazio.
low
e high
precisam ser preenchidos, 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 Nova York:
Swift
let high = CLLocationCoordinate2DMake(40.921628, -73.700051) let low = CLLocationCoordinate2DMake(40.477398, -74.259087) let filter = GMSAutocompleteFilter() filter.locationBias = GMSPlaceRectangularLocationOption(high, low)
Objective-C
CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087); CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051); GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.locationBias = GMSPlaceRectangularLocationOption(high, low);
GooglePlacesSwift
let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087) let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051) let filter = AutocompleteFilter(coordinateRegionBias: bias)
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. Precisa ser especificado como coordenadas de latitude e longitude:
Swift
let filter = GMSAutocompleteFilter() filter.origin = CLLocation(latitude: 37.395804, longitude: -122.077023)
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude: -122.077023];
GooglePlacesSwift
let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))
regionCode
O código de região usado para formatar a resposta, especificado como um valor de dois caracteres ccTLD ("top-level domain"). 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 seu 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 retornará um erro INVALID_ARGUMENT
. O parâmetro pode afetar os resultados com base na legislação aplicável.
sessionToken
Tokens de sessão são strings geradas pelo usuário que rastreiam chamadas de preenchimento automático (novo) como "sessões". O Autocomplete (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)
Usar locationRestriction e locationBias
O Autocomplete (novo) usa a polarização de IP por padrão para controlar a área de pesquisa. Com a polarização de IP, a API usa o endereço IP do dispositivo para direcionar os resultados. Também é possível usar locationRestriction
ou locationBias
, mas não ambos, para especificar uma área a ser pesquisada.
A restrição de local especifica a área a ser pesquisada. Os resultados fora da área especificada não são retornados. O exemplo a seguir usa a restrição de local para limitar a solicitação a uma restrição de local circular com um raio de 5.000 metros centrado em São Francisco:
Swift
let token = GMSAutocompleteSessionToken() let center = CLLocationCoordinate2DMake(37.775061, -122.419400) let radius = 5000.0 let filter = GMSAutocompleteFilter() filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius) let request = GMSAutocompleteRequest(query:"Piz") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))") } } })
Objective-C
CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400); radius = 5000.0; GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius); GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
GooglePlacesSwift
let center = (37.775061, -122.419400) let radius = 5000.0 let restriction = CircularCoordinateRegion(center: center, radius: radius) let filter = AutocompleteFilter(coordinateRegionRestriction: restriction) let token = AutocompleteSessionToken() let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): for suggestion in autocompleteSuggestions { switch suggestion { case .place: // Show place suggestion data. } } case .failure(let placesError): // Handle error. }
Com a polarização de local, a localização atua como um direcionamento, o que significa que os resultados ao redor do local especificado podem ser retornados, incluindo resultados fora da área especificada. O próximo exemplo muda a solicitação anterior para usar a polarização de local:
Swift
let token = GMSAutocompleteSessionToken() let center = CLLocationCoordinate2DMake(37.775061, -122.419400) let radius = 5000.0 let filter = GMSAutocompleteFilter() filter.locationBias = GMSPlaceCircularLocationOption(center, radius) let request = GMSAutocompleteRequest(query:"Piz") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))") } } })
Objective-C
CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400); radius = 5000.0; GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.locationBias = GMSPlaceCircularLocationOption(center, radius); GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
GooglePlacesSwift
let center = (37.775061, -122.419400) let radius = 5000.0 let bias = CircularCoordinateRegion(center: center, radius: radius) let filter = AutocompleteFilter(coordinateRegionBias: bias) let token = AutocompleteSessionToken() let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): for suggestion in autocompleteSuggestions { switch suggestion { case .place: // Show place suggestion data. } } case .failure(let placesError): // Handle error. }
Tipos de uso
Use o parâmetro de tipos para restringir os resultados de uma solicitação para que sejam de um determinado tipo, conforme listado na Tabela A e na Tabela B. É possível especificar uma matriz de até cinco valores. Se omitido, todos os tipos são retornados.
O exemplo a seguir especifica uma string de consulta de "Futebol" e usa o parâmetro "types" para restringir os resultados a estabelecimentos do tipo "sporting_goods_store"
:
Swift
let token = GMSAutocompleteSessionToken() let filter = GMSAutocompleteFilter() filter.types = ["sporting_goods_store"] let request = GMSAutocompleteRequest(query:"Soccer") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))") } } })
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.types = @[ "sporting_goods_store" ]; GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
GooglePlacesSwift
let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ]) let token = AutocompleteSessionToken() let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): for suggestion in autocompleteSuggestions { switch suggestion { case .place: // Show place suggestion data. } } case .failure(let placesError): // Handle error. }
Usar origem
Quando você inclui o parâmetro origin
na solicitação, especificado como
coordenadas de latitude e longitude, a API inclui a distância em linha reta
da origem ao destino na resposta. A resposta retorna a distância como distanceMeters
.
Este exemplo define a origem como o centro de São Francisco:
Swift
let token = GMSAutocompleteSessionToken() let origin = CLLocation(latitude: 37.7749, longitude: -122.4194) let filter = GMSAutocompleteFilter() filter.origin = origin let request = GMSAutocompleteRequest(query:"Amoeba") request.filter = filter request.sessionToken = token GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in if let error = error { print("Autocomplete error: \(error)") return } if let autocompleteResults = results { for result in autocompleteResults { print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText)) and distance: \(String(describing: result.placeSuggestion?.distanceMeters))") } } })
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023]; GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"]; request.sessionToken = token; request.filter = filter; [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){ // Handle response for (GMSAutocompleteSuggestion *suggestion in results) { if (suggestion.placeSuggestion) { // Show place suggestion data. } } }];
GooglePlacesSwift
let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194)) let token = AutocompleteSessionToken() let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter) switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) { case .success(let autocompleteSuggestions): for suggestion in autocompleteSuggestions { switch suggestion { case .place: // Show place suggestion data. } } case .failure(let placesError): // Handle error. }
Atribuições
Você pode usar o Autocomplete (novo), mesmo sem um mapa. Se você exibir um mapa, ele deverá ser do Google. Ao mostrar sugestões do serviço Autocomplete (novo) sem um mapa, é necessário incluir o logotipo do Google in-line com o campo de pesquisa/resultados. Para mais informações, consulte Como mostrar o logotipo e as atribuições do Google.