Place Autocomplete (新版)

選取平台： Android iOS JavaScript 網頁服務

歐洲經濟區 (EEA) 開發人員

Autocomplete (新版) 服務是 iOS API，可根據要求傳回地點建議。在要求中，指定文字搜尋字串和地理範圍，以控管搜尋區域。

Autocomplete (New) 服務可比對完整字詞和輸入內容的子字串，解析地點名稱、地址和 Plus Codes。因此，應用程式可在使用者輸入內容時傳送查詢，即時提供地點建議。

地點建議是根據指定的輸入文字字串和搜尋區域，建議商家、地址和搜尋點等地點。

舉例來說，您使用 API 時，輸入的字串包含部分使用者輸入內容「Spagh」，且搜尋範圍僅限紐約市。回應會包含與搜尋字串和搜尋區域相符的地點建議清單，例如名為「Cafe Spaghetti」的餐廳，以及地點的詳細資料。

傳回的地點建議會顯示給使用者，讓他們選取所需地點。您可以提出 Place Details (New) 要求，取得任何傳回地點建議的詳細資訊。

您可以透過兩種主要方式，將 Autocomplete (New) 功能整合到應用程式中：

透過程式輔助方式取得地點預測結果

自動完成 (新版) 要求

在 GMSPlacesClient 上呼叫方法，建立自動完成要求。您可以在 GMSAutocompleteRequest 物件中傳遞參數。回應會在 GMSAutocompletePlaceSuggestion 物件中提供自動完成建議。

必須提供 API 金鑰和query參數。您也可以加入 GMSAutocompleteSessionToken，將要求與帳單結算期建立關聯，並加入 GMSAutocompleteFilter，將要求套用至結果。

Places Swift SDK 版本

在 PlacesClient 上呼叫方法，建立自動完成要求。您可以在 AutocompleteRequest 物件中傳遞參數。回應會在 AutocompletePlaceSuggestion 物件中提供自動完成建議。

必須提供 API 金鑰和 query 參數。您也可以加入 AutocompleteSessionToken，將要求與帳單結算期建立關聯，並加入 AutocompleteFilter，將要求套用至結果。

如要進一步瞭解必要和選用參數，請參閱本文的參數部分。

Places Swift SDK

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

Swift

let token = GMSAutocompleteSessionToken()

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

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

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

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

Objective-C

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

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

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

Autocomplete (新版) 回應

自動完成功能最多會傳回五個 GMSAutocompleteSuggestion 例項的陣列。陣列包含：

  • placeID
  • types：適用於這個地點的類型。
  • distanceMeters：與起點的距離。
  • attributedFullText：建議的完整文字，方便使用者閱讀。
  • attributedPrimaryText：建議的主要文字，方便使用者閱讀。
  • attributedSecondaryText：建議的易讀次要文字。
  • structuredFormat：特定名稱和消歧文字，例如城市或區域。

必要參數

查詢

要搜尋的文字字串。指定完整字詞和子字串、地點名稱、地址和 Plus Codes。Autocomplete (New) 服務會根據這個字串傳回候選相符項目，並依據觀察到的關聯性排序結果。

選用參數

sessionToken

工作階段符記是使用者產生的字串，可將透過小工具和程式輔助方式發出的 Autocomplete (New) 呼叫，一併追蹤為「工作階段」。自動完成 (新版) 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。

您可以公開 Places Autocomplete 工作階段符記，將其傳遞至不屬於 Places SDK for iOS 的其他服務，例如地址驗證：

Places Swift SDK

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

Objective-C

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

詳情請參閱「工作階段權杖」。

選用的 AutocompleteFilter 參數

類型

一個地點只能有一個主要類型，且必須來自表 A 或表 B。舉例來說，主要類型可能是 mexican_restaurant 或 steak_house。

根據預設，API 會根據 input 參數傳回所有地點，無論與地點相關聯的主要類型值為何。傳送 types 參數，將結果限制為特定主要類型。

