Place Autocomplete (neu)

Plattform auswählen: Android iOS JavaScript Webdienst

Der Dienst „Autocomplete (New)“ ist eine iOS API, mit der als Antwort auf eine Anfrage Ortsvorschläge zurückgegeben werden. Geben Sie in der Anfrage einen Textsuchstring und geografische Grenzen an, die den Suchbereich steuern.

Der Dienst „Autocomplete (New)“ kann vollständige Wörter und Teilstrings der Eingabe abgleichen und Ortsnamen, Adressen und Plus Codes auflösen. Anwendungen können Abfragen senden, während der Nutzer tippt, um spontan Ortsvorschläge bereitzustellen.

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 die Teileingabe des Nutzers "Sicilian piz" enthält, wobei der Suchbereich auf San Francisco beschränkt ist. Die Antwort enthält dann eine Liste von Ortsvorschlägen, die mit dem Suchstring und dem Suchbereich übereinstimmen, z. B. das Restaurant mit dem Namen „Sicilian Pizza Kitchen“, sowie Details zum Ort.

Die zurückgegebenen Ortsvorschläge sollen dem Nutzer angezeigt werden, damit er den gewünschten Ort auswählen kann. Mit einer Place Details (New)-Anfrage können Sie weitere Informationen zu den zurückgegebenen Orten erhalten.

Hinweis :Sie müssen die ursprüngliche API für die automatische Vervollständigung aktivieren, um die Widgetfunktion nutzen zu können. Die ursprüngliche und die neue API können gleichzeitig aktiviert werden. Weitere Informationen finden Sie im Migrationsleitfaden für „Places Autocomplete (New)“.

Autocomplete (New)-Anfragen

Erstellen Sie eine Anfrage zur automatischen Vervollständigung. Rufen Sie dazu eine Methode für den GMSPlaceClient auf. Sie können Parameter im Objekt GMSAutocompleteRequest übergeben. Die Antwort liefert Autocomplete-Vorschläge innerhalb eines GMSAutocompletePlaceSuggestion-Objekts.

Der API-Schlüssel und die Parameter query sind erforderlich. Sie können auch GMSAutocompleteSessionToken einfügen, um Anfragen mit einer Abrechnungssitzung zu verknüpfen, und GMSAutocompleteFilter, um auf die Ergebnisse anzuwenden.

Weitere Informationen zu erforderlichen und optionalen Parametern finden Sie im Abschnitt zu den Parametern in diesem Dokument.

Swift

let token = GMSAutocompleteSessionToken()

let northEastBounds = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWestBounds = CLLocationCoordinate2DMake(37.395804, -122.077023)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northEastBounds, southWestBounds)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

Objective-C

CLLocationCoordinate2D northEast = CLLocationCoordinate2DMake(37.388162, -122.088137);
CLLocationCoordinate2D southWest = CLLocationCoordinate2DMake(37.395804, -122.077023);

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ kGMSPlaceTypeRestaurant ];
filter.locationBias = GMSPlaceRectangularLocationOption(northEast, southWest);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let center = (37.3913916, -122.0879074)
let northEast = (37.388162, -122.088137)
let southWest = (37.395804, -122.077023)

let bias = RectangularCoordinateRegion(northEast: northEast, southWest: southWest)
let filter = AutocompleteFilter(types: [ .restaurant ], origin: center, coordinateRegionBias: bias)

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  // Handle suggestions.
case .failure(let placesError):
  // Handle error.
}

Autocomplete (New) – Antworten

Die automatische Vervollständigung gibt ein Array von bis zu fünf GMSAutocompleteSuggestion-Instanzen zurück. Das Array enthält:

• placeID
• types: Für diesen Ort geltende Typen.
• distanceMeters: Entfernung vom Startort.
• attributedFullText: Vollständiger visuell lesbarer Text eines Vorschlags.
• attributedPrimaryText: Klar lesbarer Primärtext eines Vorschlags
• attributedSecondaryText: menschenlesbarer Sekundärtext eines Vorschlags.
• structuredFormat: Der spezifische Name und der eindeutige Text, z. B. die Stadt oder Region.

Erforderliche Parameter

Abfrage

Die Textzeichenfolge, nach der gesucht werden soll. Geben Sie vollständige Wörter und Teilstrings, Ortsnamen, Adressen und Plus Codes an. Der Dienst „Autocomplete (New)“ gibt mögliche Übereinstimmungen basierend auf diesem String zurück und ordnet die Ergebnisse nach erkannter Relevanz.

Optionale Parameter

types

Einem Ort kann nur ein einziger primärer Typ des Typs Tabelle A oder Tabelle B zugeordnet werden. Der primäre Typ kann beispielsweise mexican_restaurant oder steak_house sein.

