Der Autocomplete (New)-Dienst ist eine iOS API, die als Antwort auf eine Anfrage Ortsvorschläge zurückgibt. Geben Sie in der Anfrage einen Suchstring und geografische Grenzen an, die den Suchbereich einschränken.
Der Autocomplete (New)-Dienst findet Übereinstimmungen mit vollständigen Wörtern und Teilstrings der Eingabe, sodass sich Ortsnamen, Adressen und Plus Codes zuordnen lassen. Anwendungen können Abfragen senden, während der Nutzer tippt, und schon bei der Eingabe Ortsvorschläge ausgeben.
Ortsvorschläge sind Orte wie Unternehmen, Adressen und POIs, die auf dem angegebenen Eingabetextstring und dem Suchbereich basieren.
Sie rufen die API beispielsweise mit einem String auf, der eine unvollständige Nutzereingabe enthält, z. B. „Spagh“, und beschränken den Suchbereich auf New York City. Die Antwort enthält dann eine Liste mit Ortsvorschlägen, die dem Suchstring und dem Suchbereich entsprechen, z. B. das Restaurant „Cafe Spaghetti“, sowie Details zum Ort.
Die zurückgegebenen Ortsvorschläge sind so konzipiert, dass sie dem Nutzer präsentiert werden können, damit er den gewünschten Ort auswählen kann. Sie können eine Place Details (New)-Anfrage stellen, um weitere Informationen zu den zurückgegebenen Ortsvorschlägen zu erhalten.
Es gibt zwei Möglichkeiten, die Funktion „Automatische Vervollständigung (Neu)“ in Ihre App einzubinden:
- Ortsvorschläge programmatisch abrufen: Rufen Sie die API direkt auf, um Vorschläge abzurufen und in einer benutzerdefinierten Benutzeroberfläche anzuzeigen.
- Place Autocomplete-Widget hinzufügen: Damit erhalten Sie eine sofort einsatzbereite automatische Vervollständigung für die Suche, bei der Vorschläge angezeigt werden, während der Nutzer tippt.
Ortsvorschläge programmatisch abrufen
Autocomplete (New)-Anfragen
Erstellen Sie eine Anfrage zur automatischen Vervollständigung, indem Sie eine Methode für GMSPlacesClient aufrufen.
Sie können Parameter im Objekt GMSAutocompleteRequest übergeben. Die Antwort enthält automatisch vervollständigte Vorschläge in einem GMSAutocompletePlaceSuggestion-Objekt.
Der API-Schlüssel und die query-Parameter sind erforderlich. Sie können auch GMSAutocompleteSessionToken einfügen, um Anfragen mit einer Abrechnungssitzung zu verknüpfen, und GMSAutocompleteFilter, um die Ergebnisse zu filtern.
Places Swift SDK-Version
Erstellen Sie eine Anfrage zur automatischen Vervollständigung, indem Sie eine Methode für PlacesClient aufrufen.
Sie können Parameter im Objekt AutocompleteRequest übergeben. Die Antwort enthält automatisch vervollständigte Vorschläge in einem AutocompletePlaceSuggestion-Objekt.
Der API-Schlüssel und die query-Parameter sind erforderlich. Sie können auch AutocompleteSessionToken einfügen, um Anfragen mit einer Abrechnungssitzung zu verknüpfen, und AutocompleteFilter, um die Ergebnisse zu filtern.
Weitere Informationen zu erforderlichen und optionalen Parametern finden Sie im Abschnitt „Parameter“ in diesem Dokument.
Places Swift SDK
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. }
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. } } }];
Autocomplete (New)-Antworten
Die automatische Vervollständigung gibt ein Array mit bis zu fünf GMSAutocompleteSuggestion-Instanzen zurück. Das Array enthält:
placeIDtypes: Typen, die auf diesen Ort zutreffen.distanceMeters: Entfernung vom Ursprung.attributedFullText: Vollständiger, menschenlesbarer Text eines Vorschlags.attributedPrimaryText: Menschenlesbarer Primärtext eines Vorschlags.attributedSecondaryText: Menschenlesbarer sekundärer Text eines Vorschlags.structuredFormat: Der spezifische Name und der Text zur Unterscheidung, z. B. Stadt oder Region.
Erforderliche Parameter
Abfrage
Der Textstring, nach dem gesucht werden soll. Geben Sie vollständige Wörter und Teilstrings, Ortsnamen, Adressen und Plus Codes an. Der Autocomplete (New)-Dienst gibt mögliche Übereinstimmungen basierend auf dem String zurück, die nach erkannter Relevanz sortiert werden.
Optionale Parameter
sessionToken
Sitzungstokens sind vom Nutzer generierte Strings, mit denen Autocomplete (New)-Aufrufe (sowohl über das Widget als auch programmatisch) als „Sitzungen“ erfasst werden. In Autocomplete (New) werden Sitzungstokens verwendet, um die Abfrage- und Auswahlphasen einer Nutzeranfrage zur automatischen Vervollständigung zu Abrechnungszwecken zu einer separaten Sitzung zusammenzufassen.
Sie können das Sitzungstoken für „Place Autocomplete“ offenlegen, um es an andere Dienste zu übergeben, die nicht Teil des Places SDK for iOS sind, z. B. an die Address Validation API:
Places Swift SDK
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)")
Objective-C
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);
Weitere Informationen finden Sie unter Sitzungstokens.
Optionale AutocompleteFilter-Parameter
Typen
Ein Ort kann nur einen einzigen primären Typ aus Tabelle A oder Tabelle B haben.
Der primäre Typ könnte beispielsweise mexican_restaurant oder steak_house sein.
Standardmäßig gibt die API alle Orte basierend auf dem Parameter input zurück, unabhängig vom primären Typwert, der dem Ort zugeordnet ist. Sie können die Ergebnisse auf einen oder mehrere bestimmte primäre Typen beschränken, indem Sie den Parameter types übergeben.
Mit diesem Parameter können Sie bis zu fünf Typwerte aus Tabelle A oder Tabelle B angeben. Ein Ort muss mit einem der angegebenen primären Typwerte übereinstimmen, damit er in die Antwort aufgenommen wird.
Die Anfrage wird mit dem Fehler INVALID_REQUEST abgelehnt, wenn:
- Es wurden mehr als fünf Typen angegeben.
- Sie haben einen unbekannten Typ angegeben.
Wenn Sie die Ergebnisse beispielsweise auf Sportgeschäfte beschränken möchten, geben Sie diesen Typ in der AutocompleteFilter an:
Places Swift SDK
let filter = AutocompleteFilter(types: [ PlaceType(rawValue: "sporting_goods_store") ])
Swift
let filter = GMSAutocompleteFilter() filter.types = ["sporting_goods_store"]
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.types = @[ "sporting_goods_store" ];
Länder
Es werden nur Ergebnisse aus der Liste der angegebenen Regionen berücksichtigt. Diese werden als Array mit bis zu 15 ccTLD-Werten („Top-Level-Domain“) mit zwei Zeichen angegeben. Wenn dieses Feld weggelassen wird, werden keine Einschränkungen auf die Antwort angewendet. So beschränken Sie die Regionen beispielsweise auf Deutschland und Frankreich:
Places Swift SDK
let filter = AutocompleteFilter(countries: ["DE", "FR"])
Swift
let filter = GMSAutocompleteFilter() filter.countries = ["DE", "FR"]
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.countries = @[ @"DE", @"FR" ];
Wenn Sie sowohl locationRestriction als auch countries angeben, befinden sich die Ergebnisse im Schnittbereich der beiden Einstellungen.
inputOffset
Der nullbasierte Unicode-Zeichen-Offset, der die Cursorposition in input angibt. Die Cursorposition kann beeinflussen, welche Vervollständigungen zurückgegeben werden. Wenn das Feld leer ist, wird standardmäßig die Länge von input verwendet.
locationBias oder locationRestriction
Sie können entweder locationBias oder locationRestriction angeben, um den Suchbereich zu definieren, aber nicht beides. Mit locationRestriction wird die Region angegeben, in der die Ergebnisse liegen müssen. Mit locationBias wird die Region angegeben, in deren Nähe die Ergebnisse liegen müssen, aber auch außerhalb des Bereichs liegen können.
Mit
locationBiaswird ein Bereich für die Suche angegeben. Dieser Standort dient als Gewichtung. Das bedeutet, dass Ergebnisse in der Nähe des angegebenen Standorts zurückgegeben werden können, einschließlich Ergebnissen außerhalb des angegebenen Bereichs.Mit
locationRestrictionwird ein Bereich für die Suche angegeben. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben.
Geben Sie die Region locationBias oder locationRestriction als rechteckigen Darstellungsbereich oder als Kreis an.
Ein Kreis wird durch einen Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 liegen (jeweils einschließlich). Der Standardwert ist 0,0. Für locationRestriction müssen Sie den Radius auf einen Wert größer als 0,0 festlegen.
Andernfalls werden keine Ergebnisse zurückgegeben.
Beispiel:
Places Swift SDK
let center = CLLocationCoordinate2DMake(40.477398, -74.259087) let bias = CircularCoordinateRegion(center: center, radius: 1000.0) let filter = AutocompleteFilter(coordinateRegionBias: bias)
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);
Ein Rechteck ist ein Darstellungsbereich mit Breiten- und Längengrad, der durch zwei diagonal gegenüberliegende Punkte (low und high) dargestellt wird. Ein Darstellungsbereich gilt als geschlossene Region, d. h., er umfasst auch seine Grenze. Die Grenzen für den Breitengrad müssen zwischen -90 und 90 Grad liegen und die Grenzen für den Längengrad zwischen -180 und 180 Grad:
- Wenn
low=highist, besteht der Darstellungsbereich aus diesem einzelnen Punkt. - Wenn
low.longitude>high.longitude, wird der Längengradbereich invertiert (der Darstellungsbereich kreuzt den 180-Grad-Längengrad). - Wenn
low.longitude= -180 Grad undhigh.longitude= 180 Grad, umfasst der Darstellungsbereich alle Längengrade. - Wenn
low.longitude= 180 Grad undhigh.longitude= -180 Grad ist, ist der Längengradbereich leer.
Sowohl low als auch high müssen ausgefüllt sein und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.
Dieser Darstellungsbereich umschließt beispielsweise New York City vollständig:
Places Swift SDK
let northEast = CLLocationCoordinate2DMake(40.477398, -74.259087) let southWest = CLLocationCoordinate2DMake(40.921628, -73.700051) let filter = AutocompleteFilter(coordinateRegionBias: bias)
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);
origin
Der Ausgangspunkt, von dem aus die Luftlinie zum Ziel berechnet werden soll (zurückgegeben als distanceMeters). Wenn dieser Wert weggelassen wird, wird die Luftlinie nicht zurückgegeben. Muss als Breiten- und Längengradkoordinaten angegeben werden:
Places Swift SDK
let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.395804, longitude: -122.077023))
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];
regionCode
Der Regionscode, der zum Formatieren der Antwort verwendet wird, angegeben als zweistelliger Wert der ccTLD („Top-Level-Domain“). Die meisten ccTLD-Codes entsprechen den ISO-3166-1-Codes. Es gibt jedoch einige Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch gesehen für die Entität „Vereinigtes Königreich Großbritannien und Nordirland“).
Wenn Sie einen ungültigen Regionscode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück. Der Parameter kann sich je nach anwendbarem Recht auf die Ergebnisse auswirken.
shouldIncludePureServiceAreaBusinesses
Wenn true, werden im Antwort-Array reine Unternehmen ohne festen Standort zurückgegeben. Ein Unternehmen ohne festen Standort in einem Einzugsgebiet ist ein Unternehmen, das Kunden vor Ort besucht oder direkt beliefert, aber an seiner Geschäftsadresse keine Kunden empfängt.
Beispiel:
Places Swift SDK
let filter = AutocompleteFilter() filter.shouldIncludePureServiceAreaBusinesses = true
Swift
let filter = AutocompleteFilter() filter.shouldIncludePureServiceAreaBusinesses = true
Objective-C
GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init]; filter.shouldIncludePureServiceAreaBusinesses = YES;
Das „Place Autocomplete“-Widget hinzufügen
Wenn Sie die automatische Vervollständigung von Orten einheitlich gestalten möchten, können Sie das Place Autocomplete-Widget in Ihre App einbinden. Das Widget bietet eine spezielle Vollbildoberfläche, die Nutzereingaben verarbeitet und Ortsvorschläge anzeigt, während AutocompletePlaceSuggestion-Objekte an die App zurückgegeben werden. Sie können dann eine Place Details (New)-Anfrage stellen, um zusätzliche Informationen zu den Ortsvorschlägen abzurufen.
Wie beim programmatischen Abrufen von Ortsvorschlägen können Sie auch im Place Autocomplete-Widget Sitzungstokens verwenden, um Autocomplete-Anfragen zu Abrechnungszwecken in Sitzungen zu gruppieren. Sie können ein Sitzungstoken übergeben, indem Sie AutocompleteSessionToken() aufrufen.
Wenn Sie kein Sitzungstoken angeben, erstellt das Widget ein Autocomplete-Sitzungstoken für Sie, das dann über den Callback onSelection abgerufen werden kann. Weitere Informationen zur Verwendung von Sitzungstokens finden Sie unter Sitzungstokens.
Wenn der Bindungswert show auf true festgelegt ist, wird der Nutzer zu einer Vollbildansicht weitergeleitet, in der er einen Ort auswählen kann. Während der Nutzer tippt, gibt das Widget Vorschläge für Orte wie Unternehmen, Adressen und POIs zurück. Wenn der Nutzer einen Ort auswählt, ruft das Widget den onSelection-Handler mit dem ausgewählten Ort auf und schließt die Vollbildansicht.
Parameter für das Place Autocomplete-Widget
Zusätzlich zu den programmatisch verfügbaren Parametern bietet das „Place Autocomplete“-Widget auch die folgenden Parameter.
Einblenden
show gibt an, ob das Widget angezeigt wird.
onSelection
Der Closure, der ausgeführt werden soll, wenn ein Ort ausgewählt wird.
onError
Der Closure, der ausgeführt werden soll, wenn ein Fehler auftritt. Wenn ein Fehler auftritt, wird ein PlacesError übergeben.
Anpassung von Inhalten und Designs
Die Parameter AutocompleteUICustomization geben die Anpassungen der Benutzeroberfläche an, die auf das Widget angewendet werden sollen. Folgende Anpassungsoptionen sind verfügbar:
AutocompleteListDensity: Mit diesem Parameter können Sie die Dichte der Vorschlagsliste auswählen, entwedermultiLineodertwoLine.AutocompleteUIIcon: Mit diesem Parameter können Sie festlegen, ob das Standardsymbol für jedes Listenelement angezeigt werden soll.theme: Mit diesem Parameter wird ein benutzerdefiniertes Design angegeben, das alle Standardstilattribute überschreibt. Sie können die Farben, die Typografie, die Abstände, die Rahmen und die Ecken der Place Autocomplete-Komponente anpassen. Der Standardwert istPlacesMaterialTheme. Für alle Designattribute, die nicht überschrieben werden, werden die Standardstile verwendet.
Vollständiges Codebeispiel ansehen
Beispiele für Autocomplete (New)
„locationRestriction“ und „locationBias“ verwenden
Bei der automatischen Vervollständigung (New) wird standardmäßig die IP-Gewichtung verwendet, um den Suchbereich einzugrenzen. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts, um die Ergebnisse zu gewichten. Sie können optional locationRestriction oder locationBias verwenden, aber nicht beide, um einen Suchbereich anzugeben.
Mit der Standortbeschränkung wird der Suchbereich festgelegt. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Im folgenden Beispiel wird die Anfrage mithilfe einer Standorteinschränkung auf einen kreisförmigen Bereich mit einem Radius von 5.000 Metern um San Francisco beschränkt:
Places Swift SDK
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. }
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. } } }];
Bei der Standortgewichtung dient der Standort als Gewichtung. Das bedeutet, dass Ergebnisse um den angegebenen Standort herum zurückgegeben werden können, einschließlich Ergebnissen außerhalb des angegebenen Bereichs. Im nächsten Beispiel wird die vorherige Anfrage so geändert, dass die Ortsgewichtung verwendet wird:
Places Swift SDK
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. }
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. } } }];
Nutzungsarten
Mit dem Parameter „types“ können Sie die Ergebnisse einer Anfrage auf einen bestimmten Typ beschränken, wie in Tabelle A und Tabelle B aufgeführt. Sie können ein Array mit bis zu fünf Werten angeben. Wenn weggelassen, werden alle Typen zurückgegeben.
Im folgenden Beispiel wird der Abfragestring „Soccer“ angegeben und der Parameter „types“ verwendet, um die Ergebnisse auf Einrichtungen vom Typ "sporting_goods_store" zu beschränken:
Places Swift SDK
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. }
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. } } }];
Ursprung verwenden
Wenn Sie den Parameter origin in die Anfrage aufnehmen und als Breiten- und Längengradkoordinaten angeben, enthält die Antwort der API die Luftlinie vom Start- zum Zielort. Die Antwort gibt die Entfernung als distanceMeters zurück.
In diesem Beispiel wird der Ursprung auf das Zentrum von San Francisco festgelegt:
Places Swift SDK
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. }
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. } } }];
Inhalte und Design anpassen
Swift
let uiCustomization = AutocompleteUICustomization( listDensity: .multiLine, listItemIcon: .noIcon, theme: PlacesMaterialTheme() )
Widget für die automatische Vervollständigung von Orten hinzufügen (vollständiger Code)
Places Swift SDK
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 } ) } } }
Autocomplete (New)-Optimierung
Hier finden Sie Best Practices, damit Sie den Autocomplete-Dienst (New) optimal nutzen können.
Allgemeine Richtlinien:
- Am schnellsten lässt sich eine funktionsfähige Benutzeroberfläche mit dem Widget für die automatische Vervollständigung (neu) der Maps JavaScript API, dem Widget für die automatische Vervollständigung (neu) des Places SDK for Android oder dem Widget für die automatische Vervollständigung (neu) des Places SDK for iOS entwickeln.
- Machen Sie sich zu Beginn mit den wichtigsten Datenfeldern von Autocomplete (New) vertraut.
- Die Felder zur Standortgewichtung und Standortbeschränkung sind optional, können aber erhebliche Auswirkungen auf die Leistung der automatischen Vervollständigung haben.
- Verwenden Sie die Fehlerbehandlung, wenn die API einen Fehler zurückgibt, damit die Anwendung fehlertolerant reagiert.
- Die Anwendung sollte Anfragen weiter verarbeiten und weiter funktionieren, auch wenn keine Auswahl getroffen wird.
Best Practices für die Kostenoptimierung
Einfache Kostenoptimierung
Wenn Sie die Kosten für die Nutzung des Autocomplete (New)-Dienstes optimieren möchten, verwenden Sie Feldmasken in Place Details (New)- und Autocomplete (New)-Widgets, damit nur die erforderlichen Datenfelder für Autocomplete (New) zurückgegeben werden.
Erweiterte Kostenoptimierung
Wenn Sie Autocomplete (New) programmatisch implementieren, erhalten Sie Zugriff auf die Preise für die SKU „Autocomplete Request“ und können Geocoding API-Ergebnisse für den ausgewählten Ort anstelle von Place Details (New)-Ergebnissen anfordern. Wenn Sie die Kosten pro Anfrage mit der Geocoding API kombinieren, ist das kosteneffizienter als die Verwendung von Kosten pro Sitzung (sitzungsbasiert), sofern die beiden folgenden Bedingungen erfüllt werden:
- Wenn Sie nur den Breiten- und Längengrad oder die Adresse des vom Nutzer ausgewählten Orts abrufen möchten, erhalten Sie entsprechende Informationen über die Geocoding API, für die weniger Kosten anfallen als bei einem Place Details (New)-Aufruf.
- Wenn Nutzer eine automatische Vervollständigung bei durchschnittlich maximal 4 entsprechenden Anfragen auswählen, ist der Preis pro Anfrage möglicherweise kosteneffizienter als der Preis pro Sitzung.
| Was in deinem Antrag enthalten sein muss | Durchschnittliche Anzahl der Autocomplete (New)-Anfragen, bevor ein Nutzer einen Vorschlag auswählt | Empfohlene Implementierung |
|---|---|---|
| Place Details, die nicht die Adresse und den Standort betreffen, z. B. den Namen des Ortes, den Unternehmensstatus oder die Öffnungszeiten | Beliebig | Sitzungsbasierte Autocomplete (Neu) mit Place Details (Neu) |
| Nur Adresse und Breiten-/Längengrad des ausgewählten Vorschlags | Vier oder weniger | Anfragebasierte Autocomplete (New) mit der Geocoding API |
| Nur Adresse und Breiten-/Längengrad des ausgewählten Vorschlags | Mehr als vier | Sitzungsbasierte Autocomplete (New) für Anwendungen, die nur Adressen verwenden |
Wenn Sie Autocomplete (New) in Ihrer Anwendung stark nutzen, kann es kostengünstiger sein, anstelle von Place Details (New) die Geocoding API zu verwenden. Die Effizienz der Autovervollständigung (New) jeder Anwendung hängt davon ab, was die Nutzer eingeben, wo die Anwendung verwendet wird und ob die Best Practices zur Leistungsoptimierung implementiert wurden.
Um die durchschnittliche Anzahl der Anfragen für die Tabelle zu ermitteln, analysieren Sie, wie viele Zeichen Nutzer durchschnittlich eingeben, bevor sie in Ihrer Anwendung einen Autocomplete (New)-Vorschlag auswählen.
Sitzungsbasierte Autocomplete-Anfragen (neu) mit Place Details-Anfragen (neu)
Nutzen Sie das sitzungsbasierte Autocomplete (New) mit Place Details (New).
Da Ihre Anwendung Place Details (New) wie den Ortsnamen, den Geschäftsstatus oder die Öffnungszeiten benötigt, sollte Ihre Implementierung von Autocomplete (New) ein Sitzungstoken verwenden (programmatisch oder in die Widgets für JavaScript, Android oder iOS integriert). Die Abrechnung erfolgt pro Sitzung zuzüglich der entsprechenden Places-SKUs, je nachdem, welche Ortsdatenfelder Sie anfordern.1
Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das
JavaScript,
Android
oder iOS
integriert. Das umfasst sowohl Autocomplete (New)-Anfragen als auch die Place Details (New)-Anfrage für die ausgewählte Vervollständigung. Der fields-Parameter muss festgelegt werden, damit nur die erforderlichen Autocomplete (New)-Datenfelder angefordert werden.
Programmatische Implementierung
Verwenden Sie für Autocomplete (New)-Anfragen ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Place Details (New) für die ausgewählte Vervollständigung anfordern:
- Die Orts-ID aus der Autocomplete (New)-Antwort
- Das Sitzungstoken, das in der Autocomplete (New)-Anfrage verwendet wird
- Den
fields-Parameter, mit dem die erforderlichen Datenfelder für Autocomplete (New) angegeben werden
Automatische Vervollständigung (New) pro Anfrage mit der Geocoding API
Implementieren Sie Autocomplete (New) programmatisch ohne Sitzungstokens und rufen Sie die Geocoding API für die ausgewählte Ortsvervollständigung auf.
Über die Geocoding API erhalten Sie Adressen und Breiten-/Längenkoordinaten.
Vier Autocomplete-Anfragen plus ein Geocoding API-Aufruf für die ausgewählte Ortsvervollständigung kosten weniger als eine Sitzung mit Autocomplete (New).1
Wenn Sie die Best Practices zur Leistung beachten, erhalten Ihre Nutzer bereits mit weniger eingegebenen Zeichen passende Vervollständigungen.
Sitzungsbasierte automatische Vervollständigung (neu) für Anwendungen, die nur Adressen verwenden
Nutzen Sie das sitzungsbasierte Autocomplete (New) mit Place Details (New).
Da die durchschnittliche Anzahl der Anfragen, die Sie voraussichtlich stellen, bevor ein Nutzer eine Autocomplete (New)-Vervollständigung auswählt, die Kosten für die Preisgestaltung pro Sitzung übersteigt, sollte Ihre Implementierung von Autocomplete (New) ein Sitzungstoken sowohl für die Autocomplete (New)-Anfragen als auch für die zugehörige Place Details (New)-Anfrage verwenden.
pro Sitzung.
1
Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das
JavaScript,
Android
oder iOS
integriert. Das umfasst sowohl Autocomplete (New)-Anfragen als auch die Place Details (New)-Anfrage für die ausgewählte Vervollständigung. Der fields-Parameter muss festgelegt werden, damit nur die erforderlichen Felder angefordert werden.
Programmatische Implementierung
Verwenden Sie für Autocomplete (New)-Anfragen ein Sitzungstoken.
Binden Sie die folgenden Parameter ein, wenn Sie Place Details (New) für die ausgewählte Vervollständigung anfordern:
- Die Orts-ID aus der Autocomplete (New)-Antwort
- Das Sitzungstoken, das in der Autocomplete (New)-Anfrage verwendet wird
- Den
fields-Parameter, mit dem Felder wie „Adresse“ oder „Geometrie“ angegeben werden
Autocomplete (New)-Anfragen verzögern
Sie können Autocomplete (New)-Anfragen verzögern, bis der Nutzer die ersten 3 oder 4 Zeichen eingegeben hat, damit weniger Anfragen über die Anwendung gestellt werden. Wenn Sie beispielsweise Autocomplete (New)-Anfragen für jedes Zeichen stellen, nachdem der Nutzer das dritte Zeichen eingegeben hat, und der Nutzer sieben Zeichen eingibt und dann eine Vervollständigung auswählt, für die Sie eine Geocoding API-Anfrage stellen, werden die Gesamtkosten für 4 Autocomplete (New)-Anfragen mit Preis pro Anfrage und die Geocoding-Anfrage berechnet.1
Wenn sich durch das Verzögern von Anfragen Ihre durchschnittliche Anzahl programmatischer Anfragen auf unter 4 senken lässt, empfehlen wir, die Anleitung für eine leistungsstarke Autocomplete (New)-Funktion mit Geocoding API-Implementierung zu beachten. Das Verzögern von Anfragen wird vom Nutzer, der evtl. bei jedem eingegebenen Zeichen mit Vorschlägen rechnet, möglicherweise als Latenz wahrgenommen.
Wenn Sie die Best Practices zur Leistung beachten, erhalten Ihre Nutzer bereits mit weniger eingegebenen Zeichen passende Vervollständigungen.
-
Informationen zu den Kosten finden Sie in den Preislisten für die Google Maps Platform.
Best Practices für die Leistung
Im Folgenden finden Sie Tipps zum Optimieren der Autocomplete (New)-Leistung:
- Binden Sie in Ihre Autocomplete (New)-Implementierung länderspezifische Einschränkungen, eine Standortgewichtung und (bei programmatischen Implementierungen) eine Spracheinstellung ein. Die Spracheinstellung ist bei Widgets nicht erforderlich, weil bei ihnen die Spracheinstellungen aus dem Browser oder vom Mobilgerät des Nutzers übernommen werden.
- Wenn Autocomplete (New) mit einer Karte kombiniert wird, können Sie den Standort anhand des Darstellungsbereichs der Karte gewichten.
- Wenn ein Nutzer keinen der Vorschläge der automatischen Vervollständigung (New) auswählt, was in der Regel geschieht, wenn es sich bei keinem Vorschlag um die gewünschte Adresse handelt, können Sie anhand der ursprünglichen Nutzereingabe versuchen, relevantere Ergebnisse zu erhalten:
- Wenn der Nutzer voraussichtlich nur Adressinformationen eingibt, können Sie die ursprüngliche Nutzereingabe bei einem Aufruf der Geocoding API noch einmal verwenden.
- Wenn Sie davon ausgehen, dass der Nutzer Abfragen für einen bestimmten Ort mithilfe von Name oder Adresse eingibt, verwenden Sie eine „Place Details (New)“-Anfrage. Wenn nur in einer bestimmten Region Ergebnisse erwartet werden, nutzen Sie die Standortgewichtung.
- Nutzer, die Adressen von Untereinheiten eingeben, z. B. Adressen für bestimmte Einheiten oder Wohnungen in einem Gebäude. So wird bei der tschechischen Adresse „Stroupežnického 3191/17, Praha“ z. B. eine teilweise Vervollständigung in Autocomplete (New) ausgegeben.
- Wenn Nutzer Adressen mit Präfixen für Straßenabschnitte eingeben, z. B. „23-30 29th St, Queens“ in New York City oder „47-380 Kamehameha Hwy, Kaneohe“ auf der Insel Kauai in Hawaii
Standortgewichtung
Wenn Sie die Parameter location und radius weitergeben, können Sie die Ergebnisse zugunsten eines festgelegten Bereichs gewichten. Dadurch werden von Autocomplete (New) vorzugsweise Ergebnisse für Orte angezeigt, die sich innerhalb des definierten Bereichs befinden. Ergebnisse außerhalb dieses Bereichs können aber trotzdem angezeigt werden. Mit dem Parameter includedRegionCodes können Sie die Ergebnisse so filtern, dass nur Orte in einem bestimmten Land angezeigt werden.
Standorteinschränkung
Sie können die Ergebnisse auf einen bestimmten Bereich beschränken, indem Sie den Parameter locationRestriction übergeben.
Sie können die Ergebnisse auch auf die Region beschränken, die durch die Parameter location und radius definiert ist, indem Sie den Parameter locationRestriction hinzufügen. Dadurch wird Autocomplete (New) angewiesen, nur Ergebnisse innerhalb dieser Region zurückzugeben.