Autouzupełnianie miejsc (nowość)

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

Usługa Autouzupełnianie (nowa) może dopasowywać pełne słowa i podłańcuchy danych wejściowych, rozpoznając nazwy miejsc, adresy i plus kody. Dzięki temu aplikacje mogą wysyłać zapytania podczas wpisywania tekstu przez użytkownika, aby na bieżąco wyświetlać sugestie miejsc.

Sugestie miejsc to miejsca, takie jak firmy, adresy i ciekawe miejsca, na podstawie określonego ciągu tekstowego i obszaru wyszukiwania.

Załóżmy na przykład, że wywołujesz interfejs API, używając jako danych wejściowych ciągu znaków, który zawiera częściowe dane wejściowe użytkownika „Spagh”, a obszar wyszukiwania jest ograniczony do Nowego Jorku. Odpowiedź zawiera listę sugerowanych miejsc, które pasują do wyszukiwanego ciągu znaków i obszaru wyszukiwania, np. restaurację o nazwie „Cafe Spaghetti”, wraz ze szczegółowymi informacjami o tym miejscu.

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

Funkcję autouzupełniania (nową) możesz zintegrować z aplikacją na 2 główne sposoby:

• Uzyskiwanie podpowiedzi miejsc automatycznie: wywołaj interfejs API bezpośrednio, aby pobrać podpowiedzi i wyświetlić je w niestandardowym interfejsie użytkownika.
• Dodaj widżet autouzupełniania miejsc: udostępnia gotową do użycia funkcję autouzupełniania wyszukiwania, która wyświetla podpowiedzi podczas wpisywania tekstu przez użytkownika.

Automatyczne uzyskiwanie podpowiedzi dotyczących miejsc

Żądania autouzupełniania (nowe)

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

Klucz interfejsu API i parametry query są wymagane. Możesz też dodać parametr GMSAutocompleteSessionToken, aby powiązać żądania z sesją rozliczeniową, oraz parametr GMSAutocompleteFilter, aby zastosować go do wyników.

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

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

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

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

let token = GMSAutocompleteSessionToken()

let northWestBounds = CLLocationCoordinate2DMake(40.921628, -73.700051)
let southEastBounds = CLLocationCoordinate2DMake(40.477398, -74.259087)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northWestBounds, southEastBounds)

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

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

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

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

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

Odpowiedzi autouzupełniania (nowe)

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

• placeID
• types: typy, które mają zastosowanie do tego miejsca.
• distanceMeters: odległość od punktu początkowego.
• attributedFullText: pełny tekst sugestii zrozumiały dla człowieka.
• attributedPrimaryText: zrozumiały dla człowieka tekst główny sugestii.
• attributedSecondaryText: zrozumiały dla człowieka tekst dodatkowy sugestii.
• structuredFormat: konkretna nazwa i tekst uściślający, np. miasto lub region.

Wymagane parametry

zapytanie

Ciąg tekstowy, który ma zostać wyszukany. Podaj pełne słowa i podłańcuchy, nazwy miejsc, adresy i plus codes. Usługa Autouzupełnianie (nowa) zwraca potencjalne dopasowania na podstawie tego ciągu znaków i porządkuje wyniki według ich trafności.

Parametry opcjonalne

sessionToken

Tokeny sesji to ciągi znaków generowane przez użytkownika, które śledzą wywołania Autouzupełniania (nowego) – zarówno wywołania wykonywane przez widżet, jak i wywołania automatyczne – jako „sesje”. Autouzupełnianie (nowe) używa tokenów sesji do grupowania faz zapytania i wyboru wyszukiwania z autouzupełnianiem przez użytkownika w osobną sesję na potrzeby rozliczeń.

Możesz ujawnić token sesji autouzupełniania miejsc, aby przekazać go innym usługom, które nie są częścią pakietu Places SDK na iOS, np. weryfikacji adresów:

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

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

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

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

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

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

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

Więcej informacji znajdziesz w sekcji Tokeny sesji.

Opcjonalne parametry AutocompleteFilter

typy

Miejsce może mieć tylko 1 główny typ z typów wymienionych w tabeli A lub tabeli B. Na przykład typem głównym może być mexican_restaurant lub steak_house.

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

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

