Tự động hoàn thành địa điểm (Mới)

Dịch vụ Tự động hoàn thành (Mới) là một API iOS trả về các đề xuất về địa điểm để phản hồi một yêu cầu. Trong yêu cầu, hãy chỉ định một chuỗi tìm kiếm văn bản và ranh giới địa lý kiểm soát khu vực tìm kiếm.

Dịch vụ Tự động hoàn thành (Mới) có thể so khớp các từ và chuỗi con đầy đủ của thông tin đầu vào, phân giải tên địa điểm, địa chỉ và Plus Codes. Do đó, các ứng dụng có thể gửi truy vấn khi người dùng nhập để đưa ra đề xuất địa điểm ngay lập tức.

Đề xuất địa điểm là các địa điểm, chẳng hạn như doanh nghiệp, địa chỉ và điểm yêu thích, dựa trên chuỗi văn bản đầu vào và khu vực tìm kiếm được chỉ định.

Ví dụ: bạn gọi API bằng cách sử dụng dữ liệu đầu vào là một chuỗi chứa một phần dữ liệu đầu vào của người dùng, "Spagh", với khu vực tìm kiếm được giới hạn ở Thành phố New York. Sau đó, phản hồi sẽ chứa danh sách đề xuất địa điểm khớp với chuỗi tìm kiếm và khu vực tìm kiếm, chẳng hạn như nhà hàng có tên "Cafe Spaghetti", cùng với thông tin chi tiết về địa điểm đó.

Đề xuất địa điểm được trả về được thiết kế để hiển thị cho người dùng để họ có thể chọn địa điểm mong muốn. Bạn có thể gửi yêu cầu Chi tiết địa điểm (Mới) để biết thêm thông tin về bất kỳ đề xuất địa điểm nào được trả về.

Bạn có thể tích hợp chức năng Tự động hoàn thành (Mới) vào ứng dụng theo hai cách chính:

• Nhận thông tin dự đoán về địa điểm theo phương thức lập trình: Gọi trực tiếp API để truy xuất thông tin dự đoán và hiển thị thông tin đó trong giao diện người dùng tuỳ chỉnh.
• Thêm tiện ích Place Autocomplete: Cung cấp trải nghiệm tự động hoàn thành tìm kiếm có sẵn, hiển thị các cụm từ gợi ý khi người dùng nhập.

Nhận thông tin dự đoán về địa điểm theo phương thức lập trình

Yêu cầu về tính năng Tự động hoàn thành (Mới)

Tạo yêu cầu tự động hoàn thành bằng cách gọi một phương thức trên GMSPlacesClient. Bạn có thể truyền tham số trong đối tượng GMSAutocompleteRequest. Phản hồi cung cấp các đề xuất Tự động hoàn thành trong một đối tượng GMSAutocompletePlaceSuggestion.

Bạn bắt buộc phải cung cấp khoá API và các tham số query. Bạn cũng có thể thêm GMSAutocompleteSessionToken để liên kết các yêu cầu với một phiên thanh toán và GMSAutocompleteFilter để áp dụng cho kết quả.

Để biết thêm thông tin về các tham số bắt buộc và không bắt buộc, hãy xem phần tham số của tài liệu này.

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

Câu trả lời của tính năng Tự động hoàn thành (Mới)

Tính năng Tự động hoàn thành trả về một mảng gồm tối đa 5 thực thể GMSAutocompleteSuggestion. Mảng này chứa:

• placeID
• types: Các loại áp dụng cho địa điểm này.
• distanceMeters: Khoảng cách từ điểm gốc.
• attributedFullText: Văn bản đầy đủ mà con người có thể đọc được của một đề xuất.
• attributedPrimaryText: Văn bản chính mà con người có thể đọc được của một đề xuất.
• attributedSecondaryText: Văn bản phụ mà con người có thể đọc được của một đề xuất.
• structuredFormat: Tên cụ thể và văn bản phân biệt, chẳng hạn như thành phố hoặc khu vực.

Tham số bắt buộc

truy vấn

Chuỗi văn bản cần tìm kiếm. Chỉ định từ đầy đủ và chuỗi con, tên địa điểm, địa chỉ và Plus Codes. Dịch vụ Tự động hoàn thành (Mới) trả về các kết quả phù hợp dựa trên chuỗi này và sắp xếp kết quả dựa trên mức độ liên quan mà dịch vụ nhận thấy.

