Autouzupełnianie miejsc (nowość)

Usługa autouzupełniania (nowa) to interfejs API iOS, który w odpowiedzi na żądanie zwraca sugestie dotyczące miejsc. Określ w żądaniu ciąg wyszukiwania tekstowego i granice geograficzne, które sterują obszarem wyszukiwania.

Usługa autouzupełniania (nowa) może uwzględniać pełne słowa i podłańcuchy danych wejściowych oraz rozpoznawać nazwy miejsc, adresy i kody plus. Aplikacje mogą więc wysyłać zapytania w trakcie wpisywania zapytania, aby na bieżąco przekazywać Ci sugestie dotyczące miejsc.

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

Na przykład wywołasz interfejs API, podając jako dane wejściowe ciąg tekstowy zawierający częściowe dane użytkownika: „Sycylijski piz” z obszarem wyszukiwania ograniczonym do San Francisco w stanie Kalifornia. Odpowiedź zawiera listę sugestii miejsc pasujących do ciągu wyszukiwania i obszaru wyszukiwania (np. restauracji o nazwie „Sycylijska pizza”, a także szczegółowych informacji o danym miejscu.

Zwrócone sugestie miejsc są zaprojektowane tak, aby można je było przedstawić użytkownikowi, tak aby mógł wybrać odpowiednie miejsce. Możesz wysłać żądanie Szczegóły miejsca (nowe), aby uzyskać więcej informacji o dowolnych zwróconych sugestiach miejsc.

Uwaga: aby korzystać z funkcji widżetu, musisz włączyć pierwotny interfejs API autouzupełniania. Pierwotny i nowy interfejs API można włączyć jednocześnie. Więcej informacji znajdziesz w przewodniku po migracji dotyczącym autouzupełniania miejsc.

Żądania autouzupełniania (nowe)

Utwórz żądanie autouzupełniania, wywołując metodę na stronie GMSPlaceClient. 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ż użyć właściwości GMSAutocompleteSessionToken, aby powiązać żądania z sesją rozliczeniową, i GMSAutocompleteFilter, aby zastosować ją do wyników.

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

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

Autouzupełnianie (nowe) odpowiedzi

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

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

Wymagane parametry

zapytanie

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

Parametry opcjonalne

Niestandardowe typy treści

Miejsce może mieć tylko jeden typ główny z powiązanych z nim typów Tabela A lub Tabela B. np. typ podstawowy to mexican_restaurant lub steak_house.

Domyślnie interfejs API zwraca wszystkie miejsca na podstawie parametru input, niezależnie od podstawowej wartości typu powiązanej z miejscem. Możesz ograniczyć wyniki tylko do określonego typu podstawowego lub podstawowego, przekazując parametr types.

Za pomocą tego parametru możesz określić maksymalnie 5 wartości typów z tabeli A lub tabeli B. Miejsce musi pasować do jednej z określonych wartości typu podstawowego, aby zostało uwzględnione w odpowiedzi.

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

• Określono więcej niż 5 typów.
• Wszystkie nierozpoznane typy są określone.

kraje

Uwzględniaj tylko wyniki z listy określonych regionów określonej w postaci tablicy zawierającej maksymalnie 15 dwuznakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli go pominiesz, do odpowiedzi nie będą stosowane żadne ograniczenia. 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" ];

GooglePlacesSwift

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

Jeśli podasz zarówno locationRestriction, jak i countries, wyniki pojawią się w obszarze przecięcia tych ustawień.

inputOffset

Przesunięcie znaków Unicode liczone od zera, które wskazuje pozycję kursora w regionie input. Pozycja kursora może wpływać na wyświetlane podpowiedzi. Jeśli pole jest puste, domyślna długość to input.

Promowanie lokalizacji lub ograniczenie związane z lokalizacją

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

Uwaga: jeśli pominiesz zarówno locationBias, jak i locationRestriction, interfejs API domyślnie użyje promowania adresów IP. W przypadku promowania ze względu na adres IP interfejs API używa adresu IP urządzenia, aby wpływać na wyniki.

• locationBias określa obszar do przeszukania. Ta lokalizacja działa odchylenia, co oznacza, że mogą być zwracane wyniki dotyczące określonej lokalizacji, w tym wyniki spoza określonego obszaru.

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

Określ obszar locationBias lub locationRestriction jako prostokątny lub okrągły obszar.

Okrąg jest wyznaczany przez punkt środkowy i promień w metrach. Promień musi mieścić się w zakresie od 0,0 do 50 000,0 włącznie. Wartością domyślną jest 0,0. W przypadku locationRestriction ustaw promień na wartość większą niż 0, 0. W przeciwnym razie żądanie nie zwróci ż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);

