Completamento automatico dei luoghi (novità)

Il servizio Autocomplete (New) è un'API per iOS che restituisce suggerimenti di luoghi in risposta a una richiesta. Nella richiesta, specifica una stringa di ricerca testuale e i confini geografici che controllano l'area di ricerca.

Il servizio Autocomplete (New) può trovare corrispondenze con parole intere e sottostringhe dell'input, risolvendo nomi di luoghi, indirizzi e Plus Code. Le applicazioni possono quindi inviare query mentre l'utente digita, per fornire suggerimenti di luoghi in tempo reale.

I suggerimenti di luoghi sono luoghi, come attività, indirizzi e punti di interesse, basati sulla stringa di testo di input e sull'area di ricerca specificate.

Ad esempio, chiami l'API utilizzando come input una stringa che contiene un input utente parziale, "Spagh", con l'area di ricerca limitata a New York City. La risposta contiene quindi un elenco di suggerimenti di luoghi che corrispondono alla stringa di ricerca e all'area di ricerca, ad esempio il ristorante denominato "Cafe Spaghetti", insieme ai dettagli del luogo.

I suggerimenti di luoghi restituiti sono progettati per essere presentati all'utente in modo che possa selezionare il luogo desiderato. Puoi effettuare una richiesta Place Details (New) per ottenere ulteriori informazioni su uno dei suggerimenti di luoghi restituiti.

Puoi integrare la funzionalità di completamento automatico (nuovo) nella tua app in due modi principali:

• Ottieni previsioni sui luoghi in modo programmatico: chiama l'API direttamente per recuperare le previsioni e visualizzarle in un'interfaccia utente personalizzata.
• Aggiungi il widget Place Autocomplete: fornisce un'esperienza di completamento automatico della ricerca pronta all'uso che mostra le previsioni man mano che l'utente digita.

Ottieni previsioni sui luoghi in modo programmatico

Richieste Autocomplete (New)

Crea una richiesta di completamento automatico chiamando un metodo su GMSPlacesClient. Puoi passare i parametri nell'oggetto GMSAutocompleteRequest. La risposta fornisce suggerimenti di completamento automatico all'interno di un oggetto GMSAutocompletePlaceSuggestion.

La chiave API e i parametri query sono obbligatori. Puoi anche includere GMSAutocompleteSessionToken per associare le richieste a una sessione di fatturazione e GMSAutocompleteFilter da applicare ai risultati.

Per ulteriori informazioni sui parametri obbligatori e facoltativi, consulta la sezione sui parametri di questo documento.

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

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))")
        }
      }
    })

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

Risposte di Autocomplete (New)

Il completamento automatico restituisce un array di un massimo di cinque istanze GMSAutocompleteSuggestion. L'array contiene:

• placeID
• types: i tipi che si applicano a questo luogo.
• distanceMeters: distanza dall'origine.
• attributedFullText: testo completo di un suggerimento leggibile da una persona.
• attributedPrimaryText: testo principale di un suggerimento leggibile da una persona.
• attributedSecondaryText: testo secondario leggibile di un suggerimento.
• structuredFormat: il nome specifico e il testo di disambiguazione, ad esempio la città o la regione.

Parametri obbligatori

query

La stringa di testo in cui cercare. Specifica parole intere e sottostringhe, nomi di luoghi, indirizzi e Plus Code. Il servizio Autocomplete (New) restituisce le corrispondenze candidate in base a questa stringa e ordina i risultati in base alla loro pertinenza percepita.

Parametri facoltativi

sessionToken

I token di sessione sono stringhe generate dagli utenti che monitorano le chiamate di Autocomplete (New), sia quelle effettuate tramite il widget sia quelle programmatiche, come "sessioni". Autocomplete (New) utilizza i token di sessione per raggruppare le fasi di query e selezione di una ricerca con completamento automatico dell'utente in una sessione distinta ai fini della fatturazione.

Puoi esporre il token di sessione di Place Autocomplete per passarlo ad altri servizi che non fanno parte di Places SDK for iOS, ad esempio Address Validation:

