Autouzupełnianie miejsc (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Usługa Autouzupełnianie (nowa) to interfejs API na iOS, który zwraca sugestie miejsc w odpowiedzi na żądanie. W żądaniu podaj tekstowy ciąg wyszukiwania i granice geograficzne określające obszar wyszukiwania.

Usługa Autouzupełnianie (nowa) może dopasowywać pełne słowa i podciągi znaków w danych wejściowych, rozwiązując nazwy miejsc, adresy i kody. Aplikacje mogą więc wysyłać zapytania w imieniu użytkownika, aby wyświetlać sugestie miejsc na bieżąco.

Propozycje miejsc to miejsca, takie jak firmy, adresy i miejsca docelowe, które są wyświetlane na podstawie określonego ciągu tekstowego i obszaru wyszukiwania.

Na przykład wywołujesz interfejs API, podając jako dane wejściowe ciąg znaków zawierający częściowe dane wejściowe użytkownika „Spagh”, z ograniczeniem obszaru wyszukiwania do Nowego Jorku. Odpowiedź zawiera listę sugestii miejsc pasujących do ciągu znaków i obszaru wyszukiwania, np. restaurację o nazwie „Cafe Spaghetti”, wraz ze szczegółami dotyczącymi tego miejsca.

Zwrócone sugestie dotyczące miejsc są przeznaczone do wyświetlania użytkownikowi, aby mógł wybrać odpowiednie miejsce. Aby uzyskać więcej informacji o dowolnej z zwróconych sugestii miejsc, możesz wysłać żądanie Szczegóły miejsca (nowe).

żądania autouzupełniania (nowe);

Utwórz żądanie autouzupełniania, wywołując metodę w GMSPlaceClient. Parametry możesz przekazywać w obiekcie GMSAutocompleteRequest. Odpowiedź zawiera sugestie autouzupełniania w obiekcie GMSAutocompletePlaceSuggestion.

Wymagane są klucz interfejsu API i parametry query. Możesz też użyć parametru GMSAutocompleteSessionToken, aby powiązać żądania z sesją płatności, oraz parametru GMSAutocompleteFilter, aby zastosować je do wyników.

Więcej informacji o wymaganych i opcjonalnych parametrach znajdziesz w sekcji dotyczącej parametrów tego dokumentu.

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

Places Swift SDK na iOS (wersja podglądowa)

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

Odpowiedzi na „Autouzupełnianie” (nowe)

Autouzupełnianie zwraca tablicę zawierającą maksymalnie 5 wartości GMSAutocompleteSuggestion. Tablica zawiera:

  • placeID
  • types: typy, które dotyczą tego miejsca.
  • distanceMeters: odległość od punktu początkowego.
  • attributedFullText: pełny tekst sugestii w postaci czytelnej dla człowieka.
  • attributedPrimaryText: tekst główny sugestii w formie czytelnej dla człowieka treści.
  • attributedSecondaryText: tekst dodatkowy sugestii w formie czytelnej dla człowieka treści.
  • structuredFormat: nazwa i tekst jednoznacznie identyfikujący, np. miasto lub region.

Wymagane parametry

zapytanie

Tekst, w którym ma być przeprowadzone wyszukiwanie. Określ pełne słowa i podciągi znaków, nazwy miejsc, adresy i kody Plus Code. Usługa Autocomplete (New) zwraca dopasowania na podstawie tego ciągu znaków i porządkuje wyniki według ich trafności.

Parametry opcjonalne

typy

Miejsce może mieć tylko jeden podstawowy typ z typów Tabela A lub Tabela B powiązanych z nim. Na przykład typem podstawowym może być mexican_restaurant lub steak_house.

Domyślnie interfejs API zwraca wszystkie miejsca na podstawie parametru input, niezależnie od wartości głównego typu powiązanego z miejscem. Ogranicz wyniki do określonego typu głównego lub typów głównych, przekazując parametr types.

Użyj tego parametru, aby określić maksymalnie 5 wartości typu z tabeli A lub B. Aby miejsce zostało uwzględnione w odpowiedzi, musi ono odpowiadać jednej z podanych wartości typu podstawowego.

Prośba zostanie odrzucona z błędem INVALID_REQUEST, jeśli:

  • Podano więcej niż 5 typów.
  • Wszelkie nierozpoznane typy są określane.

kraje

Uwzględniaj tylko wyniki z listy podanych regionów, podanych jako tablica maksymalnie 15 2-znakowych wartości ccTLD („domeny najwyższego poziomu”). Jeśli nie zostanie podany, nie zostaną zastosowane żadne ograniczenia odpowiedzi. Aby na przykład ograniczyć regiony do Niemiec i Francji:

Swift

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

Objective-C

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

Places Swift SDK na iOS (wersja podglądowa)

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

Jeśli określisz zarówno parametr locationRestriction, jak i countries, wyniki będą znajdować się w obszarze przecięcia tych 2 ustawień.

inputOffset

Odsunięcie znaku Unicode liczone od 0, wskazujące pozycję kursora w pozycji input. Pozycja kursora może wpływać na prognozy zwracane przez model. Jeśli jest pusty, przyjmuje domyślnie długość input.

locationBias lub locationRestriction

Aby zdefiniować obszar wyszukiwania, możesz podać kolumnę locationBias lub locationRestriction (ale nie obie). Pamiętaj, że locationRestriction określa region, w którym muszą się znajdować wyniki, a locationBias – region, w którym wyniki muszą się znajdować, ale mogą być poza tym obszarem.

  • locationBias określa obszar wyszukiwania. Ta lokalizacja służy jako preferencja, co oznacza, że mogą być zwracane wyniki z okolic wskazanej lokalizacji, w tym poza wskazanym obszarem.

  • locationRestriction określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane.

Określ region locationBias lub locationRestriction jako prostokątny podgląd lub koło.

Okrąg jest definiowany przez punkt środkowy i promień w metrach. Promień musi się mieścić w przedziale od 0,0 do 50 000,0 (włącznie). Wartością domyślną jest 0,0. W przypadku locationRestriction promień musi być ustawiony na wartość większą niż 0, 0. W przeciwnym razie żądanie nie zwraca żadnych wyników.

Na przykład:

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

Places Swift SDK na iOS (wersja podglądowa)

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)