Thông số tùy chọn

sessionToken

Mã thông báo phiên là các chuỗi do người dùng tạo để theo dõi các lệnh gọi của tính năng Tự động hoàn thành (Mới) – cả lệnh gọi được thực hiện thông qua tiện ích và lệnh gọi có lập trình – dưới dạng "phiên". Tính năng Tự động hoàn thành (Mới) sử dụng mã thông báo phiên để nhóm các giai đoạn truy vấn và lựa chọn của một lượt tìm kiếm tự động hoàn thành của người dùng thành một phiên riêng biệt cho mục đích thanh toán.

Bạn có thể hiển thị mã thông báo phiên của tính năng Tự động hoàn thành địa điểm để truyền mã đó đến các dịch vụ khác không thuộc Places SDK cho iOS, chẳng hạn như Xác thực địa chỉ:

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

Xem phần Mã thông báo phiên để biết thêm thông tin.

Tham số AutocompleteFilter không bắt buộc

loại

Một địa điểm chỉ có thể có một loại chính trong số các loại thuộc Bảng A hoặc Bảng B được liên kết với địa điểm đó. Ví dụ: loại chính có thể là mexican_restaurant hoặc steak_house.

Theo mặc định, API trả về tất cả địa điểm dựa trên tham số input, bất kể giá trị loại chính liên kết với địa điểm đó. Hạn chế kết quả thuộc một loại chính hoặc các loại chính nhất định bằng cách truyền tham số types.

Sử dụng tham số này để chỉ định tối đa 5 giá trị loại trong Bảng A hoặc Bảng B. Một địa điểm phải khớp với một trong các giá trị loại chính được chỉ định để được đưa vào phản hồi.

Yêu cầu sẽ bị từ chối kèm theo lỗi INVALID_REQUEST nếu:

• Bạn đã chỉ định hơn 5 loại.
• Mọi loại không được nhận dạng đều được chỉ định.

Ví dụ: để giới hạn kết quả ở các cửa hàng bán đồ thể thao, hãy chỉ định loại đó trong 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" ];

quốc gia

Chỉ bao gồm kết quả từ danh sách các khu vực được chỉ định, được chỉ định dưới dạng một mảng gồm tối đa 15 giá trị ccTLD ("miền cấp cao nhất") có hai ký tự. Nếu bạn bỏ qua, thì sẽ không có quy định hạn chế nào được áp dụng cho phản hồi. Ví dụ: Để giới hạn khu vực ở Đức và Pháp:

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

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

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

Nếu bạn chỉ định cả locationRestriction và countries, thì kết quả sẽ nằm trong khu vực giao nhau của hai chế độ cài đặt này.

inputOffset

Độ lệch ký tự Unicode dựa trên số 0 cho biết vị trí con trỏ trong input. Vị trí con trỏ có thể ảnh hưởng đến kết quả dự đoán được trả về. Nếu trống, giá trị này sẽ mặc định là độ dài của input.

locationBias hoặc locationRestriction

Bạn có thể chỉ định locationBias hoặc locationRestriction (nhưng không được chỉ định cả hai) để xác định khu vực tìm kiếm. Hãy coi locationRestriction là việc chỉ định khu vực mà kết quả phải nằm trong đó, còn locationBias là việc chỉ định khu vực mà kết quả phải ở gần nhưng có thể nằm ngoài khu vực đó.

• locationBias chỉ định một khu vực để tìm kiếm. Vị trí này đóng vai trò là một thiên kiến, nghĩa là kết quả xung quanh vị trí được chỉ định có thể được trả về, bao gồm cả kết quả bên ngoài khu vực được chỉ định.

• locationRestriction chỉ định một khu vực để tìm kiếm. Hệ thống sẽ không trả về kết quả nằm ngoài khu vực đã chỉ định.

Chỉ định khu vực locationBias hoặc locationRestriction dưới dạng khung nhìn hình chữ nhật hoặc hình tròn.

