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

Dịch vụ Autocomplete (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ừ đầy đủ và chuỗi con của dữ liệu đầu vào, phân giải tên địa điểm, địa chỉ và mã cộng. Do đó, các ứng dụng có thể gửi truy vấn khi người dùng nhập để cung cấp các đề xuất về địa điểm ngay lập tức.

Đề xuất về địa điểm là những địa điểm (chẳng hạn như doanh nghiệp, địa chỉ và điểm tham quan) 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 một chuỗi làm đầu vào có chứa một phần thông tin đầu vào của người dùng, "Spagh", với khu vực tìm kiếm giới hạn ở Thành phố New York. Sau đó, phản hồi sẽ chứa danh sách đề xuất về địa điểm phù hợ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ế để trình bày cho người dùng để họ có thể chọn địa điểm mong muốn. Bạn có thể đưa ra yêu cầu Place Details (New) để biết thêm thông tin về bất kỳ đề xuất nào về địa điểm đượ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 2 cách chính:

• Nhận các dự đoán về địa điểm theo phương thức lập trình: Gọi API trực tiếp để truy xuất các dự đoán và hiển thị chúng trong một giao diện người dùng tuỳ chỉnh.
• Thêm tiện ích Tự động hoàn thành địa điểm: Cung cấp trải nghiệm tự động hoàn thành tìm kiếm sẵn sàng sử dụng, 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 cách có lập trình

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

Tạo một 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 các tham số trong đối tượng GMSAutocompleteRequest. Phản hồi cung cấp các đề xuất của tính năng Tự động hoàn thành trong một đối tượng GMSAutocompletePlaceSuggestion.

Bạn phải có 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 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 xuất phát.
• 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.

Thông số bắt buộc

truy vấn

Chuỗi văn bản mà bạn muốn tìm kiếm. Chỉ định toàn bộ từ và chuỗi con, tên địa điểm, địa chỉ và mã cộng. Dịch vụ Tự động hoàn thành (Mới) trả về các kết quả trùng khớp đề xuất dựa trên chuỗi này và sắp xếp các kết quả theo mức độ liên quan mà người dùng cảm nhận được.

Thông số tùy chọn

sessionToken

Mã thông báo phiên là chuỗi do người dùng tạo để theo dõi các lệnh gọi 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 theo chương 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 cụm 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 Tự động hoàn thành địa điểm để truyền mã thông báo đó đế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);

Hãy 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 duy nhất trong số các loại 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 sẽ trả về tất cả địa điểm dựa trên tham số input, bất kể giá trị loại chính được liên kết với địa điểm. Hạn chế kết quả thành một hoặc nhiều 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 bị từ chối kèm theo lỗi INVALID_REQUEST nếu:

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

Ví dụ: để giới hạn kết quả chỉ ở 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ả trong danh sách các khu vực được chỉ định, được chỉ định dưới dạng một mảng có tối đa 15 giá trị ccTLD ("miền cấp cao nhất") gồm 2 ký tự. Nếu bạn bỏ qua tham số này, thì sẽ không có quy tắc 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.

inputOffset

Độ lệch ký tự Unicode dựa trên mốc 0 cho biết vị trí con trỏ trong input. Vị trí con trỏ có thể ảnh hưởng đến những nội dung 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 (chỉ 1 trong 2) để xác định khu vực tìm kiếm. Hãy coi locationRestriction là chỉ định khu vực mà kết quả phải nằm trong, còn locationBias là 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, tức là kết quả xung quanh vị trí đã chỉ định có thể được trả về, kể cả kết quả bên ngoài khu vực đã chỉ định.

• locationRestriction chỉ định một khu vực để tìm kiếm. Kết quả bên ngoài khu vực được chỉ định sẽ không được trả về.

Chỉ định vùng locationBias hoặc locationRestriction dưới dạng một khung hiển thị hình chữ nhật hoặc hình tròn.

Một 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,0 đến 50000,0. 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 hiển thị vĩ độ và kinh độ, được biểu thị dưới dạng 2 điểm low và high đối diện theo đường chéo. Khung nhìn được coi là một vùng khép kín, tức là bao gồm cả ranh giới của vùng đó. Phạm vi vĩ độ phải nằm trong khoảng từ -90 đến 90 độ (bao gồm cả hai giá trị này), còn phạm vi kinh độ phải nằm trong khoảng từ -180 đến 180 độ (bao gồm cả hai giá trị này):

• Nếu low = high, 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 hiển thị vượt qua đường kinh độ 180 độ).
• Nếu low.longitude = -180 độ và high.longitude= 180 độ, thì khung hiển thị sẽ bao gồm tất cả kinh độ.
• Nếu low.longitude = 180 độ và high.longitude = -180 độ, thì dải kinh độ sẽ trống.

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

Ví dụ: khung hiển thị này bao trọ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 đích đến (trả về dưới dạng distanceMeters). Nếu bạn bỏ qua giá trị này, 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 là giá trị gồm 2 ký tự ccTLD ("miền cấp cao nhất"). Hầu hết mã ccTLD đều giống với mã ISO 3166-1, ngoại trừ một số trường hợp đá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 Anh và Bắc Ireland").

Nếu bạn chỉ định mã vùng không hợp lệ, 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, trả về các doanh nghiệp cung cấp dịch vụ tại cơ sở khách hàng thuần tuý trong mảng phản hồi. Doanh nghiệp chỉ cung cấp dịch vụ tại cơ sở khách hàng 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 nhất quán về tính năng tự động hoàn thành địa điểm, bạn có thể thêm tiện ích Tự động hoàn thành địa điểm 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ý thông tin đầu vào của người dùng và hiển thị các địa điểm dự đoán cho người dùng trong khi trả về các đối tượng AutocompletePlaceSuggestion cho ứng dụng. Sau đó, bạn có thể đưa ra yêu cầu Chi tiết về địa điểm (Mới) để nhận thêm thông tin về bất kỳ địa điểm dự đoán nào.

