Places Autocomplete Service (deprecated)

AutocompleteService 類別

google.maps.places.AutocompleteService class
library "places"

已淘汰：自 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");

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

AutocompleteResponse 介面

google.maps.places.AutocompleteResponse 介面

呼叫 AutocompleteService.getPlacePredictions 傳回的自動完成回應，其中包含 AutocompletePrediction 清單。

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

QueryAutocompletionRequest 介面

google.maps.places.QueryAutocompletionRequest 介面

要傳送至 QueryAutocompleteService 的 QueryAutocompletion 要求。

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

ComponentRestrictions 介面

google.maps.places.ComponentRestrictions 介面

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

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

AutocompletePrediction 介面

google.maps.places.AutocompletePrediction 介面

代表單一自動預測結果。

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

QueryAutocompletePrediction 介面

google.maps.places.QueryAutocompletePrediction 介面

代表單一查詢自動預測結果。

屬性
description	類型： string 這是 Places 服務建議的查詢，未經格式化。
matched_substrings	類型： Array<PredictionSubstring> 地點說明中的一組子字串，與使用者輸入內容中的元素相符，適合用來醒目顯示這些子字串。每個子字串都由偏移和長度識別，以 Unicode 字元表示。
terms	類型： Array<PredictionTerm> 上述說明中個別字詞的資訊。類別字詞會優先顯示 (例如「餐廳」)，地址字詞會依具體程度由高到低顯示。例如「臺北市」和「臺灣」。
place_id 選填	類型： string optional 只有在預測結果為地點時，才能使用這個屬性。地點 ID，可用於透過 Place Details 服務擷取這個地點的詳細資料 (請參閱 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 這是地點服務建議地點的未格式化說明次要文字部分。通常是地點的位置。