Hình tròn được xác định bằng tâm điểm và bán kính tính bằng mét. Bán kính phải nằm trong khoảng từ 0 đến 50.000 (bao gồm cả hai giá trị này). Giá trị mặc định là 0.0. Đối với locationRestriction, bạn phải đặt bán kính thành một giá trị lớn hơn 0.0. Nếu không, yêu cầu sẽ không trả về kết quả nào.

Ví dụ:

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

Hình chữ nhật là một khung nhìn vĩ độ-kinh độ, được biểu thị dưới dạng hai điểm low và high đối diện nhau theo đường chéo. Khung nhìn được coi là một vùng khép kín, nghĩa là bao gồm cả ranh giới của nó. Ranh giới vĩ độ phải nằm trong khoảng từ -90 đến 90 độ và ranh giới kinh độ phải nằm trong khoảng từ -180 đến 180 độ:

• Nếu low = high, thì khung nhìn sẽ bao gồm điểm duy nhất đó.
• Nếu low.longitude > high.longitude, thì phạm vi kinh độ sẽ bị đảo ngược (khung nhìn vượt qua đường kinh độ 180 độ).
• Nếu low.longitude = -180 độ và high.longitude= 180 độ, thì khung nhìn sẽ bao gồm tất cả kinh độ.
• Nếu low.longitude = 180 độ và high.longitude = -180 độ, thì phạm vi kinh độ sẽ trống.

Bạn phải điền cả low và high, đồng thời hộp được biểu thị không được để trống. Khung nhìn trống sẽ dẫn đến lỗi.

Ví dụ: khung nhìn này bao quanh hoàn toàn Thành phố New York:

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

nguồn gốc

Điểm xuất phát để tính khoảng cách theo đường thẳng đến điểm đến (được trả về dưới dạng distanceMeters). Nếu bạn bỏ qua giá trị này, thì khoảng cách theo đường thẳng sẽ không được trả về. Phải được chỉ định dưới dạng toạ độ vĩ độ và kinh độ:

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

Mã khu vực dùng để định dạng phản hồi, được chỉ định dưới dạng giá trị gồm hai ký tự ccTLD ("miền cấp cao nhất"). Hầu hết các mã ccTLD đều giống với mã ISO 3166-1, ngoại trừ một số trường hợp ngoại lệ đáng chú ý. Ví dụ: ccTLD của Vương quốc Anh là "uk" (.co.uk) trong khi mã ISO 3166-1 của quốc gia này là "gb" (về mặt kỹ thuật là cho thực thể "Vương quốc Liên hiệp Anh và Bắc Ireland").

Nếu bạn chỉ định mã vùng không hợp lệ, thì API sẽ trả về lỗi INVALID_ARGUMENT. Tham số này có thể ảnh hưởng đến kết quả dựa trên luật hiện hành.

shouldIncludePureServiceAreaBusinesses

Nếu true, hãy trả về các doanh nghiệp chỉ phục vụ tận nơi trong mảng phản hồi. Doanh nghiệp chỉ phục vụ tận nơi là doanh nghiệp trực tiếp cung cấp dịch vụ tận nơi hoặc giao hàng cho khách hàng, nhưng không phục vụ khách hàng tại địa chỉ doanh nghiệp.

Ví dụ:

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

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

Thêm tiện ích Place Autocomplete

Để dễ dàng cung cấp trải nghiệm Place Autocomplete nhất quán, bạn có thể thêm tiện ích Place Autocomplete vào ứng dụng của mình. Tiện ích này cung cấp một giao diện chuyên dụng, toàn màn hình, xử lý hoạt động đầu vào của người dùng và hiển thị thông tin dự đoán về địa điểm cho người dùng, đồng thời trả về các đối tượng AutocompletePlaceSuggestion cho ứng dụng. Sau đó, bạn có thể gửi yêu cầu Place Details (Mới) để nhận thông tin bổ sung về bất kỳ thông tin dự đoán nào về địa điểm.

Giống như khi lấy thông tin dự đoán về địa điểm theo phương thức lập trình, tiện ích Place Autocomplete cho phép bạn sử dụng mã phiên để nhóm các yêu cầu tự động hoàn thành vào phiên cho mục đích thanh toán. Bạn có thể truyền mã thông báo phiên bằng cách gọi AutocompleteSessionToken().