使用這個參數，從表 A 或表 B 中指定最多五個類型值。地點必須符合其中一個指定的主要類型值，才會納入回應。

如有下列情況，要求就會遭拒，並傳回 INVALID_REQUEST 錯誤：

  • 指定超過五個類型。
  • 指定任何無法辨識的類型。

舉例來說，如要將結果限制為運動用品店，請在 AutocompleteFilter 中指定該類型：

Places Swift SDK

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

Swift

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

Objective-C

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

國家/地區

只納入指定區域的結果，最多可指定 15 個 ccTLD (「頂層網域」) 雙字元值，並以陣列形式指定。如果省略這項設定，系統不會對回覆內容套用任何限制。 舉例來說，如要將地區限制為德國和法國，請執行下列操作：

Places Swift SDK

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

Swift

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

Objective-C

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

如果同時指定 locationRestriction 和 countries，結果會位於這兩項設定的交集區域。

inputOffset

以零為基準的 Unicode 字元位移值，表示 input 中的游標位置。游標位置可能會影響系統傳回的預測結果。如果為空白，則預設為 input 的長度。

locationBias 或 locationRestriction

您可以指定 locationBias 或 locationRestriction (但不能同時指定兩者)，定義搜尋區域。locationRestriction 是指結果必須位於的區域，locationBias 則是結果必須靠近的區域，但可位於該區域外。

  • locationBias 會指定要搜尋的區域。這個位置會做為偏差值，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。

  • locationRestriction 會指定要搜尋的區域。系統不會傳回指定區域外的結果。

將 locationBias 或 locationRestriction 區域指定為矩形檢視區塊或圓形。

圓形是由中心點和半徑 (以公尺為單位) 定義。半徑必須介於 0.0 至 50000.0 之間 (含首尾)。預設值為 0.0。如果是 locationRestriction，半徑必須設為大於 0.0 的值。否則要求不會傳回任何結果。

例如：

Places Swift SDK

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)

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

矩形是經緯度可視區域，以兩個對角low和high點表示。可視區域視為封閉區域， 也就是說，可視區域包含邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾)，經度範圍必須介於 -180 到 180 度之間 (含首尾)：

  • 如果 low = high，可視區域就是該單一點。
  • 如果 low.longitude > high.longitude，經度範圍會反轉 (可視區會跨越 180 度的經度線)。
  • 如果 low.longitude = -180 度且 high.longitude= 180 度，則可視區會包含所有經度。
  • 如果 low.longitude = 180 度且 high.longitude = -180 度，經度範圍會空白。

low 和 high 都必須填入值，且代表的方塊不得為空白。如果檢視區塊為空白，就會發生錯誤。

舉例來說，這個可視區域完全涵蓋紐約市：

Places Swift SDK

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)

Swift

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

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

Objective-C

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

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

origin

計算與目的地直線距離的起點 (以 distanceMeters 形式傳回)。如果省略這個值，系統就不會傳回直線距離。必須指定為經緯度座標：

Places Swift SDK

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

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

regionCode

用來設定回應格式的區域代碼，指定為 ccTLD (「頂層網域」) 雙字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(即 .co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體)。

如果指定無效的地區代碼，API 會傳回 INVALID_ARGUMENT 錯誤。根據適用法律，這項參數可能會影響結果。

shouldIncludePureServiceAreaBusinesses

如果是 true，則會在回應陣列中傳回純區域服務商家。純區域服務商家是指直接為顧客提供送貨或到府服務，但不在商家地址提供服務的商家。

例如：

Places Swift SDK

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

Swift

let filter = AutocompleteFilter()
filter.shouldIncludePureServiceAreaBusinesses = true

Objective-C

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

新增 Place Autocomplete 小工具

如要更輕鬆地提供一致的 Place Autocomplete 體驗，您可以將 Place Autocomplete 小工具新增至應用程式。這個小工具提供專用的全螢幕介面，可處理使用者輸入內容、向使用者顯示地點預測結果，並將 AutocompletePlaceSuggestion 物件傳回應用程式。接著，您可以發出 Place Details (New) 要求，取得任何地點預測結果的額外資訊。