Prostokąt to widoczny obszar na podstawie współrzędnych geograficznych, reprezentowany przez 2 punkty low i high znajdujące się naprzeciw siebie. Widoczny obszar jest uważany za zamknięty region, co oznacza, że obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w przedziale od -90 do 90 stopni, a granice długości geograficznej – w przedziale od -180 do 180 stopni:

  • Jeśli low = high, widoczny obszar składa się z tego pojedynczego punktu.
  • Jeśli low.longitude > high.longitude, zakres długości geograficznej jest odwrócony (widok przetnie linię długości geograficznej 180°).
  • Jeśli low.longitude = -180 stopni, a high.longitude= 180 stopni, widok obejmuje wszystkie długości geograficzne.
  • Jeśli low.longitude = 180 stopni, a high.longitude = –180 stopni, zakres długości geograficznej jest pusty.

Wartości low i high muszą być wypełnione, a reprezentowane pole nie może być puste. Pusta wizjer prowadzi do błędu.

Na przykład ten widok zawiera w pełni Nowy Jork:

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

Places Swift SDK na iOS (wersja podglądowa)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)

pochodzenie

Punkt początkowy, z którego ma być obliczana odległość w linii prostej do punktu docelowego (zwracana jako distanceMeters). Jeśli ta wartość zostanie pominięta, odległość w linii prostej nie zostanie zwrócona. Musi być podany jako współrzędne szerokości i długości geograficznej:

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

Places Swift SDK na iOS (wersja podglądowa)

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

regionCode

Kod regionu użyty do sformatowania odpowiedzi, podany jako kod domeny krajowej najwyższego poziomu („domena najwyższego poziomu”) o dwóch znakach. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma wyjątkami. Na przykład ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”).