Nếu bạn không cung cấp mã phiên, tiện ích sẽ tạo một mã phiên Tự động hoàn thành cho bạn. Sau đó, bạn có thể lấy mã này từ lệnh gọi lại onSelection. Để biết thêm thông tin về cách sử dụng mã thông báo phiên, hãy xem bài viết Giới thiệu về mã thông báo phiên.

Khi giá trị liên kết show được đặt thành true, người dùng sẽ được đưa đến chế độ xem toàn màn hình, nơi họ có thể chọn một địa điểm. Khi người dùng nhập, tiện ích sẽ trả về các đề xuất cho địa điểm như doanh nghiệp, địa chỉ và điểm yêu thích. Khi người dùng chọn một địa điểm, tiện ích sẽ gọi trình xử lý onSelection với địa điểm đã chọn và đóng chế độ xem toàn màn hình.

Tham số tiện ích Place Autocomplete

Ngoài các tham số có sẵn theo phương thức lập trình, tiện ích Place Autocomplete cũng cung cấp các tham số sau.

hiện (lên)/cho thấy

show chỉ định xem tiện ích có hiển thị hay không.

onSelection

Hàm closure sẽ chạy khi một địa điểm được chọn.

onError

Hàm đóng để chạy khi xảy ra lỗi. PlacesError sẽ được truyền nếu xảy ra lỗi.

Tuỳ chỉnh nội dung và giao diện

Các tham số AutocompleteUICustomization chỉ định các tuỳ chỉnh giao diện người dùng cần áp dụng cho tiện ích. Các lựa chọn tuỳ chỉnh bao gồm:

• AutocompleteListDensity. Tham số này cho phép bạn chọn mật độ của danh sách đề xuất, multiLine hoặc twoLine.
• AutocompleteUIIcon. Tham số này cho phép bạn chọn có hiển thị biểu tượng mặc định cho mỗi mục danh sách hay không.
• theme. Tham số này chỉ định một giao diện tuỳ chỉnh ghi đè mọi thuộc tính kiểu mặc định. Bạn có thể tuỳ chỉnh màu sắc, kiểu chữ, khoảng cách, đường viền và góc của thành phần Place Autocomplete. Giá trị mặc định là PlacesMaterialTheme. Mọi thuộc tính giao diện không bị ghi đè đều sử dụng kiểu mặc định.

Xem ví dụ về mã đầy đủ.

Ví dụ về tính năng Tự động hoàn thành (Mới)

Sử dụng locationRestriction và locationBias

Tính năng Tự động hoàn thành (Mới) sử dụng tính năng thiên vị IP theo mặc định để kiểm soát khu vực tìm kiếm. Khi thiên vị theo IP, API sẽ sử dụng địa chỉ IP của thiết bị để thiên vị kết quả. Bạn có thể tuỳ ý sử dụng locationRestriction hoặc locationBias (nhưng không được dùng cả hai) để chỉ định một khu vực cần tìm kiếm.

Giới hạn vị trí chỉ định khu vực cần tìm kiếm. Kết quả bên ngoài khu vực được chỉ định sẽ không được trả về. Ví dụ sau đây sử dụng quy định hạn chế về vị trí để giới hạn yêu cầu trong một khu vực hình tròn có bán kính 5.000 m, lấy San Francisco làm tâm:

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

Với độ lệch vị trí, vị trí đóng vai trò là độ lệch, tức là kết quả xung quanh vị trí được chỉ định có thể được trả về, bao gồm cả kết quả bên ngoài khu vực được chỉ định. Ví dụ tiếp theo thay đổi yêu cầu trước đó để sử dụng độ lệch vị trí:

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

Các hình thức sử dụng

Sử dụng tham số types để hạn chế kết quả của một yêu cầu thuộc một loại nhất định như được liệt kê trong Bảng A và Bảng B. Bạn có thể chỉ định một mảng có tối đa 5 giá trị. Nếu bạn bỏ qua, tất cả các loại sẽ được trả về.

Ví dụ sau đây chỉ định chuỗi truy vấn "Soccer" (Bóng đá) và sử dụng tham số types để giới hạn kết quả cho các cơ sở thuộc loại "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.
    }
  }
}];

Sử dụng nguồn gốc