let token = AutocompleteSessionToken()
let filter = AutocompleteFilter(origin: CLLocationCoordinate2DMake(39.7, -94.5))
let request = AutocompleteRequest(query: "Piz", sessionToken: token, filter: filter)

PlacesClient.shared.fetchAutocompleteSuggestions(request: request) {
    case .success(let suggestions):
      ...
    case .failure(let placesError):
      print(placesError) 
}

// pass token's string format to use with a service that is not a part of iOS SDK.
print("token: \(token)")

GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Piz"];
GMSAutocompleteSessionToken *token = [[GMSAutocompleteSessionToken alloc] init];
request.sessionToken = token;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:39.7 longitude:-94.5];
filter.locationBias = GMSPlaceRectangularLocationOption(topLocation, bottomLocation);

request.filter = filter;
 [[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request
                     callback:^(NSArray<GMSAutocompleteSuggestion *> *_Nullable results,
                                NSError *_Nullable error) {
  ...
}];

// pass token's string format to use with a service that is not a part of iOS SDK.
NSLog(@"%@", token.description);

Per saperne di più, consulta Token di sessione.

Parametri AutocompleteFilter facoltativi

tipi

Un luogo può avere un solo tipo principale tra i tipi della Tabella A o della Tabella B associati. Ad esempio, il tipo principale potrebbe essere mexican_restaurant o steak_house.

Per impostazione predefinita, l'API restituisce tutti i luoghi in base al parametro input, indipendentemente dal valore del tipo principale associato al luogo. Limita i risultati a un determinato tipo o tipi principali passando il parametro types.

Utilizza questo parametro per specificare fino a cinque valori di tipo della Tabella A o della Tabella B. Un luogo deve corrispondere a uno dei valori del tipo principale specificati per essere incluso nella risposta.

La richiesta viene rifiutata con un errore INVALID_REQUEST se:

• Sono stati specificati più di cinque tipi.
• Vengono specificati tutti i tipi non riconosciuti.

Ad esempio, per limitare i risultati ai negozi di articoli sportivi, specifica questo tipo nel tuo AutocompleteFilter:

let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
  

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
  

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];

Paesi

Includi solo i risultati dell'elenco di regioni specificate, indicate come un array di un massimo di 15 valori di due caratteri ccTLD ("dominio di primo livello"). Se omesso, non vengono applicate limitazioni alla risposta. Ad esempio, per limitare le regioni alla Germania e alla Francia:

let filter = AutocompleteFilter(countries: ["DE", "FR"])
  

let filter = GMSAutocompleteFilter()
filter.countries = ["DE", "FR"]

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.countries = @[ @"DE", @"FR" ];

Se specifichi sia locationRestriction sia countries, i risultati si trovano nell'area di intersezione delle due impostazioni.

inputOffset

L'offset dei caratteri Unicode basato su zero che indica la posizione del cursore in input. La posizione del cursore può influire sulle previsioni restituite. Se vuoto, il valore predefinito è la lunghezza di input.

locationBias o locationRestriction

Per definire l'area di ricerca, puoi specificare locationBias o locationRestriction, ma non entrambi. Pensa a locationRestriction come alla regione in cui devono trovarsi i risultati e a locationBias come alla regione a cui i risultati devono essere vicini, ma che possono trovarsi al di fuori dell'area.

• locationBias specifica un'area in cui cercare. Questa località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata.

• locationRestriction specifica un'area in cui cercare. I risultati al di fuori dell'area specificata non vengono restituiti.

Specifica la regione locationBias o locationRestriction come area visibile rettangolare o come cerchio.

Un cerchio è definito dal punto centrale e dal raggio in metri. Il raggio deve essere compreso tra 0,0 e 50.000,0 inclusi. Il valore predefinito è 0.0. Per locationRestriction, devi impostare il raggio su un valore maggiore di 0,0. In caso contrario, la richiesta non restituisce risultati.

Ad esempio:

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

