Places Autocomplete Service

AutocompleteService class

google.maps.places.AutocompleteService class

已淘汰：自 2025 年 3 月 1 日起，新客戶無法使用 google.maps.places.AutocompleteService。請改用「AutocompleteSuggestion」。目前 google.maps.places.AutocompleteService 尚未排定停用時間，但建議使用 AutocompleteSuggestion，而非 google.maps.places.AutocompleteService。google.maps.places.AutocompleteService 仍會修正重大回歸錯誤，但不會處理現有錯誤。如要停止支援，我們會在至少 12 個月前發出通知。如需更多詳細資料，請參閱 https://developers.google.com/maps/legacy，如需遷移指南，請參閱 https://developers.google.com/maps/documentation/javascript/places-migration-overview。

包含與擷取自動完成預測結果相關的方法。

撥打 const {AutocompleteService} = await google.maps.importLibrary("places") 即可存取。
請參閱「Maps JavaScript API 中的程式庫」。

建構函式
AutocompleteService	AutocompleteService() 參數：無 建立 AutocompleteService 的新例項。

方法
getPlacePredictions	getPlacePredictions(request[, callback]) 參數：  request：AutocompletionRequest自動完成要求。 callback：function(Array<AutocompletePrediction> optional, PlacesServiceStatus): void optional回呼，接受 AutocompletePrediction 物件陣列和 PlacesServiceStatus 值做為引數。 傳回值：  Promise<AutocompleteResponse> 根據提供的自動完成要求，擷取地點自動完成預測結果。
getQueryPredictions	getQueryPredictions(request, callback) 參數：  request：QueryAutocompletionRequest查詢自動完成要求。 callback：function(Array<QueryAutocompletePrediction> optional, PlacesServiceStatus): void回呼，接受 QueryAutocompletePrediction 物件陣列和 PlacesServiceStatus 值做為引數。 傳回值：無 根據提供的查詢自動完成要求，擷取查詢自動完成預測結果。

AutocompletionRequest 介面

google.maps.places.AutocompletionRequest 介面

要傳送至 AutocompleteService.getPlacePredictions 的自動完成要求。

屬性
input	類型：  string 使用者輸入的字串。
bounds optional	已淘汰： bounds 已於 2023 年 5 月淘汰，請改用 AutocompletionRequest.locationBias 和 AutocompletionRequest.locationRestriction。 類型：  LatLngBounds|LatLngBoundsLiteral optional 預測偏差的界限。預測結果會優先 (但不限於) 顯示指定 bounds。如果設定 bounds，系統會忽略 location 和 radius。
componentRestrictions optional	類型：  ComponentRestrictions optional 元件限制。元件限制用於將預測結果限制在父項元件內。例如國家/地區。
language optional	類型：  string optional 盡可能提供語言 ID，指出應以哪種語言傳回結果。系統可能會優先顯示所選語言的結果，但建議不限於該語言。請參閱支援語言清單。
location optional	已淘汰： location 已於 2023 年 5 月淘汰，請改用 AutocompletionRequest.locationBias 和 AutocompletionRequest.locationRestriction。 類型：  LatLng optional 用於預測偏誤的位置。預測結果會偏向指定的 location 和 radius。或者，您也可以使用 bounds。
locationBias optional	類型：  LocationBias optional 搜尋地點時使用的軟性邊界或提示。
locationRestriction optional	類型：  LocationRestriction optional 用來限制搜尋結果的範圍。
offset optional	類型：  number optional 服務在輸入字詞中使用文字進行預測的字元位置 (輸入欄位中的游標位置)。
origin optional	類型：  LatLng|LatLngLiteral optional 計算 AutocompletePrediction.distance_meters 的位置。
radius optional	已淘汰： radius 已於 2023 年 5 月淘汰，請改用 AutocompletionRequest.locationBias 和 AutocompletionRequest.locationRestriction。 類型：  number optional 用於預測偏差的區域半徑。radius 以公尺為單位，且一律須附上 location 屬性。或者，您也可以使用 bounds。
region optional	類型：  string optional 用於格式化和篩選結果的區域代碼。這不會將建議限制在該國家/地區。區碼接受 ccTLD (「頂層網域」) 的兩位字元值。多數 ccTLD 代碼與 ISO 3166-1 代碼相同，只有少數例外。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體)。
sessionToken optional	類型：  AutocompleteSessionToken optional 用於將個別要求組合為工作階段的不重複參照。
types optional	類型：  Array<string> optional 要傳回的預測類型。如要瞭解支援的類型，請參閱 開發人員指南。如果未指定類型，系統會傳回所有類型。

AutocompleteResponse 介面

google.maps.places.AutocompleteResponse 介面

呼叫 AutocompleteService.getPlacePredictions 後傳回的 Autocomplete 回應，其中包含 AutocompletePrediction 清單。

