Autocomplete (新版) 會在回應要求時傳回地點預測結果，該要求包含文字搜尋字串和用於控制搜尋區域的地理邊界。Autocomplete 可比對輸入內容的完整字詞和子字串，解析地點名稱、地址和 Plus Codes。應用程式可在使用者輸入內容時傳送查詢，即時提供地點和查詢預測結果。
舉例來說，您可以使用包含部分使用者輸入內容的字串 (例如「Sicilian piz」) 做為輸入內容，並將搜尋區域限制在加州舊金山。回應會包含與搜尋字串和搜尋區域相符的地點預測結果清單，例如名為「Sicilian Pizza Kitchen」的餐廳。系統會將傳回的地點預測結果呈現給使用者，協助他們選取所需地點。您可以發出 Place Details (新版) 要求，取得任何傳回地點預測結果的詳細資訊。
您可以透過兩種主要方式將 Autocomplete (New) 功能整合至應用程式：
- 新增 Place Autocomplete 小工具：透過
PlaceAutocomplete類別提供可立即使用的搜尋自動完成體驗，該類別會在使用者輸入內容時顯示預測結果。 - 透過程式輔助方式取得地點預測結果：直接呼叫 API 來擷取預測結果，並在自訂使用者介面中顯示。
新增 Place Autocomplete 小工具
如要更輕鬆地提供一致的地點自動完成體驗，您可以將 Place Autocomplete 小工具新增至應用程式。這個小工具提供專屬的全螢幕介面，可處理使用者輸入內容，並向使用者顯示地點預測結果，同時將 AutocompletePrediction 物件傳回至應用程式。接著，您可以發出 Place Details (New) 要求，取得任何地點預測結果的其他資訊。
就像透過程式輔助方式取得地點預測結果一樣，Place Autocomplete 小工具可讓您使用工作階段符記，將自動完成要求分組為工作階段，以便計費。您可以呼叫 setAutocompleteSessionToken()，在建立小工具的意圖時傳遞工作階段權杖。如果您未提供工作階段權杖，小工具會為您建立一個，您可以透過呼叫 getSessionTokenFromIntent() 存取該權杖。如要進一步瞭解如何使用工作階段符記，請參閱「關於工作階段符記」。
如要在應用程式中加入 Place Autocomplete 小工具，請按照下列步驟操作：
(選用) 定義工作階段權杖。如果您未提供工作階段權杖，小工具會為您建立一個。
使用所需參數和工作階段權杖定義
autocompleteIntent。為
StartActivityForResult定義ActivityResultLauncher。這個啟動器會處理自動完成活動傳回的結果。在
ActivityResultLauncher的回呼中處理結果。這包括擷取AutocompletePrediction和AutocompleteSessionToken(如果您未提供自己的值)、處理錯誤，以及視需要提出fetchPlace()要求，以取得地點的其他詳細資料。使用
placeAutocompleteActivityResultLauncher啟動意圖
以下範例示範如何使用 Kotlin 和 Java 新增 Place Autocomplete 小工具：
Kotlin
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key) // Optional, create a session token for Autocomplete request and the followup FetchPlace request. val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance() val autocompleteIntent: Intent = PlaceAutocomplete.createIntent(this) { // ... provide input params for origin, countries, types filter ... setAutocompleteSessionToken(sessionToken) } val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> val intent = result.data if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object val prediction: AutocompletePrediction? = PlaceAutocomplete.getPredictionFromIntent(intent!!) // get session token val sessionToken: AutocompleteSessionToken? = PlaceAutocomplete.getSessionTokenFromIntent(intent!!) // create PlacesClient to make FetchPlace request (optional) val placesClient: PlacesClient = Places.createClient(this) val response = placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME) { sessionToken = sessionToken // optional } } } // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)
Java
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key); // Optional, create a session token for Autocomplete request and the followup FetchPlace request AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance(); Intent autocompleteIntent = new PlaceAutocomplete.IntentBuilder() // ... set input params for origin, countries, types filter ... .setSessionToken(sessionToken) // optional .build(this); ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent( Preconditions.checkNotNull(intent)); // get session token AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent( Preconditions.checkNotNull(intent)); // create PlacesClient to make FetchPlace request (optional) PlacesClient placesClient = Places.createClient(this); FetchPlaceRequest request = FetchPlaceRequest.builder(prediction.getPlaceId(), Arrays.asList(Field.DISPLAY_NAME)) .setSessionToken(sessionToken).build(); Task<FetchPlaceResponse> task = placesClient.fetchPlace(request); } } } ); // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);
透過程式取得地點預測結果
應用程式可以呼叫 PlacesClient.findAutocompletePredictions()，傳遞 FindAutocompletePredictionsRequest 物件，藉此從自動完成 API 取得預測地點名稱和/或地址的清單。以下範例顯示對 PlacesClient.findAutocompletePredictions() 的完整呼叫。
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Sicilian piz")
.setRegionCode("ES")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);Autocomplete (New) 回覆
API 會在 Task 中傳回 FindAutocompletePredictionsResponse。FindAutocompletePredictionsResponse 包含最多五個代表預測地點的 AutocompletePrediction 物件清單。如果沒有與查詢和篩選條件相符的已知地點，清單可能會是空白的。
針對每個預測地點，您可以呼叫下列方法來擷取地點詳細資料：
getFullText(CharacterStyle)會傳回地點說明的完整文字。這是主要文字和次要文字的組合。例如：艾菲爾鐵塔，Avenue Anatole France，巴黎，法國。此外，您也可以使用CharacterStyle方法，以您選擇的樣式醒目顯示與搜尋內容相符的說明部分。CharacterStyle參數為選用參數。如果不需要任何醒目顯示，請將其設為 null。getPrimaryText(CharacterStyle)會傳回描述地點的主要文字。通常是地點的名稱。例如「艾菲爾鐵塔」和「123 Pitt Street」。getSecondaryText(CharacterStyle)會傳回地點說明的輔助文字。舉例來說，當您要顯示自動完成預測時，這項功能就很實用，可用於第二行。例如：「Avenue Anatole France, Paris, France」和「Sydney, New South Wales」。getPlaceId()會傳回預測地點的地點 ID。地點 ID 是用來識別特定地點的文字 ID，您可以用來稍後再次擷取Place物件。如要進一步瞭解 Autocomplete 中的地點 ID，請參閱「Place Details (新版)」。如需地點 ID 的一般資訊，請參閱「地點 ID 總覽」。getTypes()會傳回與此地點相關聯的地點類型清單。getDistanceMeters()會傳回此地點與要求中指定的起點之間的直線距離 (以公尺為單位)。
必要參數
-
查詢
要搜尋的文字字串。指定完整字詞和子字串、地點名稱、地址和 Plus Codes。Autocomplete (New) 服務會根據這個字串傳回候選相符項目，並依據觀察到的關聯性排序結果。
如要設定查詢參數，請在建構
FindAutocompletePredictionsRequest物件時呼叫setQuery()方法。
選用參數
-
主要類型
清單，列出 表 A 或 表 B 中最多五個類型值，用於篩選回應中傳回的地點。地點必須符合指定的主要類型值，才能納入回應。
地點只能有一種主要類型，來自與其相關聯的 表 A 或 表 B 中的類型。例如，主要類型可能是
"mexican_restaurant"或"steak_house"。如有下列情況，要求就會遭到拒絕，並傳回
INVALID_REQUEST錯誤：- 指定的類型超過五個。
- 指定任何無法辨識的類型。
如要設定主要類型參數，請在建構
FindAutocompletePredictionsRequest物件時呼叫setTypesFilter()方法。 -
國家/地區
只納入指定國家/地區清單中的結果，該清單會以最多 15 個 ccTLD (「頂層網域」) 兩位字元值的清單形式指定。如果省略，系統不會對回應套用任何限制。例如，如要將地區限制為德國和法國：
如果同時指定
locationRestriction和includedRegionCodes，結果會位於這兩個設定的交集區域。如要設定國家/地區參數，請在建構
FindAutocompletePredictionsRequest物件時呼叫setCountries()方法。 -
輸入偏移
以零為基底的 Unicode 字元位移值，表示查詢中游標的位置。游標位置可能會影響系統傳回的預測結果。如果留空，則預設為查詢的長度。
如要設定輸入偏移參數，請在建構
FindAutocompletePredictionsRequest物件時呼叫setInputOffset()方法。 地區偏差或地區限制
您可以指定地點偏好設定或地點限制，但不能同時指定兩者，以便定義搜尋區域。您可以將位置限制視為指定結果必須位於其中的區域，而位置偏差則是指定結果必須位於附近的區域。主要差異在於，使用位置偏差時，系統仍可能會傳回指定區域以外的結果。
位置偏差
指定要搜尋的區域。這個位置是偏好設定，而非限制，因此系統仍可能會傳回指定區域外的結果。
如要設定位置偏差參數，請在建構
FindAutocompletePredictionsRequest物件時呼叫setLocationBias()方法。地區限制
指定要搜尋的區域。系統不會傳回指定區域以外的結果。
如要設定位置限制參數，請在建構
FindAutocompletePredictionsRequest物件時呼叫setLocationRestriction()方法。
將位置偏差或位置限制區域指定為矩形可視區域或圓形。
圓形的定義是中心點和半徑 (以公尺為單位)。半徑必須介於 0.0 和 50000.0 之間 (含首尾)。預設值為 0.0。針對位置限制，您必須將半徑設為大於 0.0 的值。否則，要求不會傳回任何結果。
矩形是經緯度可視區域，以兩個對角相反的
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都必須填入資料，且所代表的方塊不得空白。空白的檢視區會導致錯誤。- 如果
-
來源
計算到目的地的直線距離時所用的起點 (使用
getDistanceMeters()存取)。如果省略這個值，系統就不會傳回直線距離。必須指定為經緯度座標：如要設定來源參數，請在建構
FindAutocompletePredictionsRequest物件時呼叫setOrigin()方法。 -
區域代碼
用於格式化回應 (包括地址格式) 的區碼，採 ccTLD (「頂層網域」) 的兩位字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是「大不列顛與北愛爾蘭聯合王國」實體)。
如果您指定無效的區域代碼，API 會傳回
INVALID_ARGUMENT錯誤。參數可能會影響根據適用法律產生的結果。如要設定區域代碼參數，請在建構
FindAutocompletePredictionsRequest物件時呼叫setRegionCode()方法。 -
工作階段符記
工作階段符記是使用者產生的字串，用於追蹤 Autocomplete (New) 呼叫 (透過小工具和程式輔助呼叫) 的「工作階段」。Autocomplete 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。工作階段是從使用者輸入查詢時開始，到使用者選取地點時結束。在每個工作階段中，使用者可以輸入多筆查詢，最終選擇一個地點。工作階段結束後，符記就會失效；您的應用程式必須為每個工作階段產生新的符記。建議您在所有程式輔助自動完成工作階段使用工作階段符記 (當您嵌入片段或使用意圖啟動自動完成功能時，API 會自動處理這項作業)。
自動完成功能會使用
AutocompleteSessionToken來識別每個工作階段。應用程式應在開始每個新工作階段時傳遞新的工作階段符記，然後在後續呼叫fetchPlace()時傳遞該符記和地點 ID，以便擷取使用者選取的地點詳細資料。如要設定工作階段權杖參數，請在建構
FindAutocompletePredictionsRequest物件時呼叫setSessionToken()方法。詳情請參閱「工作階段符記」。
自動完成 (新版) 範例
使用地區限制和地區偏好設定
根據預設，Autocomplete (新版) 會使用 IP 偏差來控管搜尋範圍。使用 IP 偏差時，API 會使用裝置的 IP 位址來偏差結果。您可以選擇使用位置限制或位置偏差 (但不能同時使用兩者)，指定要搜尋的區域。
地點限制可指定搜尋範圍。系統不會傳回指定區域以外的結果。以下範例使用位置限制，將要求限制在以舊金山為中心，半徑 5000 公尺的圓形位置限制範圍內：
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);使用位置偏好設定時，系統會以位置做為偏好設定，也就是說，系統會傳回指定位置附近的結果，包括指定區域以外的結果。下一個範例會變更先前的請求，使用位置偏誤：
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);使用主要類型
使用「primary types」參數，將要求的結果限制為特定類型，如表 A和表 B所列。您可以指定最多五個值的陣列。如果省略，系統會傳回所有類型。
以下範例會指定「足球」查詢字串，並使用主要類型參數，將結果限制為 "sporting_goods_store" 類型的商家：
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Soccer")
.setIncludedPrimaryTypes(primaryTypes)
.setLocationBias(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);如果省略主要類型參數，結果可能會包含您不想要的類型機構，例如 "athletic_field"。
使用來源
在要求中加入 origin 參數 (以經緯度座標指定) 時，API 會在回應中加入從起點到目的地的直線距離 (使用 getDistanceMeters() 存取)。以下範例將起點設為舊金山市中心：
Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
FindAutocompletePredictionsRequest.builder()
.setQuery("Amoeba")
.setOrigin(center)
.setLocationRestriction(circle)
.build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
.addOnSuccessListener(
(response) -> {
List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
}
).addOnFailureListener(
exception -> {
Log.e(TAG, "some exception happened" + exception.getMessage());
})
);歸因
即使沒有地圖，您也可以使用 Autocomplete (新版)。如要顯示地圖，則必須使用 Google 地圖。如果您要顯示 Autocomplete (New) 服務的預測結果，但不顯示地圖，則必須在搜尋欄位/結果中顯示 Google 標誌。詳情請參閱「顯示 Google 標誌和出處來源」。