Completamento automatico dei luoghi (novità)

Il servizio Autocompletamento (nuovo) è un'API per iOS che restituisce suggerimenti di luoghi in risposta a una richiesta. Nella richiesta, specifica una stringa di ricerca di testo e limiti geografici che controllano l'area di ricerca.

Il servizio Completamento automatico (nuovo) può trovare corrispondenze per parole complete e sottostringhe dell'input, risolvendo i nomi di luoghi, indirizzi e codici plus. Le applicazioni possono quindi inviare query man mano che l'utente digita per fornire suggerimenti sui luoghi in tempo reale.

I suggerimenti di luoghi sono luoghi, come attività, indirizzi e punti d'interesse, in base alla stringa di testo inserita e all'area di ricerca specificata.

Ad esempio, chiami l'API utilizzando come input una stringa contenente un input parziale dell'utente, "Spagh", con l'area di ricerca limitata a New York. La risposta contiene un elenco di suggerimenti di luoghi corrispondenti 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 (Nuova) per avere ulteriori informazioni su uno dei suggerimenti di luoghi restituiti.

Richieste di completamento automatico (nuove)

Crea una richiesta di completamento automatico chiamando un metodo su GMSPlaceClient. 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 relativa ai parametri di questo documento.

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

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

Risposte con completamento automatico (novità)

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

• placeID
• types: 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 di un suggerimento leggibile da una persona.
• structuredFormat: il nome specifico e il testo per eliminare le ambiguità, ad esempio città o regione.

Parametri obbligatori

query

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

Parametri facoltativi

tipi

A un luogo può essere associato un solo tipo principale dei tipi Tabella A o Tabella B. 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 essere di un determinato tipo principale o di tipi principali passando il parametrotypes.

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 di 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.
• Eventuali tipi non riconosciuti vengono specificati.

Paesi

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

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

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

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

Se specifichi sia locationRestriction che countries, i risultati si trovano nella zona di intersezione delle due impostazioni.

inputOffset

Lo scarto del carattere Unicode a partire da 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

Puoi specificare locationBias o locationRestriction, ma non entrambi, per definire l'area di ricerca. Considera locationRestriction come la regione in cui devono trovarsi i risultati e locationBias come la regione in cui devono trovarsi i risultati, ma che può essere al di fuori dell'area.

• locationBias specifica un'area in cui cercare. Questa posizione funge da bias, il che significa che possono essere restituiti risultati relativi alla posizione specificata, inclusi 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 50000,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.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);

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)      
  

Un rettangolo è un'area visibile di latitudine e longitudine, rappresentata da due punti low e high diagonalmente opposti. Un viewport è considerato una regione chiusa, ovvero 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 (il viewport attraversa la linea di longitudine di 180 gradi).
• Se low.longitude = -180 gradi e high.longitude= 180 gradi, il visualizzatore 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 viewport vuoto genera un errore.

Ad esempio, questa visualizzazione inclusa racchiude completamente New York:

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

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

origine

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

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

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

regionCode

Il codice regione utilizzato per formattare la risposta, specificato come valore di due caratteri del dominio di primo livello nazionale ("top-level domain"). La maggior parte dei codici ccTLD è identica ai codici ISO 3166-1, con alcune eccezioni notevoli. Ad esempio, il TLD di primo livello del Regno Unito è "uk " (.co.uk), mentre il codice ISO 3166-1 è"gb " (tecnicamente per l'entità "Il 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.

sessionToken

I token di sessione sono stringhe generate dagli utenti che monitorano le chiamate di completamento automatico (Nuova) come "sessioni". La funzionalità di completamento automatico (nuova) utilizza i token di sessione per raggruppare le fasi di query e selezione di una ricerca di completamento automatico dell'utente in una sessione distinta ai fini della fatturazione. Per ulteriori informazioni, consulta la sezione Token sessione.

Esempi di completamento automatico (nuovo)

Utilizzare locationRestriction e locationBias

Per impostazione predefinita, la funzionalità di completamento automatico (nuova) utilizza la predisposizione IP per controllare l'area di ricerca. Con la predisposizione all'IP, l'API utilizza l'indirizzo IP del dispositivo per orientare i risultati. Se vuoi, puoi utilizzare locationRestriction o locationBias, ma non entrambi, per specificare un'area di ricerca.

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

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

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

Con la distorsione della posizione, la posizione funge da bias, il che significa che possono essere restituiti risultati relativi alla località specificata, inclusi quelli al di fuori dell'area specificata. L'esempio seguente modifica la richiesta precedente in modo da utilizzare il bias di geolocalizzazione:

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

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

Tipi di utilizzo

Utilizza il parametro types per limitare i risultati di una richiesta a un determinato tipo come indicato 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 "Calcio" e utilizza il parametro types per limitare i risultati agli stabilimenti di tipo "sporting_goods_store":

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

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

Utilizza l'origine

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

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

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

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

Attribuzioni

Puoi utilizzare il completamento automatico (nuovo) anche senza una mappa. Se mostri una mappa, deve essere una mappa di Google. Quando mostri i suggerimenti del servizio Autocompletamento (nuovo) senza una mappa, devi includere il logo di Google visualizzato in linea con il campo di ricerca/i risultati. Per ulteriori informazioni, consulta la sezione Visualizzare il logo di Google e le attribuzioni.