屬性
predictions	類型：  Array<AutocompletePrediction> AutocompletePrediction 清單。

QueryAutocompletionRequest interface

google.maps.places.QueryAutocompletionRequest 介面

要傳送至 QueryAutocompleteService 的 QueryAutocompletion 要求。

屬性
input	類型：  string 使用者輸入的字串。
bounds optional	類型：  LatLngBounds|LatLngBoundsLiteral optional 預測偏差的界限。預測結果會優先 (但不限於) 顯示指定 bounds。如果設定 bounds，系統會忽略 location 和 radius。
location optional	類型：  LatLng optional 用於預測偏誤的位置。預測結果會偏向指定的 location 和 radius。或者，您也可以使用 bounds。
offset optional	類型：  number optional 服務在輸入字詞中使用文字進行預測的字元位置 (輸入欄位中的游標位置)。
radius optional	類型：  number optional 用於預測偏差的區域半徑。radius 以公尺為單位，且一律須附上 location 屬性。或者，您也可以使用 bounds。

ComponentRestrictions interface

google.maps.places.ComponentRestrictions 介面

定義可與自動完成服務搭配使用的元件限制。

屬性
country optional	類型：  string|Array<string> optional 將預測結果範圍限制在指定國家/地區內 (ISO 3166-1 Alpha-2 國家/地區代碼，不區分大小寫)。例如 'us'、'br' 或 'au'。您可以提供單一國家/地區代碼字串，或最多五個國家/地區代碼字串的陣列。

AutocompletePrediction 介面

google.maps.places.AutocompletePrediction 介面

代表單一自動完成預測結果。

屬性
description	類型：  string 這是地點服務建議的查詢，未經過格式化。
matched_substrings	類型：  Array<PredictionSubstring> 地點說明中的一組子字串，與使用者輸入內容中的元素相符，適合用於醒目顯示這些子字串。每個子字串都會以位移和長度 (以 Unicode 字元表示) 識別。
place_id	類型：  string 地點 ID，可用於透過地點詳細資料服務擷取這個地點的詳細資料 (請參閱 PlacesService.getDetails)。
structured_formatting	類型：  StructuredFormatting 地點說明的結構化資訊，分為主要文字和次要文字，包括自動完成輸入內容中相符的子字串陣列，並以 Unicode 字元表示偏移量和長度。
terms	類型：  Array<PredictionTerm> 上述說明中各個字詞的資訊，從最明確到最不明確。例如「Taco Bell」、「Willits」和「CA」。
types	類型：  Array<string> 預測所屬的類型陣列，例如 'establishment' 或 'geocode'。
distance_meters optional	類型：  number optional 地點與 AutocompletionRequest.origin 的距離 (以公尺為單位)。

QueryAutocompletePrediction 介面

google.maps.places.QueryAutocompletePrediction 介面

代表單一查詢自動完成預測。

屬性
description	類型：  string 這是地點服務建議的查詢，未經過格式化。
matched_substrings	類型：  Array<PredictionSubstring> 地點說明中的一組子字串，與使用者輸入內容中的元素相符，適合用於醒目顯示這些子字串。每個子字串都會以位移和長度 (以 Unicode 字元表示) 識別。
terms	類型：  Array<PredictionTerm> 上述說明中個別字詞的相關資訊。先輸入類別字詞 (例如「餐廳」)，地址字詞會依最明確到最不明確的順序顯示。例如「舊金山」和「加州」。
place_id optional	類型：  string optional 只有在預測結果是地點時才能使用。地點 ID，可用於透過地點詳細資料服務擷取這個地點的詳細資料 (請參閱 PlacesService.getDetails)。

PredictionTerm 介面

google.maps.places.PredictionTerm 介面

代表預測字詞。

屬性
offset	類型：  number 這個詞在地點說明中的起始位置 (以 Unicode 字元為單位)。
value	類型：  string 這個字詞的值，例如「Taco Bell」。

PredictionSubstring 介面

google.maps.places.PredictionSubstring 介面

代表預測子字串。

屬性
length	類型：  number 子字串的長度。
offset	類型：  number 子字串在說明字串中的起始偏移值。

StructuredFormatting 介面

google.maps.places.StructuredFormatting 介面

包含地點說明的結構化資訊，分為主要文字和次要文字，包括自動完成輸入內容中相符的子字串陣列，並以位移和長度 (以 Unicode 字元表示) 識別。

屬性
main_text	類型：  string 這是 Places 服務建議地點的未格式化說明主要文字部分。通常是地點名稱。
main_text_matched_substrings	類型：  Array<PredictionSubstring> 主要文字中的一組子字串，與使用者輸入內容中的元素相符，適合用於醒目顯示這些子字串。每個子字串都會以位移和長度 (以 Unicode 字元表示) 識別。
secondary_text	類型：  string 這是 Places 服務建議地點的未格式化說明次要文字部分。通常是地點的位置。