本頁面由 Cloud Translation API 翻譯而成。

Place Autocomplete (新版)

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

Autocomplete (新版) 服務是 iOS API，會傳回地點建議以回應要求。在要求中指定文字搜尋字串和控制搜尋區域的地理邊界。

自動完成 (新版) 服務可完全比對輸入的字詞和子字串，解析地點名稱、地址和 + 代碼。因此，應用程式能以使用者的身分傳送查詢以便即時提供地點建議。

地點建議是指地點，例如商家、地址和搜尋點。興趣 (以指定輸入文字字串和搜尋區域為準)。

舉例來說，您可以使用輸入字串來呼叫 API，該字串包含部分使用者輸入的字詞「Spagh」，並將搜尋區域限定為紐約市。回應隨後會包含符合搜尋條件的地點建議清單字串和搜尋區域，例如名為「巴西義大利麵」的餐廳以及該地點的詳細資訊。

傳回的地點建議是為了呈現給使用者，讓他們選取想去的地點您可以製作 Place Details (新增) 要求更多任何傳回地點建議的相關資訊。

自動完成 (新版) 要求

呼叫上的方法，建立 Autocomplete 要求 GMSPlaceClient。您可以在 GMSAutocompleteRequest敬上物件。回應會在 GMSAutocompletePlaceSuggestion敬上物件。

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

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

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

Places Swift SDK for iOS (預先發布版)

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

自動完成 (新版) 回應

自動完成功能會傳回最多 5 個陣列 GMSAutocompleteSuggestion 執行個體。陣列包含：

placeID
types：此地點適用的類型。
distanceMeters：與起點的距離。
attributedFullText：使用者可理解的建議文字全文。
attributedPrimaryText：使用者可理解的建議主要文字。
attributedSecondaryText：建議內容的輔助文字，方便使用者閱讀。
structuredFormat：特定名稱及能夠清楚辨識的文字，例如城市或區域。

必要參數

查詢

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

選用參數

類型

地點只能包含「表格」類型的單一主要類型 A或表格 B。舉例來說，主要類型可能是 mexican_restaurant 或 steak_house。

根據預設，API 會根據 input 參數傳回所有地點。不論地點的主要類型值為何。限制結果可轉換成主要類型或主要類型，方法是將 types 參數。

使用這個參數，最多可指定表 A 或表 B 中的五種類型值。地點必須相符要包含在回應中的其中一個指定主要類型值。

如有下列情況，要求遭到拒絕，並顯示 INVALID_REQUEST 錯誤：

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

國家/地區

只加入指定區域清單中的結果，以陣列的形式指定最多 15 個 ccTLD (「頂層」網域」) 兩個字元的值如果省略，則系統不會對回應套用任何限制。舉例來說，如要將區域範圍限制在德國和法國，請按照下列步驟操作：

Swift

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

Objective-C

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

Places Swift SDK for iOS (預先發布版)

let filter = AutocompleteFilter(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 的值。否則，要求不會傳回任何結果。

例如：

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

Places Swift SDK for iOS (預先發布版)

let center = CLLocationCoordinate2DMake(40.477398, -74.259087)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)

矩形是經緯度可視區域，以兩對角線表示 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 都必須填入，且代表方塊不得並將空無一物。空白的可視區域會導致錯誤。

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

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

Places Swift SDK for iOS (預先發布版)

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

let filter = AutocompleteFilter(coordinateRegionBias: bias)

起源

計算與起點之間的直線距離目的地 (傳回 distanceMeters)。省略這個值時不會傳回直線距離。指定為緯度和經度座標：

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

Places Swift SDK for iOS (預先發布版)

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

regionCode

用於設定回應格式的區碼，以 ccTLD (「頂層」) 網域」) 兩個字元的值多數 ccTLD 代碼與 ISO 3166-1 代碼相同，一些特殊的例外狀況舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼是「gb」(技術上代表「大不列顛與北愛爾蘭聯合王國」實體)。

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

sessionToken

工作階段符記是使用者產生的字串，可追蹤 Autocomplete (New) 呼叫的「工作階段」。自動完成 (新版) 會使用工作階段符記，將查詢和選取階段，將使用者自動完成搜尋劃分為獨立的工作階段做為帳單用途詳情請參閱工作階段符記

自動完成 (新版) 範例

使用 locationRestriction 和 locationBias

自動完成功能 (新版) 預設採用 IP 自訂調整為用於控制搜尋區域透過 IP 自訂調整，API 會使用調整結果。您可以選擇使用 locationRestriction 或 locationBias (非兩者) 可指定搜尋區域

地點限制可用來指定要搜尋的區域。指定範圍以外的結果。下例示範如何使用位置限制請求請求以半徑為 5000 公尺的圓形地點限制在舊金山：

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 for iOS (預先發布版)

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

Places Swift SDK for iOS (預先發布版)

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

使用類型

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

以下範例會指定「足球」這個查詢字串並使用類型參數，將結果限制為類型建築物的結果 "sporting_goods_store"：

Swift

let token = GMSAutocompleteSessionToken()

let filter = GMSAutocompleteFilter()
filter.types = ["sporting_goods_store"]
    
let request = GMSAutocompleteRequest(query:"Soccer")
request.filter = filter
request.sessionToken = token

GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { ( results, error ) in
      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.
    }
  }
}];

Places Swift SDK for iOS (預先發布版)

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

使用來源

在要求中加入 origin 參數時，指定經緯度座標，API 會包含直線距離傳送至回應中的目的地。回應會傳回距離 distanceMeters。

以下範例將起點設為舊金山的中心：

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

Places Swift SDK for iOS (預先發布版)

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

歸因

即使沒有地圖。如要顯示地圖，則必須使用 Google 地圖。螢幕分享來自 Autocomplete (新版) 服務的建議不含地圖時，您必須加入顯示在搜尋結果旁的 Google 標誌 field/results.詳情請參閱顯示 Google 標誌及出處。