let center = CLLocationCoordinate2DMake(40.730610, -73.935242)
let radius = 1000.0

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(40.730610, -73.935242);
radius = 1000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);

Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due punti low e high diagonalmente opposti. Un'area visibile è considerata una regione chiusa, il che significa che include il suo confine. I limiti di latitudine devono essere compresi tra -90 e 90 gradi inclusi, mentre i limiti di longitudine devono essere compresi tra -180 e 180 gradi inclusi:

• Se low = high, l'area visibile è costituita da quel singolo punto.
• Se low.longitude > high.longitude, l'intervallo di longitudine è invertito (la finestra visiva attraversa la linea di longitudine di 180 gradi).
• Se low.longitude = -180 gradi e high.longitude= 180 gradi, l'area visibile include tutte le longitudini.
• Se low.longitude = 180 gradi e high.longitude = -180 gradi, l'intervallo di longitudine è vuoto.

Sia low che high devono essere compilati e la casella rappresentata non può essere vuota. Un'area visibile vuota genera un errore.

Ad esempio, questa area visibile racchiude completamente New York City:

let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087)
let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051)

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

let high = CLLocationCoordinate2DMake(40.921628, -73.700051)
let low = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceRectangularLocationOption(high, low)

CLLocationCoordinate2D high = CLLocationCoordinate2DMake(40.477398, -74.259087);
CLLocationCoordinate2D low = CLLocationCoordinate2DMake(440.921628, -73.700051);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceRectangularLocationOption(high, low);

origine

Il punto di partenza da cui calcolare la distanza in linea retta fino alla destinazione (restituita come distanceMeters). Se questo valore viene omesso, la distanza in linea retta non verrà restituita. Devono essere specificate come coordinate di latitudine e longitudine:

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

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

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];

filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude: -122.077023];

regionCode

Il codice regione utilizzato per formattare la risposta, specificato come valore ccTLD ("dominio di primo livello") di due caratteri. La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni degne di nota. Ad esempio, il ccTLD del Regno Unito è "uk " (.co.uk), mentre il suo codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Regno Unito di Gran Bretagna e Irlanda del Nord").

Se specifichi un codice regione non valido, l'API restituisce un errore INVALID_ARGUMENT. Il parametro può influire sui risultati in base alla legge vigente.

shouldIncludePureServiceAreaBusinesses

Se true, restituisce le attività al domicilio del cliente nell'array di risposta. Un'attività al domicilio del cliente è un'attività che effettua consegne a domicilio o che raggiunge direttamente i clienti, ma che non presta servizio ai clienti presso l'indirizzo dell'attività.

Ad esempio:

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.shouldIncludePureServiceAreaBusinesses = YES;

Aggiungi il widget Place Autocomplete

Per offrire più facilmente un'esperienza di completamento automatico dei luoghi coerente, puoi aggiungere il widget Place Autocomplete alla tua app. Il widget fornisce un'interfaccia dedicata a schermo intero che gestisce l'input dell'utente e mostra le previsioni dei luoghi all'utente, restituendo al contempo oggetti AutocompletePlaceSuggestion all'app. Puoi quindi effettuare una richiesta Place Details (New) per ottenere ulteriori informazioni su una qualsiasi delle previsioni dei luoghi.

Come quando ottieni le previsioni sui luoghi in modo programmatico, il widget Place Autocomplete ti consente di utilizzare i token di sessione per raggruppare le richieste di completamento automatico in una sessione ai fini della fatturazione. Puoi passare un token di sessione chiamando AutocompleteSessionToken().

Se non fornisci un token di sessione, il widget ne creerà uno per il completamento automatico, che potrà poi essere ottenuto dal callback onSelection. Per ulteriori informazioni sull'utilizzo dei token di sessione, consulta Informazioni sui token di sessione.

Quando il valore di associazione show è impostato su true, l'utente viene indirizzato a una visualizzazione a schermo intero in cui può selezionare un luogo. Man mano che l'utente digita, il widget restituisce suggerimenti per luoghi come attività, indirizzi e punti d'interesse. Quando l'utente seleziona un luogo, il widget chiama il gestore onSelection con il luogo selezionato e chiude la visualizzazione a schermo intero.

