Place Autocomplete (新版)

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

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

「地點建議」是商家、地址和搜尋點等地點，具體取決於指定的輸入文字字串和搜尋區域。

舉例來說，您可以使用做為輸入字串來呼叫 API，該字串包含部分使用者輸入內容「Sicilian piz」，且搜尋區域僅限於加州舊金山。回應隨後會包含一份符合搜尋字串和搜尋區域的地點建議清單 (例如名為「西西里披薩廚房」的餐廳)，以及地點的詳細資料。

傳回的地點建議是設計給使用者，讓他們選取想去的地點。您可以提出 Place Details (新版) 要求，取得任何傳回地點建議的詳細資訊。

注意： 您必須啟用原始自動完成 API，才能使用小工具功能。舊版 API 和新版 API 可以同時啟用。詳情請參閱 Places Autocomplete (新版) 遷移指南。

自動完成 (新版) 要求

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

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

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

Swift

let token = GMSAutocompleteSessionToken()

let northEastBounds = CLLocationCoordinate2DMake(37.388162, -122.088137)
let southWestBounds = CLLocationCoordinate2DMake(37.395804, -122.077023)

let filter = GMSAutocompleteFilter()
filter.types = [kGMSPlaceTypeRestaurant]
filter.locationBias = GMSPlaceRectangularLocationOption(northEastBounds, southWestBounds)
    
let request = GMSAutocompleteRequest(query:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

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，則 API 預設會使用 IP 自訂調整。透過 IP 自訂調整，API 會使用裝置的 IP 位址調整結果。

• 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.477398, -74.259087)
let low = CLLocationCoordinate2DMake(40.921628, -73.700051)

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:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
  })

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:"Sicilian piz")
request.filter = filter
request.sessionToken = token
GMSPlacesClient.shared().fetchAutocompleteSuggestions(from: request, callback: { results, error in
  // Handle response
})

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
  // Handle response
})

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
  // Handle response
})

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 標誌與作者資訊」。