地點自動完成小工具

與透過程式輔助方式取得地點預測結果類似，Place Autocomplete 小工具可讓您使用工作階段符記，將自動完成要求分組為工作階段，以用於計費。您可以呼叫 AutocompleteSessionToken() 傳遞工作階段權杖。

如果您未提供工作階段符記，小工具會為您建立 Autocomplete 工作階段符記，然後可從 onSelection 回呼取得。如要進一步瞭解如何使用工作階段符記，請參閱「關於工作階段符記」。

如果 show 繫結值設為 true，系統會將使用者帶往全螢幕檢視畫面，讓他們選取地點。使用者輸入內容時，小工具會傳回地點建議，例如商家、地址和搜尋點。使用者選取地點時，小工具會使用所選地點呼叫 onSelection 處理常式，並關閉全螢幕檢視畫面。

Place Autocomplete 小工具參數

除了可透過程式輔助使用的參數，Place Autocomplete 小工具也提供下列參數。

顯示

show 指定是否顯示小工具。

onSelection

選取地點時要執行的關閉作業。

onError

發生錯誤時要執行的閉包。如果發生錯誤，系統會傳遞 PlacesError。

自訂內容和主題

AutocompleteUICustomization 參數會指定要套用至小工具的 UI 自訂項目。自訂選項包括：

  • AutocompleteListDensity。 這個參數可讓您選擇建議清單的密度，可以是 multiLine 或 twoLine。
  • AutocompleteUIIcon。這個參數可讓您選擇是否顯示每個清單項目的預設圖示。
  • theme。 這個參數可指定自訂主題，覆寫任何預設樣式屬性。您可以自訂 Place Autocomplete 元件的顏色、字體、間距、邊框和圓角。預設值為 PlacesMaterialTheme。未覆寫的主題屬性會使用預設樣式。

查看完整程式碼範例。

Autocomplete (新版) 範例

使用 locationRestriction 和 locationBias

Autocomplete (新版) 預設會使用 IP 偏誤來控管搜尋區域。使用 IP 偏誤時，API 會使用裝置的 IP 位址來偏誤結果。您可以選擇使用 locationRestriction 或 locationBias (但不能同時使用)，指定要搜尋的區域。

地點限制會指定搜尋區域。系統不會傳回指定區域外的結果。以下範例使用位置限制，將要求限制在以舊金山為中心、半徑 5000 公尺的圓形位置限制內：

Places Swift SDK

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

Swift

let token = GMSAutocompleteSessionToken()

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

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

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

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

Objective-C

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

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

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

位置資訊偏向設定會將位置資訊做為偏向設定，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。下一個範例會變更先前的要求，改為使用位置偏誤：

Places Swift SDK

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

Swift

let token = GMSAutocompleteSessionToken()

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

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

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

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

Objective-C

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

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

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

用途類型

使用 types 參數，將要求結果限制為特定類型，如表 A 和表 B 所列。最多可以指定五個值的陣列。如果省略，系統會傳回所有類型。

以下範例指定「Soccer」的查詢字串，並使用 types 參數將結果限制為 "sporting_goods_store" 類型的場所：

Places Swift SDK

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

Swift

let token = GMSAutocompleteSessionToken()

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

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

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

Objective-C

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

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

使用來源

在要求中加入 origin 參數 (指定為經緯度座標) 時，API 會在回應中加入從起點到目的地的直線距離。回應會以 distanceMeters 形式傳回距離。

這個範例將原點設為舊金山中心：

Places Swift SDK

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

Swift

let token = GMSAutocompleteSessionToken()

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

let filter = GMSAutocompleteFilter()

filter.origin =  origin

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

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

Objective-C

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

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

自訂內容和主題

Swift

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