Parametri del widget Place Autocomplete

Oltre ai parametri disponibili in modo programmatico, il widget Place Autocomplete offre anche i seguenti parametri.

mostra

show specifica se il widget viene mostrato.

onSelection

La chiusura da eseguire quando viene selezionato un luogo.

onError

La chiusura da eseguire quando si verifica un errore. Se si verifica un errore, verrà passato un PlacesError.

Personalizzazione di contenuti e temi

I parametri AutocompleteUICustomization specificano le personalizzazioni della UI da applicare al widget. Le opzioni di personalizzazione sono:

• AutocompleteListDensity. Questo parametro ti consente di scegliere la densità dell'elenco di suggerimenti, ovvero multiLine o twoLine.
• AutocompleteUIIcon. Questo parametro ti consente di scegliere se mostrare l'icona predefinita per ogni elemento dell'elenco.
• theme. Questo parametro specifica un tema personalizzato che sostituisce uno qualsiasi degli attributi di stile predefiniti. Puoi personalizzare i colori, la tipografia, la spaziatura, i bordi e gli angoli del componente Place Autocomplete. Il valore predefinito è PlacesMaterialTheme. Tutti gli attributi del tema che non vengono sostituiti utilizzano gli stili predefiniti.

Guarda un esempio di codice completo.

Esempi di Autocomplete (New)

Utilizza locationRestriction e locationBias

Il completamento automatico (nuovo) utilizza la priorità IP per impostazione predefinita per controllare l'area di ricerca. Con la personalizzazione in base all'IP, l'API utilizza l'indirizzo IP del dispositivo per personalizzare i risultati. Facoltativamente, puoi utilizzare locationRestriction o locationBias, ma non entrambi, per specificare un'area di ricerca.

La limitazione della località specifica l'area in cui eseguire la ricerca. I risultati al di fuori dell'area specificata non vengono restituiti. L'esempio seguente utilizza la limitazione della località per limitare la richiesta a una limitazione della località circolare con un raggio di 5000 metri centrato su San Francisco:

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

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))")
        }
      }
    })

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

Con l'impostazione di bias della località, la località funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, inclusi i risultati al di fuori dell'area specificata. L'esempio seguente modifica la richiesta precedente per utilizzare l'impostazione di priorità della località:

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

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))")
        }
      }
    })

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

Tipi di utilizzo

Utilizza il parametro types per limitare i risultati di una richiesta a un determinato tipo, come elencato nella Tabella A e nella Tabella B. Puoi specificare un array di massimo cinque valori. Se omesso, vengono restituiti tutti i tipi.

L'esempio seguente specifica una stringa di query "Soccer" e utilizza il parametro types per limitare i risultati alle attività di tipo "sporting_goods_store":

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

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))")
        }
      }
    })

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

Usa origine

Quando includi il parametro origin nella richiesta, specificato come coordinate di latitudine e longitudine, l'API include nella risposta la distanza in linea retta dall'origine alla destinazione. La risposta restituisce la distanza come distanceMeters.

Questo esempio imposta l'origine sul centro di San Francisco:

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

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))")
        }
      }
    })

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

Personalizza contenuti e tema

let uiCustomization = AutocompleteUICustomization(
    listDensity: .multiLine,
    listItemIcon: .noIcon,
    theme: PlacesMaterialTheme()
)

Aggiungi un widget Place Autocomplete (codice completo)

struct PlaceAutocompleteDemoView: View {

  @State private var fetchedPlace: Place?
  @State private var placesError: PlacesError?
  @State private var showWidget = false

