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

Place Autocomplete (新版)

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

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