Jeśli podasz nieprawidłowy kod regionu, interfejs API zwróci błąd INVALID_ARGUMENT. Parametr może wpływać na wyniki w zależności od obowiązujących przepisów.

sessionToken

Tokeny sesji to tworzone przez użytkownika ciągi znaków, które śledzą wywołania funkcji Autouzupełnianie (nowa) jako „sesje”. Autouzupełnianie (nowa wersja) używa tokenów sesji, aby grupować fazy zapytania i wyboru w autouzupełnianiu w ramach jednej sesji na potrzeby rozliczeń. Więcej informacji znajdziesz w artykule Tokeny sesji.

Przykłady autouzupełniania (nowa wersja)

Używanie parametrów locationRestriction i locationBias

Autouzupełnianie (nowa wersja) domyślnie używa ukierunkowania adresu IP do kontrolowania obszaru wyszukiwania. W przypadku ukierunkowania na adres IP interfejs API używa adresu IP urządzenia, aby ukierunkować wyniki. Aby określić obszar wyszukiwania, możesz opcjonalnie użyć właściwości locationRestriction lub locationBias (ale nie obu jednocześnie).

Ograniczenie dotyczące lokalizacji określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W tym przykładzie użyliśmy ograniczenia dotyczącego lokalizacji, aby ograniczyć żądanie do koła o promieniu 5000 metrów z San Francisco jako środkiem:

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

Places Swift SDK na iOS (wersja podglądowa)

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

W przypadku ustawienia „preferencje dotyczące lokalizacji” lokalizacja służy jako preferencja, co oznacza, że wyniki mogą być zwracane w pobliżu określonej lokalizacji, w tym poza określony obszar. W następnym przykładzie zmieniamy poprzednie zapytanie, aby wykorzystać uczenie z uwzględnieniem lokalizacji:

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

Places Swift SDK na iOS (wersja podglądowa)

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

Typy użycia

Użyj parametru types, aby ograniczyć wyniki żądania do określonego typu, jak podano w tabeli A i tabeli B. Możesz podać tablicę zawierającą maksymalnie 5 wartości. Jeśli nie zostanie podany, zwrócone zostaną wszystkie typy.

W tym przykładzie łańcuch zapytania to „Soccer”, a parametry types służy do ograniczenia wyników do obiektów typu "sporting_goods_store":

Swift

let token = GMSAutocompleteSessionToken()

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
    
let request = GMSAutocompleteRequest(query:"Soccer")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText))")
        }
      }
    })

Objective-C

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

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

Places Swift SDK na iOS (wersja podglądowa)

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

Użyj punktu początkowego

Jeśli w żądaniu uwzględnisz parametr origin podany jako współrzędne szerokości i długości geograficznej, interfejs API uwzględni w odpowiedzi odległość w linii prostej od punktu początkowego do docelowego. Odpowiedź zwraca odległość jako distanceMeters.

W tym przykładzie punkt początkowy znajduje się w centrum San Francisco:

Swift

let token = GMSAutocompleteSessionToken()

let origin = CLLocation(latitude: 37.7749, longitude: -122.4194)

let filter = GMSAutocompleteFilter()

filter.origin =  origin
    
let request = GMSAutocompleteRequest(query:"Amoeba")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      if let error = error {
        print("Autocomplete error: \(error)")
        return
      }
      if let autocompleteResults = results {
        for result in autocompleteResults {
          print("Result \(String(describing: result.placeSuggestion?.placeID)) with \(String(describing: result.placeSuggestion?.attributedFullText)) and distance: \(String(describing: result.placeSuggestion?.distanceMeters))")
        }
      }
    })

Objective-C

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

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

Places Swift SDK na iOS (wersja podglądowa)

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

Atrybucje

Możesz używać funkcji Autouzupełnianie (nowa) nawet bez mapy. Jeśli chcesz wyświetlić mapę, musi to być mapa Google. Jeśli wyświetlasz sugestie z usługi Autocomplete (New) bez mapy, musisz uwzględnić logo Google wyświetlane w polu wyszukiwania lub w wynikach. Więcej informacji znajdziesz w artykule Wyświetlanie logo i przypisów Google.