  public var body: some View {
    VStack {
      Button("Search for a place") {
        showWidget.toggle()
      }
      .placeAutocomplete(
        show: $showWidget,
        onSelection: { (autocompletePlaceSuggestion, autocompleteSessionToken) in
          Task {
            let placesClient = await PlacesClient.shared
            let fetchPlaceRequest = FetchPlaceRequest(
              placeID: autocompletePlaceSuggestion.placeID,
              placeProperties: [.displayName, .formattedAddress],
              sessionToken: autocompleteSessionToken
            )

            switch await placesClient.fetchPlace(with: fetchPlaceRequest) {
            case .success(let place):
              print("Fetched place: \(place)")
              self.fetchedPlace = place
            case .failure(let placesError):
              print("Failed to fetch place: \(placesError)")
              self.placesError = placesError
            }
          }
        },
        onError: { placesError in
          self.placesError = placesError
        }
      )
    }
  }
}

Ottimizzazione del completamento automatico (nuovo)

Questa sezione descrive le best practice per aiutarti a sfruttare al meglio il servizio Autocomplete (New).

Ecco alcune linee guida generali:

• Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget di completamento automatico (nuovo) dell'API Maps JavaScript, il widget di completamento automatico (nuovo) di Places SDK for Android o il widget di completamento automatico (nuovo) di Places SDK for iOS.
• Comprendi i campi di dati essenziali di Autocomplete (New) fin dall'inizio.
• I campi di polarizzazione e limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
• Utilizza la gestione degli errori per assicurarti che l'app si degradi correttamente se l'API restituisce un errore.
• Assicurati che la tua app gestisca i casi in cui non viene effettuata alcuna selezione e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione dei costi di base

Per ottimizzare il costo di utilizzo del servizio Autocomplete (New), utilizza le maschere di campo nei widget Place Details (New) e Autocomplete (New) per restituire solo i campi di dati di Autocomplete (New) di cui hai bisogno.

Ottimizzazione avanzata dei costi

Valuta l'implementazione programmatica di Autocomplete (New) per accedere allo SKU: Autocomplete Request pricing e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details (New). I prezzi per richiesta abbinati all'API Geocoding sono più convenienti dei prezzi per sessione (basati sulla sessione) se sono soddisfatte entrambe le seguenti condizioni:

• Se hai bisogno solo della latitudine e della longitudine o dell'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni a un costo inferiore rispetto a una chiamata di Place Details (New).
• Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro o meno richieste di previsioni di completamento automatico (nuovo), i prezzi per richiesta possono essere più convenienti rispetto ai prezzi per sessione.

L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details (New) per la tua applicazione, a seconda delle prestazioni di utilizzo di Autocomplete (New). L'efficienza di Autocomplete (New) di ogni applicazione varia a seconda di ciò che gli utenti inseriscono, di dove viene utilizzata l'applicazione e se sono state implementate le best practice per l'ottimizzazione delle prestazioni.

Per trovare il numero medio di richieste per la tabella, analizza quanti caratteri un utente digita in media prima di selezionare una previsione di Autocomplete (New) nella tua applicazione.

Autocomplete (New) basato su sessione con Place Details (New)