GooglePlacesSwift

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 o długości i szerokości geograficznej reprezentowany jako dwa przeciwległe punkty: low i high. Widoczny obszar jest uważany za zamknięty, co oznacza, że obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w przedziale od -90 do 90 stopni włącznie, a długość geograficzna – od -180 do 180 stopni włącznie:

• 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 (widoczny obszar przecina 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.

Zarówno pole low, jak i high muszą być wypełnione, a reprezentowane pole nie może być puste. Gdy to zrobisz, pojawi się błąd.

Na przykład ten widoczny obszar w całości obejmuje Nowy Jork:

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)
  

pochodzenie

Punkt początkowy, z którego oblicza się prostą odległość do miejsca docelowego (zwracany jako distanceMeters). Jeśli ta wartość zostanie pominięta, odległość prosta nie zostanie zwrócona. Trzeba ją podać jako szerokość i długość geograficzną:

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

Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów domen ccTLD jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”).

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

sessionToken

Tokeny sesji to ciągi wygenerowane przez użytkownika, które śledzą wywołania autouzupełniania (nowe) jako „sesje”. Autouzupełnianie (nowość) korzysta z tokenów sesji, aby grupować zapytania i fazy wyboru autouzupełniania wyszukiwania użytkownika w oddzielną sesję na potrzeby rozliczeń. Więcej informacji znajdziesz w artykule Tokeny sesji.

Przykłady autouzupełniania (nowe)

Używanie ograniczeń lokalizacji i uprzedzeń według lokalizacji

Autouzupełnianie (nowość) do kontrolowania obszaru wyszukiwania wykorzystuje domyślnie promowanie adresu IP. W przypadku promowania ze względu na adres IP interfejs API używa adresu IP urządzenia do promowania wyników. Opcjonalnie do określenia obszaru wyszukiwania możesz użyć właściwości locationRestriction lub locationBias, ale nie obu naraz.

Ograniczenie lokalizacji określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W poniższym przykładzie użyto ograniczenia lokalizacji, aby ograniczyć żądanie do okrągłego ograniczenia lokalizacji z promieniem 5000 metrów wyśrodkowanym na San Francisco:

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

W przypadku uprzedzenia lokalizacji lokalizacja działa jako odchylenie, co oznacza, że mogą być zwracane wyniki dotyczące określonej lokalizacji, w tym wyniki spoza określonego obszaru. W następnym przykładzie zmieniamy poprzednie żądanie tak, by używało uprzedzeń związanych z lokalizacją:

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

Typy użycia

Parametr type umożliwia ograniczenie wyników żądania do określonego typu, zgodnie z informacjami podanymi w tabelach A i tabeli B. Możesz określić tablicę zawierającą maksymalnie 5 wartości. Jeśli nazwa zostanie pominięta, zwracane są wszystkie typy.

Poniższy przykład określa ciąg zapytania „Piłka nożna” i używa parametru „type”, by ograniczyć wyniki do instytucji 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
  // 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.
}
    

Użyj punktu początkowego

Jeśli umieścisz w żądaniu parametr origin, który jest podawany jako współrzędne geograficzne, interfejs API uwzględni w odpowiedzi odległość wprost od punktu początkowego do miejsca docelowego. Odpowiedź zwraca odległość distanceMeters.

W tym przykładzie punkt początkowy jest ustawiony na 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
  // 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.
}
  

Atrybucje

Z autouzupełniania (nowego) możesz korzystać nawet bez mapy. Jeśli jest wyświetlana mapa, musi to być mapa Google. Gdy wyświetlasz sugestie z usługi autouzupełniania (nowe) bez mapy, w polu wyszukiwania/wynikach wyszukiwania musisz umieścić logo Google. Więcej informacji znajdziesz w artykule Wyświetlanie logo i atrybucji Google.