Tương tự 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 Tự động hoàn thành địa điểm cho phép bạn sử dụng mã thông báo phiên để nhóm các yêu cầu tự động hoàn thành thành 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ã thông báo phiên, thì tiện ích sẽ tạo mã thông báo phiên Tự động hoàn thành cho bạn. Sau đó, bạn có thể lấy mã thông báo 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 chuyển đến chế độ xem toàn màn hình để chọn một địa điểm. Khi người dùng nhập, tiện ích này sẽ trả về các đề xuất về địa điểm, chẳng hạn như doanh nghiệp, địa chỉ và địa đ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 bằng địa điểm đã chọn và đóng chế độ xem toàn màn hình.

Các thông số của 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 Tự động hoàn thành địa điểm 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ó được hiển thị hay không.

onSelection

Đóng để chạy khi một địa điểm được chọn.

onError

Đó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 chế độ tuỳ chỉnh giao diện người dùng sẽ á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, có thể là 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 từng mục trong danh sách hay không.
• theme. Tham số này chỉ định một giao diện tuỳ chỉnh sẽ 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 Tự động hoàn thành tên địa điểm. Giá trị mặc định là PlacesMaterialTheme. Mọi thuộc tính giao diện không bị ghi đè sẽ sử dụng các kiểu mặc định.

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

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. Với tính năng 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.

Hạn chế về vị trí chỉ định khu vực cần tìm kiếm. Hệ thống sẽ không trả về kết quả bên ngoài khu vực được chỉ định. Ví dụ sau đây sử dụng chế độ hạn chế vị trí để giới hạn yêu cầu đối với chế độ hạn chế vị trí hình tròn có bán kính 5.000 mét, tập trung vào 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.
    }
  }
}];

Với thiên kiến về vị trí, vị trí đóng vai trò là một thiên kiến, 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 sẽ thay đổi yêu cầu trước đó để sử dụng thiên kiến 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ỏ qua, tất cả các loại sẽ được trả về.

Ví dụ sau đây chỉ định một chuỗi truy vấn là "Bóng đá" và sử dụng tham số types để hạn chế kết quả đối với 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

Khi bạn thêm tham số origin vào yêu cầu (được chỉ định là toạ độ vĩ độ và kinh độ), API sẽ thêm khoảng cách theo đườ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 dưới dạng distanceMeters.

Ví dụ này đặt điểm gốc ở trung tâm 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 Tự động hoàn thành địa điểm (đầy đủ mã)

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

Dưới đây là một số nguyên tắc chung:

• Cách nhanh nhất để phát triển giao diện người dùng hoạt động là sử dụng tiện ích Tự động hoàn thành (Mới) của Maps JavaScript API, tiện ích Tự động hoàn thành (Mới) của Places SDK cho Android hoặc tiện ích Tự động hoàn thành (Mới) của Places SDK cho iOS.
• Ngay từ đầu, hãy hiểu rõ các trường dữ liệu quan trọng của tính năng Tự động hoàn thành (Mới).
• 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 của tính năng 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 giảm hiệu suất một cách thích hợp nếu API trả về lỗi.
• Đảm bảo ứng dụng của bạn xử lý khi 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 Chi tiết về địa điểm (Mới) và Tự động hoàn thành (Mới) để chỉ trả về các 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 theo chương trình tính năng Tự động hoàn thành (Mới) để truy cập vào SKU: Giá yêu cầu Tự động hoàn thành và yêu cầu kết quả Geocoding API về địa điểm đã chọn thay vì Chi tiết về địa điểm (Mới). Mức 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ức giá theo phiên (dựa trên phiên) nếu cả hai điều kiện sau đây đều được đáp ứng:

• Nếu bạn chỉ cần 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 ít hơn một lệnh gọi Place Details (New).
• Nếu người dùng chọn một cụm từ dự đoán tự động hoàn thành trong trung bình 4 yêu cầu dự đoán Tự động hoàn thành (Mới) hoặc ít hơn, 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.

Ứng dụng của bạn có yêu cầu thông tin nào khác ngoài địa chỉ và vĩ độ/kinh độ của kết quả dự đoán đã chọn không?

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

Các nguyên tắc sau đây mô tả những 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ế về quốc gia, ưu tiên vị trí và (đối với các cách triển khai có lập trình) lựa chọn ưu tiên ngôn ngữ vào chế độ triển khai Autocomplete (New) (Tự động hoàn thành (Mới)). Không cần lựa chọn ưu tiên về ngôn ngữ đối với các tiện ích vì chúng chọn lựa chọn ưu tiên về ngôn ngữ 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ể điều chỉnh vị trí theo khung hiển thị 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ả mà họ muốn, bạn có thể sử dụng lại nội dung đầ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 chỉ muốn người dùng 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 một 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 về địa điểm (Mới). Nếu 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 dùng Geocoding API bao gồm:
  • Người dùng nhập địa chỉ của một phần trong cơ sở, chẳng hạn như địa chỉ của các căn hộ hoặc đơn vị cụ thể trong một toà nhà. Ví dụ: địa chỉ "Stroupežnického 3191/17, Praha" của Cộng hoà 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ề vị trí

Điều chỉnh kết quả cho 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ố components để lọc kết quả và chỉ cho thấy những địa điểm trong một quốc gia cụ thể.

Hạn chế về vị trí

Hạn chế kết quả ở 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 do location và tham số radius xác định bằng cách thêm tham số locationRestriction. Thao tác này hướng dẫn tính năng Autocomplete (Mới) chỉ trả về kết quả trong khu vực đó.