Standardmäßig gibt die API alle Orte basierend auf dem Parameter input zurück, unabhängig vom Wert des primären Typs, der dem Ort zugeordnet ist. Schränken Sie die Ergebnisse auf einen bestimmten primären Typ oder einen bestimmten primären Typ ein, 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 Werte des primären Typs übereinstimmen, um in die Antwort aufgenommen zu werden.

In folgenden Fällen wird die Anfrage mit dem Fehler INVALID_REQUEST abgelehnt:

• Es sind mehr als fünf Typen angegeben.
• Alle nicht erkannten Typen wurden angegeben.

Länder

Schließt nur Ergebnisse aus der Liste der angegebenen Regionen ein, angegeben als Array mit bis zu 15 zweistelligen ccTLD-Werten ("top-level domain"). Wenn keine Angabe gemacht wird, werden keine Einschränkungen auf die Antwort angewendet. So beschränken Sie die Regionen beispielsweise auf Deutschland und Frankreich:

Swift

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

Objective-C

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

GooglePlacesSwift

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

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 Vorhersagen zurückgegeben werden. Wenn es leer ist, wird standardmäßig die Länge von input verwendet.

„locationBias“ oder „locationRestriction“

Sie können locationBias oder locationRestriction angeben, aber nicht beides, um den Suchbereich zu definieren. Stellen Sie sich locationRestriction vor, um die Region anzugeben, in der sich die Ergebnisse befinden müssen, und locationBias die Region, in der sich die Ergebnisse in der Nähe befinden müssen, aber auch außerhalb des Bereichs.

Hinweis: Wenn Sie sowohl locationBias als auch locationRestriction weglassen, verwendet die API standardmäßig die Quellengewichtung nach IP-Adresse. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts zur Gewichtung der Ergebnisse.

• locationBias gibt das Gebiet an, in dem gesucht werden soll. Dieser Standort dient als Verzerrung. Das bedeutet, dass Ergebnisse in der Nähe des angegebenen Standorts zurückgegeben werden können, auch Ergebnisse außerhalb des angegebenen Bereichs.

• locationRestriction gibt das Gebiet an, in dem gesucht werden soll. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben.

Geben Sie den Bereich 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 (einschließlich) liegen. Der Standardwert ist 0,0. Für locationRestriction müssen Sie den Radius auf einen Wert größer als 0, 0 festlegen. Andernfalls gibt die Anfrage keine Ergebnisse zurück.

Beispiel:

Swift

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

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

Objective-C

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

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

GooglePlacesSwift

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)      
  

Ein Rechteck ist ein Darstellungsbereich mit Breiten- und Längengrad, der als zwei diagonal gegenüberliegende low- und high-Punkte dargestellt wird. Ein Darstellungsbereich gilt als geschlossener Bereich, d. h. er umfasst seine Begrenzung. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen, die Längengradgrenzen zwischen -180 und 180 Grad (einschließlich):

• Wenn low = high, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
• Wenn low.longitude > high.longitude ist, wird der Längengradbereich umgekehrt (der Darstellungsbereich kreuzt die 180-Grad-Längenlinie).
• Wenn low.longitude = -180 Grad und high.longitude= 180 Grad ist, enthält der Darstellungsbereich alle Längengrade.
• Wenn low.longitude = 180 Grad und high.longitude = -180 Grad ist, ist der Längengradbereich leer.

Sowohl low als auch high müssen ausgefüllt werden und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

Dieser Darstellungsbereich schließt beispielsweise New York City vollständig ein:

Swift

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

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

Objective-C

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

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

GooglePlacesSwift

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

Ursprung

Der Startpunkt, von dem aus die direkte Entfernung zum Ziel berechnet werden soll (wird als distanceMeters zurückgegeben). Wenn dieser Wert weggelassen wird, wird keine Geradenentfernung zurückgegeben. Muss als Breiten- und Längengrad angegeben werden:

Swift

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

Objective-C

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

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

GooglePlacesSwift

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

regionCode

Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger ccTLD-Wert ("top-level domain"). Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes, mit einigen Ausnahmen. So lautet beispielsweise der ccTLD-Code des Vereinigten Königreichs „uk“ (.co.uk) und der ISO 3166-1-Code „gb“ (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Northern Ireland“).

Wenn Sie einen ungültigen Regionscode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück. Der Parameter kann sich gemäß geltendem Recht auf Ergebnisse auswirken.

sessionToken