Żądanie zostanie odrzucone z błędem INVALID_REQUEST, jeśli:

• Podano więcej niż 5 typów.
• określono nierozpoznane typy;

Aby na przykład ograniczyć wyniki do sklepów ze sprzętem sportowym, określ ten typ w parametrze AutocompleteFilter:

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

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

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

kraje

Uwzględniaj tylko wyniki z listy określonych regionów, podanych jako tablica zawierająca maksymalnie 15 dwuznakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli go pominiesz, do odpowiedzi nie zostaną zastosowane żadne ograniczenia. Aby na przykład ograniczyć regiony do Francji i Niemiec:

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

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

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

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

inputOffset

Przesunięcie znaku Unicode liczone od 0, które wskazuje pozycję kursora w input. Pozycja kursora może wpływać na zwracane podpowiedzi. Jeśli pole jest puste, domyślnie używana jest długość input.

locationBias lub locationRestriction

Aby określić obszar wyszukiwania, możesz podać locationBias lub locationRestriction, ale nie obie te wartości. Parametr locationRestriction określa region, w którym muszą znajdować się wyniki, a parametr locationBias określa region, w pobliżu którego muszą znajdować się wyniki, ale mogą być poza tym obszarem.

• locationBias określa obszar wyszukiwania. Ta lokalizacja służy jako punkt odniesienia, co oznacza, że mogą być zwracane wyniki z określonej lokalizacji, w tym wyniki spoza określonego obszaru.

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

Określ region locationBias lub locationRestriction jako prostokątny obszar widoczny lub okrąg.

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

Na przykład:

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

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

filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

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

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

Prostokąt to widoczny obszar szerokości i długości geograficznej, reprezentowany przez 2 punkty low i high po przekątnej. Widoczny obszar jest uważany za zamknięty, co oznacza, że obejmuje on swoje granice. Szerokość geograficzna musi mieścić się w zakresie od -90 do 90 stopni, a długość geograficzna – 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 (obszar widoczny na ekranie przekracza linię długości geograficznej 180 stopni).
• Jeśli low.longitude = –180 stopni, a high.longitude= 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne.
• Jeśli low.longitude = 180 stopni, a high.longitude = –180 stopni, zakres długości geograficznej jest pusty.

Należy wypełnić zarówno pole low, jak i high, a reprezentowane pole nie może być puste. Pusty widoczny obszar powoduje błąd.

Na przykład ten widoczny obszar obejmuje cały Nowy Jork:

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)
  

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

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

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

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

pochodzenie

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

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

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

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

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

regionCode

Kod regionu używany do formatowania odpowiedzi, określony jako 2-znakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a 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 na podstawie obowiązujących przepisów.

shouldIncludePureServiceAreaBusinesses

Jeśli ma wartość true, zwraca w tablicy odpowiedzi firmy działające wyłącznie na określonym obszarze. Firma działająca wyłącznie na określonym obszarze to firma, która świadczy usługi na miejscu u klienta lub samodzielnie dostarcza produkty odbiorcom, ale nie obsługuje klientów pod swoim adresem.

Na przykład:

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

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

Dodawanie widżetu autouzupełniania miejsc

Aby łatwiej zapewnić spójne działanie Autouzupełniania miejsc, możesz dodać do aplikacji widżet Autouzupełniania miejsc. Widżet udostępnia dedykowany interfejs pełnoekranowy, który obsługuje dane wejściowe użytkownika i wyświetla mu prognozy miejsc, zwracając do aplikacji obiekty AutocompletePlaceSuggestion. Następnie możesz wysłać żądanie informacji o miejscu (nowe), aby uzyskać dodatkowe informacje o prognozach miejsc.

Podobnie jak w przypadku pobierania prognoz miejsc za pomocą kodu, widżet autouzupełniania miejsc umożliwia używanie tokenów sesji do grupowania żądań autouzupełniania w sesje na potrzeby rozliczeń. Token sesji możesz przekazać, wywołując funkcję AutocompleteSessionToken().

Jeśli nie podasz tokena sesji, widżet utworzy token sesji autouzupełniania, który można uzyskać z wywołania zwrotnego onSelection. Więcej informacji o używaniu tokenów sesji znajdziesz w artykule Informacje o tokenach sesji.