Utilizza Autocomplete (New) basato su sessione con Place Details (New).
Poiché la tua applicazione richiede Place Details (New), come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione di Autocomplete (New) deve utilizzare un token di sessione (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per sessione, oltre agli SKU di Places applicabili, a seconda dei campi di dati dei luoghi richiesti.¹

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Autocomplete (New) sia la richiesta Place Details (New) sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di dati di Autocomplete (New) di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le tue richieste Autocomplete (New). Quando richiedi i dettagli dei luoghi (nuova versione) relativi alla previsione selezionata, includi i seguenti parametri:

1. L'ID luogo della risposta di Autocomplete (New)
2. Il token di sessione utilizzato nella richiesta Autocomplete (New)
3. Il parametro fields che specifica i campi di dati di Autocomplete (New) di cui hai bisogno

Autocomplete (New) per richiesta con l'API Geocoding

Implementa Autocomplete (New) in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione di luogo selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine. L'esecuzione di quattro richieste Autocomplete Requests più una chiamata all'API Geocoding relativa alla previsione del luogo selezionato è inferiore al costo per sessione di Autocomplete (New).¹

Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con un numero ancora minore di caratteri.

Autocomplete (New) basato su sessione per applicazioni solo per indirizzi

Utilizza Autocomplete (New) basato su sessione con Place Details (New).
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di Autocomplete (New) supera il costo dei prezzi per sessione, la tua implementazione di Autocomplete (New) deve utilizzare un token di sessione sia per le richieste di Autocomplete (New) sia per la richiesta Place Details (New) associata per sessione. ¹

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Autocomplete (New) sia la richiesta Place Details (New) sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le richieste Autocomplete (New). Quando richiedi i dettagli dei luoghi (nuova versione) relativi alla previsione selezionata, includi i seguenti parametri:

1. L'ID luogo della risposta di Autocomplete (New)
2. Il token di sessione utilizzato nella richiesta Autocomplete (New)
3. Il parametro fields che specifica i campi, ad esempio indirizzo e geometria

Valuta la possibilità di ritardare le richieste di Autocomplete (New)
Puoi adottare strategie come ritardare una richiesta di Autocomplete (New) finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione effettui meno richieste. Ad esempio, se effettui richieste di Autocomplete (New) per ogni carattere dopo che l'utente ha digitato il terzo carattere, se l'utente digita sette caratteri e poi seleziona una previsione per la quale effettui una richiesta API Geocoding, il costo totale sarà di 4 richieste Autocomplete (New) Per Request + Geocoding.¹

Se ritardando le richieste puoi ridurre la media delle richieste programmatiche a meno di quattro, puoi seguire le indicazioni per l'implementazione di Autocomplete (New) con l'API Geocoding. Tieni presente che il ritardo delle richieste può essere percepito come latenza dall'utente, che potrebbe aspettarsi di vedere le previsioni a ogni nuova pressione di un tasto.

Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che stanno cercando con meno caratteri.

Best practice per le prestazioni

Le seguenti linee guida descrivono i modi per ottimizzare le prestazioni di Autocomplete (New):

• Aggiungi limitazioni in base al paese, localizzazione e (per le implementazioni programmatiche) preferenza sulla lingua alla tua implementazione di Autocomplete (New). La preferenza sulla lingua non è necessaria con i widget, poiché questi ultimi scelgono le preferenze sulla lingua dal browser o dal dispositivo mobile dell'utente.
• Se Autocomplete (New) è accompagnato da una mappa, puoi influenzare la località in base all'area visibile della mappa.
• In situazioni in cui un utente non sceglie una delle previsioni di Autocomplete (New), in genere perché nessuna di queste previsioni è l'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
  • Se prevedi che l'utente inserisca solo informazioni sull'indirizzo, riutilizza l'input utente originale in una chiamata all'API Geocoding.
  • Se prevedi che l'utente inserisca query per un luogo specifico in base al nome o all'indirizzo, utilizza una richiesta Place Details (New). Se i risultati sono previsti solo in una regione specifica, utilizza la localizzazione.
  Altri scenari in cui è meglio utilizzare l'API Geocoding includono:
  • Utenti che inseriscono indirizzi di unità secondarie, ad esempio indirizzi di unità o appartamenti specifici all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praga" restituisce una previsione parziale in Autocomplete (New).
  • Utenti che inseriscono indirizzi con prefissi di segmenti stradali come "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.

Bias di località

Per orientare i risultati verso un'area specifica, passa un parametro location e un parametro radius. In questo modo, Autocomplete (New) preferisce mostrare i risultati all'interno dell'area definita. Potrebbero comunque essere visualizzati risultati al di fuori dell'area definita. Puoi utilizzare il parametro includedRegionCodes per filtrare i risultati in modo da mostrare solo i luoghi all'interno di un paese specificato.

Limitazione della località

Limita i risultati a un'area specificata passando un parametro locationRestriction.

Puoi anche limitare i risultati alla regione definita da location e da un parametro radius aggiungendo il parametro locationRestriction . In questo modo, Autocomplete (New) restituisce solo i risultati all'interno di quella regione.