Autocomplete (新版) 服務為 iOS API,可因應要求傳回地點建議。在要求中,指定用來控制搜尋區域的文字搜尋字串和地理邊界。
Autocomplete (新版) 服務可比對輸入內容的完整字詞和子字串,解析地點名稱、地址和 Plus Codes。因此,應用程式可在使用者輸入內容時傳送查詢,即時提供地點建議。
「地點建議」是商家、地址和搜尋點等地點,具體取決於指定的輸入文字字串和搜尋區域。
舉例來說,您可以使用做為輸入字串來呼叫 API,該字串包含部分使用者輸入內容「Spagh」,且搜尋區域僅限於紐約市。接著,回應中會包含符合搜尋字串和搜尋區域的地點建議清單 (例如名為「Cafe Spaghetti」的餐廳),以及該地點的詳細資料。
傳回的地點建議是設計給使用者,讓他們選取想去的地點。您可以提出 Place Details (新版) 要求,取得任何傳回地點建議的詳細資訊。
自動完成 (新版) 要求
對 GMSPlaceClient
呼叫方法,建立 Autocomplete 要求。您可以在 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. } } }];
GooglePlacesSwift
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. }
自動完成 (新版) 回應
Autocomplete 會傳回最多包含五個 GMSAutocompleteSuggestion
執行個體的陣列。陣列包含:
placeID
types
:此地點適用的類型。distanceMeters
:與起點的距離。attributedFullText
:使用者可理解的建議文字全文。attributedPrimaryText
:使用者可理解的建議主要文字。attributedSecondaryText
:使用者可理解的建議次要文字。structuredFormat
:特定名稱及能夠清楚辨識文字,例如城市或地區。
必要參數
項查詢
要搜尋的文字字串。指定完整字詞和子字串、地點名稱、地址和 plus code。Autocomplete (新版) 服務會根據這個字串傳回候選相符項目,並會依據觀察到的關聯性排序結果。
自選參數
種類
地點在與其相關聯的表 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" ];
GooglePlacesSwift
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);
GooglePlacesSwift
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);
GooglePlacesSwift
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];
GooglePlacesSwift
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 (新) 呼叫視為「工作階段」來追蹤。Autocomplete (新版) 會使用工作階段符記,將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段,以用於計費。詳情請參閱「工作階段符記」。
自動完成 (新版) 範例
使用 locationRestriction 和 locationBias
自動完成 (新版) 預設會使用 IP 自訂調整來控制搜尋區域。透過 IP 自訂調整,API 會使用裝置的 IP 位址自訂調整結果。您可以選擇使用 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. } } }];
GooglePlacesSwift
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. } } }];
GooglePlacesSwift
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. } } }];
GooglePlacesSwift
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. } } }];
GooglePlacesSwift
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. }
出處
即使沒有地圖,也能使用 Autocomplete (新版)。如要顯示地圖,則必須使用 Google 地圖。如果要在沒有地圖的情況下顯示 Autocomplete (新版) 服務的建議,您必須加入顯示在搜尋欄位/結果中的 Google 標誌。詳情請參閱「顯示 Google 標誌與作者資訊」。