Gdy wartość powiązania show jest ustawiona na true, użytkownik zostanie przekierowany do widoku pełnego ekranu, w którym może wybrać miejsce. Gdy użytkownik wpisuje tekst, widżet zwraca sugestie miejsc, takich jak firmy, adresy i ciekawe miejsca. Gdy użytkownik wybierze miejsce, widżet wywołuje moduł obsługi onSelection z wybranym miejscem i zamyka widok pełnoekranowy.

Parametry widżetu autouzupełniania miejsc

Oprócz parametrów dostępnych programowo widżet autouzupełniania miejsc oferuje też te parametry:

pokaż

show określa, czy widżet jest wyświetlany.

onSelection

Zamknięcie, które ma zostać uruchomione po wybraniu miejsca.

onError

Zamknięcie, które ma zostać uruchomione w przypadku wystąpienia błędu. Jeśli wystąpi błąd, zostanie przekazany obiekt PlacesError.

Dostosowywanie treści i motywu

Parametry AutocompleteUICustomization określają dostosowania interfejsu, które mają zostać zastosowane do widżetu. Dostępne są te opcje dostosowywania:

• AutocompleteListDensity. Ten parametr pozwala wybrać gęstość listy sugestii: multiLine lub twoLine.
• AutocompleteUIIcon. Ten parametr pozwala wybrać, czy ma być wyświetlana domyślna ikona każdego elementu listy.
• theme. Ten parametr określa motyw niestandardowy, który zastępuje wszystkie domyślne atrybuty stylu. Możesz dostosować kolory, typografię, odstępy, obramowania i narożniki komponentu autouzupełniania miejsc. Wartość domyślna to PlacesMaterialTheme. Wszystkie atrybuty motywu, które nie zostały zastąpione, używają stylów domyślnych.

Zobacz przykład pełnego kodu

Przykłady autouzupełniania (nowa wersja)

Używanie parametrów locationRestriction i locationBias

Autouzupełnianie (nowe) domyślnie używa kierowania na adres IP, aby kontrolować obszar wyszukiwania. W przypadku ukierunkowania na adres IP interfejs API używa adresu IP urządzenia, aby ukierunkować wyniki. Możesz opcjonalnie użyć parametru locationRestriction lub locationBias, ale nie obu, aby określić obszar wyszukiwania.

Ograniczenie lokalizacji określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W tym przykładzie użyto ograniczenia lokalizacji, aby ograniczyć żądanie do okrągłego obszaru o promieniu 5000 metrów wokół San Francisco:

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

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

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationRestriction = GMSPlaceCircularLocationOption(center, radius)

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

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

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

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

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

W przypadku ustawienia „location bias” lokalizacja służy jako preferencja, co oznacza, że mogą być zwracane wyniki z określonej lokalizacji, w tym wyniki spoza określonego obszaru. W następnym przykładzie zmieniamy poprzednie żądanie, aby użyć lokalizacji preferowanej:

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

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

let token = GMSAutocompleteSessionToken()

let center = CLLocationCoordinate2DMake(37.775061, -122.419400)
let radius = 5000.0

let filter = GMSAutocompleteFilter()
filter.locationBias = GMSPlaceCircularLocationOption(center, radius)

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

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

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

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

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

Typy użycia

Użyj parametru types, aby ograniczyć wyniki żądania do określonego typu wymienionego w tabeli A i tabeli B. Możesz określić tablicę zawierającą maksymalnie 5 wartości. Jeśli zostanie pominięty, zwracane są wszystkie typy.

W poniższym przykładzie ciąg zapytania to „Soccer”, a parametr types ogranicza wyniki do placówek typu "sporting_goods_store":

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

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

let token = GMSAutocompleteSessionToken()

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

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

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

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

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

Użyj punktu początkowego

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

W tym przykładzie punkt początkowy jest ustawiony na centrum San Francisco:

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

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

let token = GMSAutocompleteSessionToken()

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

let filter = GMSAutocompleteFilter()

filter.origin =  origin

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

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

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

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

Dostosowywanie treści i motywu

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

Dodawanie widżetu autouzupełniania miejsc (pełny kod)

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

Optymalizacja autouzupełniania (nowa wersja)

