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。 自動完成 (新版) 服務會傳回候選相符項目 然後根據感知的關聯性排列結果。
選用參數
類型
地點只能包含「表格」類型的單一主要類型
A或表格
B。
舉例來說,主要類型可能是 mexican_restaurant
或 steak_house
。
根據預設,API 會根據 input
參數傳回所有地點。
不論地點的主要類型值為何。限制結果
可轉換成主要類型或主要類型,方法是將
types
參數。
使用這個參數從 Table 表指定最多五個類型值 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
工作階段符記是使用者產生的字串,可追蹤 自動完成 (新) 呼叫做為「工作階段」。 自動完成 (新版) 會使用工作階段符記,將 查詢和選取階段,將使用者自動完成搜尋劃分為獨立的工作階段 做為帳單用途詳情請參閱工作階段 符記
自動完成 (新版) 範例
使用 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 標誌及 出處。