新增 Place Autocomplete 小工具 (完整程式碼)

Places Swift SDK

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

Autocomplete (新版) 最佳化

本節將說明最佳做法，協助您充分運用 Autocomplete (New) 服務。

以下列出幾項一般準則：

  • 如要開發有效的使用者介面，最快的方法就是使用 Maps JavaScript API Autocomplete (New) 小工具、 Places SDK for Android Autocomplete (New) 小工具， 或 Places SDK for iOS Autocomplete (New) 小工具。
  • 從一開始就瞭解 Autocomplete (新版) 的必要資料欄位。
  • 「位置自訂調整」和「位置限制」為自選欄位，但可能會對自動完成效能產生重大影響。
  • 使用錯誤處理機制，可以減輕 API 傳回錯誤時對應用程式效能造成的影響。
  • 確保應用程式能處理未選取任何項目的情況，以便使用者繼續操作。

費用最佳化最佳做法

基本費用最佳化

為了讓 Autocomplete (New) 服務費用發揮最大效益，請使用 Place Details (New) 和 Autocomplete (New) 小工具中的欄位遮罩，只傳回所需的 Autocomplete (New) 資料欄位。

進階費用最佳化

建議您透過程式輔助方式導入 Autocomplete (New)，採用SKU：Autocomplete Request 計價，並要求已選地點 (而非 Place Details (New)) 的相關 Geocoding API 結果。如果同時符合以下兩項條件，搭配 Geocoding API 使用「按要求」計價會比使用「按工作階段」(以工作階段為準) 計價更具成本效益：

  • 如果您只需要針對使用者選取的地點取得經緯度或地址，透過 Geocoding API 擷取這項資訊，支付的費用會比使用 Place Details (New) 呼叫更低。
  • 如果使用者在平均四次以內的自動預測結果要求選取了自動預測結果，則「按要求」計價可能會比「按工作階段」計價更符合成本效益。
如要瞭解如何選取符合需求的 Autocomplete (New) 導入方式，請回答下列問題，並選取對應的分頁標籤。

除了所選預測結果的地址和經緯度，應用程式是否需要任何其他資訊？

是，需要更多詳細資料

搭配 Place Details (新版) 使用以工作階段為準的 Autocomplete (新版)。
由於應用程式需要地點詳細資料 (新版)，例如地點名稱、商家狀態或營業時間，因此實作 Autocomplete (新版) 時，應使用JavaScript、Android 或 iOS 小工具中內建的每個工作階段工作階段符記，以及適用的 Places SKU，具體取決於您要求哪些地點資料欄位。1

透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Autocomplete (新版) 要求和 Place Details (新版) 要求。請務必指定 fields 參數，確保只要求所需的 Autocomplete (New) 資料欄位 。

透過程式輔助方式導入
搭配 Autocomplete (New) 要求使用工作階段符記。要求所選預測結果的相關 Place Details (新版) 時，請加入下列參數：

  1. Autocomplete (新版) 回應中的地點 ID
  2. Autocomplete (New) 要求中使用的工作階段符記
  3. 指定所需 Autocomplete (新版) 資料欄位的 fields 參數

否，只需要地址和位置資訊

對您的應用程式而言，Geocoding API 可能比 Place Details (New) 更符合成本效益，視 Autocomplete (New) 使用效能而定。每個應用程式的自動完成 (新版) 效率各不相同，可能取決於使用者輸入的內容、使用應用程式的位置，以及是否採用效能最佳化最佳做法。

為了找出以下問題的解答，請分析使用者在應用程式中選取 Autocomplete (New) 預測結果前，平均輸入的字元數量。

使用者是否會在平均四次以內的要求中選取 Autocomplete (New) 預測結果？

是

透過程式輔助方式導入 Autocomplete (New)，但不使用工作階段符記，並針對已選取的地點預測結果呼叫 Geocoding API。
Geocoding API 提供地址和經緯度座標。 提出四次自動完成要求，加上所選地點預測結果的相關 Geocoding API 呼叫，總費用會低於自動完成 (新版) 功能「按工作階段」計價的每個工作階段費用1。