Khi bạn đưa tham số origin vào yêu cầu (được chỉ định dưới dạng toạ độ vĩ độ và kinh độ), API sẽ đưa khoảng cách đường thẳng từ điểm xuất phát đến điểm đến vào phản hồi. Phản hồi trả về khoảng cách là distanceMeters.

Ví dụ này đặt điểm xuất phát là trung tâm của 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.
      }
    }
}];

Tuỳ chỉnh nội dung và giao diện

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

Thêm tiện ích Place Autocomplete (mã đầy đủ)

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

Tối ưu hoá tính năng Tự động hoàn thành (Mới)

Phần này mô tả các phương pháp hay nhất để giúp bạn khai thác tối đa dịch vụ Tự động hoàn thành (Mới).

Sau đây là một số nguyên tắc chung:

• Cách nhanh nhất để phát triển một giao diện người dùng hoạt động hiệu quả là sử dụng Tiện ích Tự động hoàn thành (Mới) của API JavaScript của Maps, Tiện ích Tự động hoàn thành (Mới) của SDK Địa điểm cho Android, hoặc Tiện ích Tự động hoàn thành (Mới) của SDK Địa điểm cho iOS.
• Hiểu rõ các trường dữ liệu cần thiết của tính năng Tự động hoàn thành (Mới) ngay từ đầu.
• Các trường thiên vị vị trí và hạn chế vị trí là không bắt buộc nhưng có thể ảnh hưởng đáng kể đến hiệu suất tự động hoàn thành.
• Sử dụng tính năng xử lý lỗi để đảm bảo ứng dụng của bạn xuống cấp một cách linh hoạt nếu API trả về lỗi.
• Đảm bảo ứng dụng của bạn xử lý được trường hợp không có lựa chọn nào và cung cấp cho người dùng cách để tiếp tục.

Các phương pháp hay nhất để tối ưu hoá chi phí

Tối ưu hoá chi phí cơ bản

Để tối ưu hoá chi phí sử dụng dịch vụ Tự động hoàn thành (Mới), hãy sử dụng mặt nạ trường trong các tiện ích Place Details (Mới) và Tự động hoàn thành (Mới) để chỉ trả về trường dữ liệu Tự động hoàn thành (Mới) mà bạn cần.

Tối ưu hoá chi phí nâng cao

Hãy cân nhắc việc triển khai tính năng Tự động hoàn thành (Mới) theo phương thức lập trình để sử dụng SKU: Giá của yêu cầu Tự động hoàn thành và yêu cầu kết quả của Geocoding API về địa điểm đã chọn thay vì Place Details (Mới). Mô hình định giá theo yêu cầu kết hợp với Geocoding API sẽ tiết kiệm chi phí hơn so với mô hình định giá theo phiên (dựa trên phiên) nếu đáp ứng cả hai điều kiện sau:

• Nếu bạn chỉ cần vĩ độ và kinh độ hoặc địa chỉ của địa điểm mà người dùng đã chọn, thì Geocoding API sẽ cung cấp thông tin này với chi phí thấp hơn so với lệnh gọi Place Details (Mới).
• Nếu người dùng chọn một cụm từ gợi ý của tính năng tự động hoàn thành trong trung bình 4 yêu cầu cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) trở xuống, thì mức giá theo yêu cầu có thể tiết kiệm chi phí hơn so với mức giá theo phiên.

Geocoding API có thể là một lựa chọn tiết kiệm chi phí hơn so với Place Details (Mới) cho ứng dụng của bạn, tuỳ thuộc vào hiệu suất sử dụng Autocomplete (Mới). Hiệu suất của tính năng Tự động hoàn thành (Mới) trong mỗi ứng dụng sẽ khác nhau tuỳ thuộc vào nội dung người dùng nhập, nơi ứng dụng được sử dụng và liệu các phương pháp hay nhất để tối ưu hoá hiệu suất đã được triển khai hay chưa.

Để tìm số yêu cầu trung bình cho bảng, hãy phân tích xem trung bình người dùng nhập bao nhiêu ký tự trước khi chọn một cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) trong ứng dụng của bạn.

Tính năng Tự động hoàn thành (Mới) dựa trên phiên có Place Details (Mới)