W tej sekcji opisujemy sprawdzone metody, które pomogą Ci w pełni wykorzystać możliwości usługi Autouzupełnianie (nowa).

Oto ogólne wskazówki:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania (nowego) z Maps JavaScript API, widżetu autouzupełniania (nowego) z pakietu SDK Miejsc na Androida lub widżetu autouzupełniania (nowego) z pakietu SDK Miejsc na iOS.
• Od samego początku poznaj najważniejsze pola danych autouzupełniania (nowej wersji).
• Pola ukierunkowania na lokalizację i ograniczenia lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na działanie autouzupełniania.
• Użyj obsługi błędów, aby upewnić się, że aplikacja będzie działać prawidłowo, jeśli interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje sytuację, gdy nie ma wyboru, i oferuje użytkownikom sposób na kontynuowanie.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi Autouzupełnianie (nowa), użyj masek pól w widżetach informacje o miejscu (nowe) i Autouzupełnianie (nowe), aby zwracać tylko potrzebne pola danych Autouzupełniania (nowego).

Zaawansowana optymalizacja kosztów

Rozważ automatyczne wdrożenie autouzupełniania (nowego), aby uzyskać dostęp do SKU: ceny żądań autouzupełniania i poprosić o wyniki Geocoding API dotyczące wybranego miejsca zamiast informacji o miejscu (nowych). Ceny za żądanie w połączeniu z Geocoding API są bardziej opłacalne niż ceny za sesję, jeśli spełnione są oba te warunki:

• Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu miejsca wybranego przez użytkownika, Geocoding API dostarcza te informacje za mniej niż wywołanie informacji o miejscu (New).
• Jeśli użytkownicy wybierają podpowiedź autouzupełniania średnio w ciągu maksymalnie 4 żądań podpowiedzi autouzupełniania (nowych), ceny za żądanie mogą być bardziej opłacalne niż ceny za sesję.

W zależności od wydajności Autouzupełniania (nowego) interfejs Geocoding API może być dla Twojej aplikacji bardziej opłacalny niż informacje o miejscu (nowe). Skuteczność autouzupełniania (nowego) w każdej aplikacji zależy od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożono sprawdzone metody optymalizacji skuteczności.

Aby znaleźć średnią liczbę żądań dla tabeli, przeanalizuj, ile znaków użytkownik wpisuje średnio przed wybraniem podpowiedzi autouzupełniania (nowej) w aplikacji.

Autouzupełnianie (nowe) oparte na sesji z informacjami o miejscu (nowe)

Używaj autouzupełniania opartego na sesji (nowego) z informacjami o miejscu (nowymi).
Ponieważ Twoja aplikacja wymaga informacji o miejscu (nowych), takich jak nazwa miejsca, status firmy lub godziny otwarcia, Twoja implementacja autouzupełniania (nowego) powinna używać tokena sesji (programowo lub wbudowanego w widżety JavaScript, Android lub iOS) na sesję oraz odpowiednich kodów SKU Miejsc, w zależności od tego, o które pola danych miejsca prosisz¹.

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android lub iOS. Obejmuje to zarówno żądania autouzupełniania (nowe), jak i żądania dotyczące informacji o miejscu (nowe) w przypadku wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko tych pól danych autouzupełniania (nowego), których potrzebujesz.

Implementacja automatyczna
Używaj tokena sesji w żądaniach autouzupełniania (nowych). W żądaniu informacji o miejscu (nowych) dotyczących wybranej podpowiedzi uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi Autouzupełniania (nowego).
2. Token sesji użyty w żądaniu Autouzupełniania (nowego).
3. Parametr fields określający potrzebne pola danych autouzupełniania (nowego).

Autouzupełnianie (nowe) na żądanie z Geocoding API

Zaimplementuj Autouzupełnianie (nowe) automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API w przypadku wybranej podpowiedzi miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej. Wykonanie 4 żądań autouzupełniania i wywołanie Geocoding API w przypadku wybranej podpowiedzi miejsca kosztuje mniej niż autouzupełnianie (nowe) na sesję.¹

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby ułatwić użytkownikom uzyskiwanie podpowiedzi, których szukają, przy użyciu jeszcze mniejszej liczby znaków.

Autouzupełnianie (nowe) oparte na sesjach w przypadku aplikacji, które korzystają tylko z adresów