建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。

否

搭配 Place Details (新版) 使用以工作階段為準的 Autocomplete (新版)。
由於您預期在使用者選取 Autocomplete (新版) 預測結果前，平均會發出超過「按工作階段」計價費用的要求，因此 Autocomplete (新版) 的實作應針對 Autocomplete (新版) 要求和相關聯的 Place Details (新版) 要求，使用按工作階段計價的工作階段符記。 1

透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Autocomplete (新版) 要求和 Place Details (新版) 要求。請務必指定 fields 參數，確保只要求所需的欄位。

透過程式輔助方式導入
搭配 Autocomplete (New) 要求使用工作階段符記。要求所選預測結果的相關 Place Details (新版) 時，請加入下列參數：

  1. Autocomplete (新版) 回應中的地點 ID
  2. Autocomplete (New) 要求中使用的工作階段符記
  3. 指定地址和幾何圖形等欄位的 fields 參數

考慮延後 Autocomplete (New) 要求
您可以運用一些策略，例如將 Autocomplete (New) 要求延後到使用者輸入三或四個字元時再開始，藉此減少應用程式提出要求數量。舉例來說，如果使用者輸入第三個字元後，您為每個字元提出自動完成 (新版) 要求，則使用者輸入七個字元並選取預測結果後，您提出一次 Geocoding API 要求，總費用會是 4 次自動完成 (新版) 要求 + Geocoding。1

如果延後要求可以讓平均程式輔助要求少於四次，您可以按照使用 Geocoding API 提高 Autocomplete (New) 效能的指南操作。請注意，如果使用者希望每輸入一個字就能看到預測結果，可能就會將延後要求視為時間上的延遲。

建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。

  1. 如要瞭解費用，請參閱 Google 地圖平台價目表。

效能最佳做法

以下準則說明如何將 Autocomplete (新版) 效能最佳化：

  • 針對導入的 Autocomplete (New) 加入國家/地區限制、位置自訂調整和 (適用於程式輔助導入) 語言偏好設定。小工具會從使用者的瀏覽器或行動裝置選擇語言偏好設定，因此不需要設定語言偏好。
  • 如果 Autocomplete (New) 附帶地圖，您就可以根據地圖可視區域進行位置自訂調整。
  • 如果使用者沒有選擇任何自動完成 (新版) 預測結果 (通常是因為這些預測結果並非他們想要的地址)，您可以重複使用原始使用者輸入內容，嘗試取得更相關的結果：
    • 如果您預期使用者只會輸入地址資訊，請在 Geocoding API 呼叫中重複使用原始使用者輸入內容。
    • 如果您預期使用者會依名稱或地址查詢某個地點，請使用 Place Details (New) 要求。如果希望將結果範圍限制在特定區域，請使用位置自訂調整。
    適合改回使用 Geocoding API 的其他情況如下：
    • 使用者輸入子處所地址，例如建築物內特定單位或公寓的地址。例如，捷克地址「Stroupežnického 3191/17, Praha」在 Autocomplete (新版) 中會產生不完整的預測結果。
    • 使用者輸入的地址含有路段前置字元，例如紐約的「23-30 29th St, Queens」或夏威夷考艾島的「47-380 Kamehameha Hwy, Kaneohe」。

位置偏好設定

傳遞 location 參數和 radius 參數，針對特定區域調整結果。這會指示 Autocomplete (New) 優先顯示定義區域內的結果。不過，系統還是有可能會顯示定義區域外的結果。您可以使用 components 參數篩選結果，只顯示特定國家/地區內的地點。

限制位置

傳送 locationRestriction 參數，將結果限制在特定區域。

您也可以新增 locationRestriction 參數，將結果限制在 location 和 radius 參數定義的區域內。這會指示 Autocomplete (New) 只傳回該區域內的結果。