Sử dụng tính năng Tự động hoàn thành (Mới) dựa trên phiên với Place Details (Mới).
Vì ứng dụng của bạn yêu cầu Chi tiết địa điểm (Mới), chẳng hạn như tên địa điểm, trạng thái doanh nghiệp hoặc giờ mở cửa, nên việc triển khai tính năng Tự động hoàn thành (Mới) phải sử dụng mã thông báo phiên (theo phương thức lập trình hoặc được tích hợp vào các tiện ích JavaScript, Android hoặc iOS) cho mỗi phiên cộng với các SKU Địa điểm hiện hành, tuỳ thuộc vào trường dữ liệu địa điểm mà bạn yêu cầu.¹

Triển khai tiện ích
Tính năng quản lý phiên được tích hợp tự động vào các tiện ích JavaScript, Android hoặc iOS. Trong đó bao gồm cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu trường dữ liệu Tự động hoàn thành (Mới) mà bạn cần.

Triển khai có lập trình
Sử dụng mã thông báo phiên với các yêu cầu Tự động hoàn thành (Mới). Khi yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn, hãy thêm các tham số sau:

1. Mã địa điểm từ phản hồi của tính năng Tự động hoàn thành (Mới)
2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành (Mới)
3. Tham số fields chỉ định trường dữ liệu của tính năng Tự động hoàn thành (Mới) mà bạn cần

Tính năng Tự động hoàn thành (Mới) theo yêu cầu bằng Geocoding API

Triển khai tính năng Tự động hoàn thành (Mới) theo phương thức lập trình mà không cần mã thông báo phiên và gọi Geocoding API trên cụm từ gợi ý địa điểm đã chọn.
Geocoding API cung cấp địa chỉ và toạ độ vĩ độ/kinh độ. Việc thực hiện 4 yêu cầu Autocomplete Requests cộng với một lệnh gọi Geocoding API về cụm từ gợi ý địa điểm đã chọn sẽ có chi phí thấp hơn chi phí cho mỗi phiên của Autocomplete (Mới).¹

Hãy cân nhắc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm kiếm chỉ với ít ký tự hơn.

Tính năng Tự động hoàn thành dựa trên phiên (Mới) cho các ứng dụng chỉ có địa chỉ

Sử dụng tính năng Tự động hoàn thành (Mới) dựa trên phiên với Place Details (Mới).
Vì số lượng yêu cầu trung bình mà bạn dự kiến thực hiện trước khi người dùng chọn một cụm từ gợi ý của tính năng Tự động hoàn thành (Mới) vượt quá chi phí của mức giá theo phiên, nên việc triển khai tính năng Tự động hoàn thành (Mới) phải sử dụng mã thông báo phiên cho cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Chi tiết địa điểm (Mới) liên quan theo phiên. ¹

Triển khai tiện ích
Tính năng quản lý phiên được tích hợp tự động vào các tiện ích JavaScript, Android hoặc iOS. Trong đó bao gồm cả yêu cầu Tự động hoàn thành (Mới) và yêu cầu Place Details (Mới) đối với cụm từ gợi ý đã chọn. Hãy nhớ chỉ định tham số fields để đảm bảo bạn chỉ yêu cầu các trường cần thiết.

Triển khai có lập trình
Sử dụng mã thông báo phiên với các yêu cầu Tự động hoàn thành (Mới). Khi yêu cầu Place Details (Mới) về cụm từ gợi ý đã chọn, hãy thêm các tham số sau:

1. Mã địa điểm từ phản hồi của tính năng Tự động hoàn thành (Mới)
2. Mã thông báo phiên được dùng trong yêu cầu Tự động hoàn thành (Mới)
3. Tham số fields chỉ định các trường chẳng hạn như địa chỉ và hình học

Cân nhắc việc trì hoãn yêu cầu Tự động hoàn thành (Mới)
Bạn có thể áp dụng các chiến lược như trì hoãn yêu cầu Tự động hoàn thành (Mới) cho đến khi người dùng nhập 3 hoặc 4 ký tự đầu tiên để ứng dụng của bạn đưa ra ít yêu cầu hơn. Ví dụ: việc đưa ra yêu cầu về tính năng Tự động hoàn thành (Mới) cho mỗi ký tự sau khi người dùng nhập ký tự thứ ba có nghĩa là nếu người dùng nhập 7 ký tự rồi chọn một cụm từ gợi ý mà bạn đưa ra một yêu cầu về Geocoding API, thì tổng chi phí sẽ là 4 yêu cầu về tính năng Tự động hoàn thành (Mới) + Mã hoá địa lý.¹