Używaj autouzupełniania opartego na sesji (nowego) z informacjami o miejscu (nowymi).
Średnia liczba żądań, których oczekujesz, zanim użytkownik wybierze podpowiedź autouzupełniania (nowego), przekracza koszt rozliczania za sesję, dlatego Twoja implementacja autouzupełniania (nowego) powinna używać tokena sesji zarówno w przypadku żądań autouzupełniania (nowego), jak i powiązanych żądań informacji o miejscu (nowych) za sesję. ¹

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania autouzupełniania (nowe), jak i żądania dotyczące informacji o miejscu (nowe) w przypadku wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko tych pól, których potrzebujesz.

Implementacja automatyczna
Używaj tokena sesji w żądaniach autouzupełniania (nowych). Gdy prosisz o informacje o miejscu (nowe) dotyczące wybranej podpowiedzi, uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi Autouzupełniania (nowego).
2. Token sesji użyty w żądaniu Autouzupełniania (nowego).
3. Parametr fields określający pola, takie jak adres i geometria.

Rozważ opóźnienie żądań autouzupełniania (nowa wersja)
Możesz zastosować strategie takie jak opóźnienie żądania autouzupełniania (nowa wersja), dopóki użytkownik nie wpisze pierwszych 3 lub 4 znaków, dzięki czemu aplikacja będzie wysyłać mniej żądań. Jeśli na przykład wysyłasz żądania Autouzupełniania (nowego) dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku, oznacza to, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze podpowiedź, dla której wysyłasz jedno żądanie do interfejsu Geocoding API, łączny koszt będzie obejmował 4 żądania Autouzupełniania (nowego) i żądanie do interfejsu Geocoding API¹.

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań automatycznych spadnie poniżej 4, możesz postępować zgodnie ze wskazówkami dotyczącymi implementacji wydajnego autouzupełniania (nowego) z interfejsem Geocoding API. Pamiętaj, że opóźnianie żądań może być postrzegane przez użytkownika jako opóźnienie, ponieważ może on oczekiwać podpowiedzi po każdym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby pomóc użytkownikom uzyskać podpowiedź, której szukają, przy użyciu mniejszej liczby znaków.

Sprawdzone metody dotyczące skuteczności

Te wskazówki opisują sposoby optymalizacji wydajności autouzupełniania (nowego):

• Dodaj do implementacji Autouzupełniania (nowego) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji automatycznych) ustawienia języka. Ustawienia języka nie są potrzebne w przypadku widżetów, ponieważ pobierają one ustawienia języka z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli autouzupełnianiu (nowemu) towarzyszy mapa, możesz zmienić lokalizację według widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania (nowego), zwykle dlatego, że żadna z nich nie jest adresem, którego szuka, możesz ponownie użyć oryginalnych danych wejściowych użytkownika, aby spróbować uzyskać trafniejsze wyniki:
  • Jeśli oczekujesz, że użytkownik wpisze tylko informacje o adresie, użyj ponownie oryginalnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli spodziewasz się, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania informacji o miejscu (nowego). Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj ustawienia lokalizacji.
  Inne scenariusze, w których najlepiej jest użyć Geocoding API:
  • Użytkownicy wpisują adresy podlokali, np. adresy konkretnych lokali lub mieszkań w budynku. Na przykład czeski adres „Stroupežnického 3191/17, Praha” zwraca częściową podpowiedź w Autouzupełnianiu (nowym).
  • Użytkownicy wpisują adresy z prefiksami segmentów dróg, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Ustalanie lokalizacji na podstawie preferencji

Możesz faworyzować wyniki z określonego obszaru, przekazując parametry location i radius. Dzięki temu autouzupełnianie (nowe) będzie preferować wyświetlanie wyników w określonym obszarze. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Możesz użyć parametru includedRegionCodes, aby filtrować wyniki i wyświetlać tylko miejsca w określonym kraju.

Ograniczanie lokalizacji

Ogranicz wyniki do określonego obszaru, przekazując parametr locationRestriction.

Możesz też ograniczyć wyniki do regionu określonego przez parametry location i radius, dodając parametr locationRestriction. Dzięki temu autouzupełnianie (nowe) zwraca wyniki tylko z tego regionu.