Place Autocomplete (新版)

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

Autocomplete (New) 服務是 iOS API，可根據要求傳回地點建議。在要求中指定文字搜尋字串和地理邊界，以控制搜尋範圍。

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

地點建議是根據指定的輸入文字字串和搜尋區域，顯示商家、地址和景點等地點。

舉例來說，您可以使用包含部分使用者輸入內容「Spagh」的字串做為輸入內容，並將搜尋範圍限制在紐約市，來呼叫 API。回應內容會包含與搜尋字串和搜尋區域相符的地點建議清單，例如名為「Cafe Spaghetti」的餐廳，以及該地點的詳細資料。

系統會將傳回的地點建議呈現給使用者，方便他們選取所需地點。您可以提出 Place Details (New) 要求，進一步瞭解任何傳回的地點建議。

自動完成 (新) 要求

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

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

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

自動完成 (新) 回覆

自動完成功能會傳回最多五個 GMSAutocompleteSuggestion 例項的陣列。這個陣列包含：

  • placeID
  • types：適用於此地點的類型。
  • distanceMeters：距離原點的距離。
  • attributedFullText：建議內容的完整人類可讀文字。
  • attributedPrimaryText：建議內容的可讀主要文字。
  • attributedSecondaryText：建議內容的可讀人類語言次要文字。
  • structuredFormat：具體名稱和不含歧義的文字，例如城市或地區。

必要參數

查詢

要搜尋的文字字串。指定完整字詞和子字串、地點名稱、地址和加號代碼。Autocomplete (New) 服務會根據這個字串傳回候選相符項目，並依據所認知的相符程度排序結果。

選用參數

類型

地點只能有一個單一主要類型，來自與其相關聯的 Table A 或 Table B 類型。例如，主要類型可能是 mexican_restaurant 或 steak_house。

根據預設，API 會根據 input 參數傳回所有地點，不論與地點相關聯的主要類型值為何。傳遞 types 參數，限制結果為特定主要類型或主要類型。

您可以使用這個參數，指定 Table A 或 Table B 中的五個類型值。地點必須符合指定的主要類型值之一，才能納入回應。

如果發生下列情況，系統會拒絕要求並顯示 INVALID_REQUEST 錯誤：

  • 指定的類型超過五個。
  • 指定任何未知的類型。

國家/地區

只包含指定區域清單中的結果，並以陣列的形式指定，最多可包含 15 個 ccTLD (「頂層網域」) 兩個字元的值。如果省略，系統就不會對回應套用任何限制。舉例來說，如要將地區限制為德國和法國：

Swift

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

Objective-C

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

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

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

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

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

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

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

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

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」(技術上是「The United Kingdom of Great Britain and Northern Ireland」實體)。

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

sessionToken

工作階段權杖是使用者產生的字串，可追蹤「工作階段」的自動完成 (新) 呼叫。自動完成 (新版) 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段分組為個別工作階段，以便計費。詳情請參閱「工作階段符記」。

自動完成 (新) 範例

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

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

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

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

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 所列的特定類型。您可以指定最多五個值的陣列。如果省略，則會傳回所有類型。

以下範例會指定「足球」的查詢字串，並使用 types 參數將結果限制為 "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.
    }
  }
}];

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

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

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

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 地圖。如要顯示自動完成 (新版) 服務的建議，但不顯示地圖，則必須在搜尋欄位/結果中內嵌 Google 標誌。詳情請參閱「顯示 Google 標誌和出處標記」。