Nếu việc trì hoãn yêu cầu có thể giúp số yêu cầu có lập trình trung bình của bạn giảm xuống dưới 4, thì bạn có thể làm theo hướng dẫn triển khai Autocomplete (Mới) hiệu suất cao bằng Geocoding API. Xin lưu ý rằng việc trì hoãn yêu cầu có thể được người dùng coi là độ trễ, người dùng có thể muốn xem thông tin dự đoán sau mỗi lần nhấn phím mới.

Hãy cân nhắc việc áp dụng các phương pháp hay nhất về hiệu suất để giúp người dùng nhận được cụm từ gợi ý mà họ đang tìm kiếm với ít ký tự hơn.

Các phương pháp hay nhất về hiệu suất

Các nguyên tắc sau đây mô tả cách tối ưu hoá hiệu suất của tính năng Tự động hoàn thành (Mới):

• Thêm các quy định hạn chế theo quốc gia, thiên vị vị trí và (đối với việc triển khai có lập trình) ngôn ngữ ưu tiên cho việc triển khai Tính năng tự động hoàn thành (Mới). Bạn không cần đặt ngôn ngữ ưu tiên cho các tiện ích vì các tiện ích này sẽ chọn ngôn ngữ ưu tiên từ trình duyệt hoặc thiết bị di động của người dùng.
• Nếu tính năng Tự động hoàn thành (Mới) đi kèm với bản đồ, bạn có thể thiên vị vị trí theo khung nhìn bản đồ.
• Trong trường hợp người dùng không chọn một trong các cụm từ gợi ý của tính năng Tự động hoàn thành (Mới), thường là do không có cụm từ gợi ý nào là địa chỉ kết quả mong muốn, bạn có thể sử dụng lại thông tin đầu vào ban đầu của người dùng để cố gắng nhận được kết quả phù hợp hơn:
  • Nếu bạn muốn người dùng chỉ nhập thông tin địa chỉ, hãy sử dụng lại thông tin đầu vào ban đầu của người dùng trong lệnh gọi đến Geocoding API.
  • Nếu bạn muốn người dùng nhập cụm từ tìm kiếm cho một địa điểm cụ thể theo tên hoặc địa chỉ, hãy sử dụng yêu cầu Chi tiết địa điểm (Mới). Nếu bạn chỉ muốn nhận kết quả ở một khu vực cụ thể, hãy sử dụng tính năng thiên vị vị trí.
  Các trường hợp khác mà bạn nên quay lại Geocoding API bao gồm:
  • Người dùng nhập địa chỉ của cơ sở phụ, chẳng hạn như địa chỉ của các căn hộ hoặc căn hộ cụ thể trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" ở Séc sẽ trả về một cụm từ gợi ý một phần trong tính năng Tự động hoàn thành (Mới).
  • Người dùng nhập địa chỉ có tiền tố đoạn đường như "23-30 29th St, Queens" ở Thành phố New York hoặc "47-380 Kamehameha Hwy, Kaneohe" trên đảo Kauai ở Hawaii.

Thiên vị vị trí

Tạo độ lệch cho kết quả theo một khu vực cụ thể bằng cách truyền tham số location và tham số radius. Thao tác này hướng dẫn tính năng Tự động hoàn thành (Mới) ưu tiên hiển thị kết quả trong khu vực đã xác định. Kết quả bên ngoài khu vực đã xác định vẫn có thể xuất hiện. Bạn có thể sử dụng tham số includedRegionCodes để lọc kết quả nhằm chỉ hiển thị những địa điểm trong một quốc gia cụ thể.

Hạn chế về vị trí

Giới hạn kết quả trong một khu vực cụ thể bằng cách truyền tham số locationRestriction.

Bạn cũng có thể giới hạn kết quả ở khu vực được xác định bằng location và tham số radius bằng cách thêm tham số locationRestriction. Thao tác này hướng dẫn tính năng Tự động hoàn thành (Mới) chỉ trả về kết quả trong khu vực đó.