Sitzungstokens sind vom Nutzer erstellte Strings, die Aufrufe der automatischen Vervollständigung (New) als "Sitzungen" erfassen. „Autocomplete (New)“ verwendet Sitzungstokens, um die Abfrage- und Auswahlphasen einer Nutzersuche mit automatischer Vervollständigung zu Abrechnungszwecken in einer separaten Sitzung zu gruppieren. Weitere Informationen finden Sie unter Sitzungstokens.

Beispiele für Autocomplete (New)

„locationRestriction“ und „locationBias“ verwenden

Bei „Autocomplete (New)“ wird standardmäßig die Gewichtung nach IP-Adresse verwendet, um den Suchbereich zu steuern. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts zur Gewichtung der Ergebnisse. Sie können optional locationRestriction oder locationBias verwenden, aber nicht beides, um einen zu durchsuchenden Bereich anzugeben.

Durch die Standortbeschränkung wird das zu durchsuchende Gebiet angegeben. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Im folgenden Beispiel wird die Standortbeschränkung verwendet, um die Anfrage auf eine zirkuläre Standortbeschränkung mit einem Radius von 5.000 m um San Francisco zu beschränken:

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:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
  })

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let center = (37.775061, -122.419400)
let radius = 5000.0
let restriction = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionRestriction: restriction)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Bei der Standortgewichtung dient der Standort als Verzerrung, d. h., Ergebnisse um den angegebenen Ort herum können zurückgegeben werden, auch solche außerhalb des angegebenen Bereichs. Im nächsten Beispiel wird die Standortgewichtung für die vorherige Anfrage geändert:

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:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

Objective-C

CLLocationCoordinate2D center = CLLocationCoordinate2DMake(37.775061, -122.419400);
radius = 5000.0;

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.locationBias = GMSPlaceCircularLocationOption(center, radius);
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Sicilian piz"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

let center = (37.775061, -122.419400)
let radius = 5000.0
let bias = CircularCoordinateRegion(center: center, radius: radius)
let filter = AutocompleteFilter(coordinateRegionBias: bias)
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Sicilian piz", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

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. Bei Auslassung werden alle Typen zurückgegeben.

Im folgenden Beispiel wird der Abfragestring „Soccer“ angegeben und der Parameter „types“ verwendet, um die Ergebnisse auf Einrichtungen des Typs "sporting_goods_store" zu beschränken:

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
  // Handle response
})

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.types = @[ "sporting_goods_store" ];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Soccer"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
    }
  }
}];

GooglePlacesSwift

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

let autocompleteRequest = AutocompleteRequest(query: "Soccer", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
    

Ursprung verwenden

Wenn Sie den Parameter origin in Form von Breiten- und Längengradkoordinaten in die Anfrage aufnehmen, schließt die API in der Antwort die Entfernung zwischen Start und Ziel auf. In der Antwort wird die Entfernung als distanceMeters zurückgegeben.

In diesem Beispiel wird als Startpunkt das Zentrum von San Francisco festgelegt:

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
  // Handle response
})

Objective-C

GMSAutocompleteFilter *filter = [[GMSAutocompleteFilter alloc] init];
filter.origin = [[CLLocation alloc] initWithLatitude:37.395804 longitude:-122.077023];
GMSAutocompleteRequest *request = [[GMSAutocompleteRequest alloc] initWithQuery:@"Amoeba"];
request.sessionToken = token;
request.filter = filter;

[[GMSPlacesClient sharedClient] fetchAutocompleteSuggestionsFromRequest:request callback:^(NSArray<GMSAutocompleteSuggestion *> * results, NSError * error){
  // Handle response
  for (GMSAutocompleteSuggestion *suggestion in results) {
    if (suggestion.placeSuggestion) {
      // Show place suggestion data.
      }
    }
}];

GooglePlacesSwift

let filter = AutocompleteFilter(origin: CLLocation(latitude: 37.7749, longitude: -122.4194))
let token = AutocompleteSessionToken()

let autocompleteRequest = AutocompleteRequest(query: "Amoeba", sessionToken: token, filter: filter)
switch await placesClient.fetchAutocompleteSuggestions(with: autocompleteRequest) {
case .success(let autocompleteSuggestions):
  for suggestion in autocompleteSuggestions {
    switch suggestion {
    case .place:
      // Show place suggestion data.
    }
  }
case .failure(let placesError):
  // Handle error.
}
  

Attribution

Sie können „Autocomplete (New)“ auch ohne Karte verwenden. Falls Sie eine Karte anzeigen, muss es eine Google-Karte sein. Wenn Sie Vorschläge aus dem Dienst „Autocomplete (New)“ ohne Karte anzeigen, müssen Sie das Google-Logo direkt in das Suchfeld bzw. die Suchergebnisse einfügen. Weitere Informationen findest du unter Google-Logo und Quellenangaben anzeigen.