Place Autocomplete (novo)

Selecione a plataforma: Android iOS JavaScript Web Service

O serviço de preenchimento automático (novo) é uma API do 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 de preenchimento automático (novo) pode corresponder a palavras e substrings completas da entrada, resolvendo nomes de lugares, endereços e códigos de mais. Portanto, os aplicativos podem enviar consultas conforme o usuário digita, para fornecer sugestões de lugares em tempo real.

As sugestões de lugar são lugares, como empresas, endereços e pontos de interesse, com base na string de texto de entrada especificada e na área de pesquisa.

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 a Nova York. A resposta contém uma lista de sugestões de lugares que correspondem à string de pesquisa e à área de pesquisa, como o restaurante "Cafe Spaghetti", além de detalhes sobre o lugar.

As sugestões de lugar retornadas são projetadas para serem apresentadas ao usuário para que ele possa selecionar o lugar desejado. Você pode fazer uma solicitação de Place Details (New) para receber mais informações sobre qualquer uma das sugestões de lugar retornadas.

Observação: é necessário ativar a API original de preenchimento automático para usar a funcionalidade do widget. A API original e a nova podem ser ativadas ao mesmo tempo. Consulte o guia de migração do preenchimento automático de lugares (novo) para mais informações.

Solicitações de preenchimento automático (novas)

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 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.
    }
  }
}];

SDK do Places Swift para iOS (pré-lançamento)

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 preenchimento automático (novas)

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 esse lugar.
• distanceMeters: distância da origem.
• attributedFullText: texto completo de uma sugestão legível por humanos.
• 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 elimina a ambiguidade, como cidade ou região.

Parâmetros obrigatórios

consulta

A string de texto em que pesquisar. Especifique palavras e substrings completas, nomes de lugares, endereços e códigos Plus. O serviço de preenchimento automático (novo) retorna correspondências de candidatos com base nessa string e ordena os resultados com base na relevância percebida.

Parâmetros opcionais

tipos

Um lugar só pode ter um tipo principal de tabela A ou tabela B associado a ele. Por exemplo, o tipo principal pode ser mexican_restaurant ou steak_house.

Por padrão, a API retorna todos os lugares com base no parâmetro input, independente do valor do tipo principal associado ao lugar. Restringir os resultados a um determinado tipo primário ou tipos primários transmitindo o parâmetro types.

Use esse parâmetro para especificar até cinco valores de tipo da Tabela A ou da Tabela B. Um lugar precisa corresponder a um dos valores de tipo principal especificados para ser incluído na resposta.

A solicitação é rejeitada com um erro INVALID_REQUEST se:

• Mais de cinco tipos foram especificados.
• Todos os tipos não reconhecidos são especificados.

países

Inclua apenas os resultados da lista de regiões especificadas, especificadas como uma matriz de até 15 valores de dois caracteres de ccTLDs ("domínio de nível superior"). Se omitido, nenhuma restrição é 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" ];

SDK do Places Swift para iOS (pré-lançamento)

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 do caractere Unicode com base 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 vazio, o padrão é a duração de input.

locationBias ou locationRestriction

Você pode especificar locationBias ou locationRestriction, mas não ambos, para definir a área de pesquisa. Pense em locationRestriction como a especificação da região em que os resultados precisam estar e em locationBias como a especificação da região em que os resultados precisam estar próximos, mas podem estar fora da área.

Observação: se você omitir locationBias e locationRestriction, a API vai usar a polarização de IP por padrão. Com a distorção de IP, a API usa o endereço IP do dispositivo para distorcer os resultados.

• locationBias especifica uma área para pesquisar. Esse local serve como uma viés, o que significa que os resultados em torno do local especificado podem ser retornados, incluindo resultados fora da área especificada.

• locationRestriction especifica uma área para pesquisar. Os resultados fora da área especificada não são retornados.

Especifique a região locationBias ou locationRestriction como uma viewport 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 500.000,0. O valor padrão é 0,0. Para locationRestriction, defina o raio como um valor maior que 0,0. Caso contrário, a solicitação não retorna 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);

SDK do Places Swift para iOS (pré-lançamento)

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

let bias = CircularCoordinateRegion(center: center, radius: 1000.0)

let filter = AutocompleteFilter(coordinateRegionBias: bias)      
  

Um retângulo é uma viewport de latitude-longitude, representada como dois pontos low e high opostos diagonalmente. Uma viewport é considerada uma região fechada, ou seja, ela inclui o limite. Os limites de latitude precisam variar entre -90 e 90 graus, e os limites de longitude precisam variar entre -180 e 180 graus:

• Se low = high, a viewport consiste nesse único ponto.
• Se low.longitude > high.longitude, o intervalo de longitude será invertido (a viewport cruza a linha de longitude de 180 graus).
• Se low.longitude = -180 graus e high.longitude= 180 graus, o viewport inclui todas as longitudes.
• Se low.longitude = 180 graus e high.longitude = -180 graus, o intervalo de longitude estará vazio.

low e high precisam ser preenchidos, e a caixa representada não pode estar vazia. Uma viewport vazia resulta em um erro.

Por exemplo, esta viewport inclui toda a cidade de 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);

SDK do Places Swift para iOS (pré-lançamento)

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];

SDK do Places Swift para iOS (pré-lançamento)

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))
  

regionCode

O código da região usado para formatar a resposta, especificado como um valor de dois caracteres de ccTLD ("domínio de nível superior"). A maioria dos códigos ccTLD é idêntica aos códigos ISO 3166-1, com algumas exceções. Por exemplo, o ccTLD do Reino Unido é "uk" (.co.uk), enquanto o código ISO 3166-1 é "gb" (tecnicamente para a entidade "O Reino Unido da Grã-Bretanha e Irlanda do Norte").

Se você especificar um código de região inválido, a API vai retornar um erro INVALID_ARGUMENT. O parâmetro pode afetar os resultados com base na legislação aplicável.

sessionToken

Os tokens de sessão são strings geradas pelo usuário que rastreiam chamadas de preenchimento automático (novo) como "sessões". O preenchimento automático (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 preenchimento automático (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 polarizar os resultados. Você pode 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 centrada 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.
    }
  }
}];

SDK do Places Swift para iOS (pré-lançamento)

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 ênfase no local, o local serve como uma ênfase, o que significa que os resultados em torno do local especificado podem ser retornados, incluindo resultados fora da área especificada. O próximo exemplo muda a solicitação anterior para usar a ênfase na localização:

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.
    }
  }
}];

SDK do Places Swift para iOS (pré-lançamento)

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 types para restringir os resultados de uma solicitação a 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 "Soccer" 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.
    }
  }
}];

SDK do Places Swift para iOS (pré-lançamento)

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 a 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 até o 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.
      }
    }
}];

SDK do Places Swift para iOS (pré-lançamento)

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ão do serviço de preenchimento automático (novo) sem um mapa, é necessário incluir o logotipo do Google exibido inline com o campo/resultados de pesquisa. Para mais informações, consulte Exibir o logotipo e as atribuições do Google.