Places SDK for Android 中的自動完成服務會根據使用者的搜尋查詢傳回地點預測結果。當使用者輸入時，自動完成服務會傳回商家、地址、Plus Code 和搜尋點等地點的建議。
您可以透過下列方式在應用程式中加入自動完成功能：
- 加入 Autocomplete 小工具，節省開發時間並確保使用者體驗一致。
- 透過程式輔助方式取得地點預測結果，打造客製化使用者體驗。
新增 Autocomplete 小工具
Autocomplete 小工具是提供內建自動完成功能的搜尋對話方塊，使用者輸入搜尋字詞時，小工具會顯示預測地點清單以供選擇。使用者做出選擇時，系統會傳回 Place 例項，接著應用程式就能利用該例項取得所選地點的詳細資料。
在應用程式中加入 Autocomplete 小工具的方法有兩種：
選項 1：嵌入 AutocompleteSupportFragment
若要在應用程式中新增 AutocompleteSupportFragment，請按照下列步驟操作：
- 新增片段至活動的 XML 版面配置。
- 在活動或片段中新增事件監聽器。
將 AutocompleteSupportFragment 新增至活動
如要將 AutocompleteSupportFragment 新增至活動，請在 XML 版面配置中新增片段。例如：
<fragment android:id="@+id/autocomplete_fragment"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
/>
- 根據預設，片段沒有邊框或背景。如要提供一致的視覺外觀，請將片段巢狀結構置於其他版面配置元素 (例如 CardView) 中。
- 如果您使用 Autocomplete 片段，且需要覆寫
onActivityResult，則必須呼叫super.onActivityResult，否則該片段將無法正常運作。
將 PlaceSelectionListener 新增至活動
PlaceSelectionListener 會根據使用者的選擇傳回地點。下列程式碼顯示瞭如何建立片段的參照，並在 AutocompleteSupportFragment 中新增事件監聽器：
Kotlin
// Initialize the AutocompleteSupportFragment.
val autocompleteFragment =
supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
as AutocompleteSupportFragment
// Specify the types of place data to return.
autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))
// Set up a PlaceSelectionListener to handle the response.
autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
override fun onPlaceSelected(place: Place) {
// TODO: Get info about the selected place.
Log.i(TAG, "Place: ${place.name}, ${place.id}")
}
override fun onError(status: Status) {
// TODO: Handle the error.
Log.i(TAG, "An error occurred: $status")
}
})
Java
// Initialize the AutocompleteSupportFragment.
AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);
// Specify the types of place data to return.
autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));
// Set up a PlaceSelectionListener to handle the response.
autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
@Override
public void onPlaceSelected(@NonNull Place place) {
// TODO: Get info about the selected place.
Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
}
@Override
public void onError(@NonNull Status status) {
// TODO: Handle the error.
Log.i(TAG, "An error occurred: " + status);
}
});
方法 2：使用意圖啟動自動完成活動
如果您希望應用程式使用不同的導覽流程 (例如透過圖示 (而非搜尋欄位) 觸發自動完成體驗)，應用程式可以使用意圖啟動自動完成功能。
如要使用意圖啟動 Autocomplete 小工具，請按照下列步驟操作：
- 使用
Autocomplete.IntentBuilder建立意圖，傳遞所需的Autocomplete模式。 - 定義活動結果啟動器
registerForActivityResult，可用來啟動意圖，並處理使用者在搜尋結果中選取的地點預測結果。
建立 Autocomplete 意圖
以下範例使用 Autocomplete.IntentBuilder 建立意圖，以意圖啟動 Autocomplete 小工具：
Kotlin
// Set the fields to specify which types of place data to
// return after the user has made a selection.
val fields = listOf(Place.Field.ID, Place.Field.NAME)
// Start the autocomplete intent.
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.build(this)
startAutocomplete.launch(intent)
Java
// Set the fields to specify which types of place data to
// return after the user has made a selection.
List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
// Start the autocomplete intent.
Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.build(this);
startAutocomplete.launch(intent);
使用意圖啟動自動完成小工具時，您可以選擇疊加或全螢幕顯示模式。以下螢幕截圖分別顯示這兩種顯示模式：
註冊意圖結果的回呼
如要在使用者選取地點時收到通知，請定義 registerForActivityResult() 啟動器，用來啟動活動並處理結果，如以下範例所示。如果使用者選取某項預測結果，這項結果會透過結果物件中的意圖提供。由於意圖是由 Autocomplete.IntentBuilder 所建立，因此 Autocomplete.getPlaceFromIntent() 方法可以從中擷取 Place 物件。
Kotlin
private val startAutocomplete =
registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
if (result.resultCode == Activity.RESULT_OK) {
val intent = result.data
if (intent != null) {
val place = Autocomplete.getPlaceFromIntent(intent)
Log.i(
TAG, "Place: ${place.name}, ${place.id}"
)
}
} else if (result.resultCode == Activity.RESULT_CANCELED) {
// The user canceled the operation.
Log.i(TAG, "User canceled autocomplete")
}
}
Java
private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
new ActivityResultContracts.StartActivityForResult(),
result -> {
if (result.getResultCode() == Activity.RESULT_OK) {
Intent intent = result.getData();
if (intent != null) {
Place place = Autocomplete.getPlaceFromIntent(intent);
Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
}
} else if (result.getResultCode() == Activity.RESULT_CANCELED) {
// The user canceled the operation.
Log.i(TAG, "User canceled autocomplete");
}
});
透過程式輔助方式取得地點預測結果
除了由自動完成小工具提供的 UI 以外，您也可以建立自訂搜尋 UI，若要這麼做，應用程式必須以程式輔助方式取得地點預測結果。應用程式可以呼叫 PlacesClient.findAutocompletePredictions()，並傳遞含有下列參數的 FindAutocompletePredictionsRequest 物件，從自動完成 API 取得預測的地點名稱和/或地址清單：
- 必要：
query字串，包含使用者輸入的文字。 - 建議使用：
AutocompleteSessionToken，此屬性會將使用者搜尋的查詢和選取階段歸類為獨立的工作階段，以用於計費。工作階段是從使用者輸入查詢時開始，到使用者選取地點時結束。 - 建議使用：
RectangularBounds物件，這個物件會指定經緯度邊界，以將結果限制在指定區域。 - 選用：一或多個兩個字母的國家/地區代碼 (ISO 3166-1 Alpha-2)，用於指出應限制哪個國家/地區的結果。
選用步驟：
TypeFilter，用於將結果限制為指定地點類型。支援的地點類型如下：TypeFilter.GEOCODE：只傳回地理編碼結果，不含商家。這項要求可用來釐清指定位置可能不明確的結果。TypeFilter.ADDRESS：只傳回地址精確的自動完成結果。如果您知道使用者要查詢的是完整指定地址，請使用此類型。TypeFilter.ESTABLISHMENT：僅傳回商家的地點。TypeFilter.REGIONS- 僅傳回符合下列其中一種類型的地點：LOCALITYSUBLOCALITYPOSTAL_CODECOUNTRYADMINISTRATIVE_AREA_LEVEL_1ADMINISTRATIVE_AREA_LEVEL_2TypeFilter.CITIES：只傳回與LOCALITY或ADMINISTRATIVE_AREA_LEVEL_3相符的結果。
選用：指定要求起點位置的
LatLng。當您呼叫setOrigin()時，服務會針對回應中的每項自動完成預測，傳回距離指定來源的距離 (以公尺為單位 (distanceMeters)。
如需地點類型的相關資訊，請參閱地點類型指南。
以下範例顯示對 PlacesClient.findAutocompletePredictions() 的完整呼叫。
Kotlin
// Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
// and once again when the user makes a selection (for example when calling fetchPlace()).
val token = AutocompleteSessionToken.newInstance()
// Create a RectangularBounds object.
val bounds = RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
// Use the builder to create a FindAutocompletePredictionsRequest.
val request =
FindAutocompletePredictionsRequest.builder()
// Call either setLocationBias() OR setLocationRestriction().
.setLocationBias(bounds)
//.setLocationRestriction(bounds)
.setOrigin(LatLng(-33.8749937, 151.2041382))
.setCountries("AU", "NZ")
.setTypesFilter(listOf(PlaceTypes.ADDRESS))
.setSessionToken(token)
.setQuery(query)
.build()
placesClient.findAutocompletePredictions(request)
.addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
for (prediction in response.autocompletePredictions) {
Log.i(TAG, prediction.placeId)
Log.i(TAG, prediction.getPrimaryText(null).toString())
}
}.addOnFailureListener { exception: Exception? ->
if (exception is ApiException) {
Log.e(TAG, "Place not found: ${exception.statusCode}")
}
}
Java
// Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
// and once again when the user makes a selection (for example when calling fetchPlace()).
AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();
// Create a RectangularBounds object.
RectangularBounds bounds = RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596));
// Use the builder to create a FindAutocompletePredictionsRequest.
FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
// Call either setLocationBias() OR setLocationRestriction().
.setLocationBias(bounds)
//.setLocationRestriction(bounds)
.setOrigin(new LatLng(-33.8749937, 151.2041382))
.setCountries("AU", "NZ")
.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
.setSessionToken(token)
.setQuery(query)
.build();
placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
Log.i(TAG, prediction.getPlaceId());
Log.i(TAG, prediction.getPrimaryText(null).toString());
}
}).addOnFailureListener((exception) -> {
if (exception instanceof ApiException) {
ApiException apiException = (ApiException) exception;
Log.e(TAG, "Place not found: " + apiException.getStatusCode());
}
});
API 會在
Task 中傳回 FindAutocompletePredictionsResponse。FindAutocompletePredictionsResponse 包含代表預測地點的 AutocompletePrediction 物件清單。如果沒有與查詢和篩選條件相對應的已知地點，清單可能會是空白。
針對每個預測的地點，您可以呼叫下列方法以擷取 Place Details：
getFullText(CharacterStyle)會傳回地點說明的完整文字。這是主要和次要文字的組合。例如：「Eiffel Tower, Avenue Anatole France, Paris, France」。此外，此方法也可讓您使用CharacterStyle，醒目顯示符合搜尋樣式的說明區段。CharacterStyle為選用參數，如果您不需要任何醒目顯示，請將這個項目設為空值。getPrimaryText(CharacterStyle)會傳回地點描述的主要文字。這通常是地點的名稱。例如：「艾菲爾鐵塔」和「123 Pitt Street」。getSecondaryText(CharacterStyle)會傳回地點說明的子公司文字。舉例來說，在顯示自動完成預測結果時，這行程式碼就能派上用場。例如：「Avenue Anatole France, Paris, France」和「Sydney, New South Wales」。getPlaceId()會傳回預測地點的地點 ID。地點 ID 是專門用於識別地點的文字 ID，稍後可用來再次擷取Place物件。如要進一步瞭解 Places SDK for Android 中的地點 ID，請參閱 Place Details。如需地點 ID 的一般資訊，請參閱「地點 ID 總覽」。getPlaceTypes()會傳回與這個地點相關聯的地點類型清單。getDistanceMeters()會傳回這個地點與要求中指定的起點之間的直線距離 (以公尺為單位)。
工作階段符記
工作階段符記會將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。工作階段是從使用者輸入查詢時開始，到使用者選取地點時結束。在每個工作階段中，使用者可以輸入多筆查詢，最終選擇一個地點。工作階段確認後，憑證就會失效；應用程式必須為每個工作階段產生新的符記。建議您為所有程式輔助自動完成工作階段使用工作階段符記 (當您嵌入片段或使用意圖啟動自動完成功能時，API 會自動處理這項作業)。
Places SDK for Android 使用 AutocompleteSessionToken 識別每個工作階段。應用程式應在每個新工作階段開始時傳遞新的工作階段符記，然後在後續呼叫 fetchPlace() 時，傳遞相同的權杖和地點 ID，以擷取使用者所選地點的 Place Details。
限制自動完成結果
您可以將自動完成結果限制在特定地理區域，並/或篩選出一或多個地點類型，或最多五個國家/地區。您可以將這些限制套用至自動完成活動、AutocompleteSupportFragment 和程式輔助自動完成 API。
如要限制結果，請按照下列步驟操作：
- 如要「偏好」定義區域內的結果，請呼叫
setLocationBias()(系統可能仍會傳回所定義區域以外的部分結果)。 - 如果只顯示已定義區域內的結果，請呼叫
setLocationRestriction()(只會傳回指定區域內的結果)。 - 如果只要傳回符合特定地點類型的結果，請呼叫
setTypesFilter()(例如指定TypeFilter.ADDRESS只會傳回包含精確地址的結果)。 - 如果只要傳回最多五個指定國家/地區的結果，請呼叫
setCountries()。傳遞國家/地區時，請務必使用雙字元 ISO 3166-1 Alpha-2 相容國家/地區代碼。
針對特定區域調整結果
如要針對特定地理區域調整自動完成結果，請呼叫 setLocationBias() 並傳遞 RectangularBounds。以下程式碼範例顯示如何對片段執行個體呼叫 setLocationBias()，以針對澳洲雪梨的某區域調整自動完成建議。
Kotlin
autocompleteFragment.setLocationBias(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
Java
autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
限制只傳回特定區域的結果
如要將自動完成結果限制在特定地理區域，請呼叫 setLocationRestriction() 並傳遞 RectangularBounds。以下程式碼範例說明如何對片段執行個體呼叫 setLocationRestriction()，以針對澳洲雪梨的某區域調整自動完成建議。
Kotlin
autocompleteFragment.setLocationRestriction(
RectangularBounds.newInstance(
LatLng(-33.880490, 151.184363),
LatLng(-33.858754, 151.229596)
)
)
Java
autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
new LatLng(-33.880490, 151.184363),
new LatLng(-33.858754, 151.229596)));
注意：這項限制僅適用於整個路徑，超出矩形邊界以外的路徑可能會傳回合成結果，而該路徑與位置限制重疊的路徑相符。
依地點類型或類型集合篩選結果
您可以限制自動完成要求的結果，只傳回特定的地點類型。指定篩選器時，請使用表 1、2 和 3 上地點類型所列的地點類型或類型集合。如未指定，系統會傳回所有類型。
如要篩選自動完成結果，請呼叫 setTypesFilter() 來設定篩選器。
如何指定類型或類型集合篩選器：
呼叫
setTypesFilter()，然後指定「地點類型」中表 1 和表 2 提供的最多五個「類型」值。類型值由 PlaceTypes 中的常數定義。呼叫
setTypesFilter()，並指定地點類型所示表 3 的類型集合。集合值是由 PlaceTypes 中的常數定義。在要求中只能使用表 3 中的一種類型。如果您指定表 3 中的值，就無法指定表 1 或表 2 中的值。否則會發生錯誤。
以下程式碼範例會在 AutocompleteSupportFragment 上呼叫 setTypesFilter()，並指定多個類型值。
Kotlin
autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))
Java
autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));
以下程式碼範例顯示如何在 AutocompleteSupportFragment 上呼叫 setTypesFilter()，以便設定篩選器只傳回地址精確的結果，方法是指定類型集合。
Kotlin
autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))
Java
autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));
以下程式碼範例顯示如何在 IntentBuilder 上呼叫 setTypesFilter()，以便設定篩選器只傳回包含精確地址的結果，方法是指定類型集合。
Kotlin
val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(listOf(PlaceTypes.ADDRESS))
.build(this)
Java
Intent intent = new Autocomplete.IntentBuilder(
AutocompleteActivityMode.FULLSCREEN, fields)
.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
.build(this);
依國家/地區篩選結果
如果最多可篩選 5 個國家/地區的自動完成結果，請呼叫 setCountries() 來設定國家/地區代碼。然後將篩選器傳遞至片段或意圖。傳遞國家/地區時，請務必使用雙字元 ISO 3166-1 Alpha-2 相容國家/地區代碼。
以下程式碼範例說明如何對 AutocompleteSupportFragment 呼叫 setCountries()，設定篩選器只傳回指定國家/地區的結果。
Kotlin
autocompleteFragment.setCountries("AU", "NZ")
Java
autocompleteFragment.setCountries("AU", "NZ");
用量限制
使用 Places API (包括 Places SDK for Android) 時，系統不再設有每日要求數量上限 (QPD)。但仍適用下列用量限制：
- 頻率限制為每分鐘 6,000 次查詢 (每分鐘的要求數量)。計算方式為使用相同專案憑證的所有應用程式的用戶端和伺服器端要求總和。
在應用程式中顯示作者資訊
- 如果應用程式以程式輔助方式使用自動完成服務，則使用者介面必須顯示「由 Google 技術提供」屬性，或是顯示在 Google 品牌地圖上。
- 如果您的應用程式使用 Autocomplete 小工具，則無須採取其他動作 (預設會顯示必要的作者資訊)。
- 如果您在透過 ID 取得地點後擷取並顯示額外的地點資訊，則必須一併顯示第三方作者資訊。
詳情請參閱歸因相關說明文件。
Place Autocomplete 最佳化
本節將說明最佳做法，協助您充分運用 Place Autocomplete 服務。
以下列出幾項一般準則：
- 如要開發有效的使用者介面，最快的方法就是使用 Maps JavaScript API Autocomplete 小工具、Places SDK for Android Autocomplete 小工具，或 Places SDK for iOS Autocomplete UI 控制項
- 從一開始就嘗試瞭解 Place Autocomplete 的必要資料欄位。
- 「位置自訂調整」和「位置限制」為自選欄位，但可能會對自動完成效能產生重大影響。
- 使用錯誤處理機制，可以減輕 API 傳回錯誤時對應用程式效能造成的影響。
- 確保應用程式能處理未選取任何項目的情況，以便使用者繼續操作。
費用最佳化最佳做法
基本費用最佳化
為了讓 Place Autocomplete 服務費用發揮最大效益，請使用 Place Details 和 Place Autocomplete 小工具中的欄位遮罩，只傳回所需的地點資料欄位。
進階費用最佳化
建議您透過程式輔助方式導入 Place Autocomplete，採用按請求計價，並要求已選地點 (而非 Place Details) 的相關 Geocoding API 結果。如果同時符合以下兩項條件，搭配 Geocoding API 使用「按要求」計價會比使用「按工作階段」(以工作階段為準) 計價更具成本效益：
- 如果您只需要針對使用者選取的地點取得經緯度或地址，透過 Geocoding API 擷取這項資訊，支付的費用會比使用 Place Details 呼叫更低。
- 如果使用者在平均四次以內的自動預測結果要求選取了自動預測結果，則「按要求」計價可能會比「按工作階段」計價更符合成本效益。
除了所選預測結果的地址和經緯度，應用程式是否需要任何其他資訊？
是，需要更多詳細資料
搭配 Place Details 使用以工作階段為準的 Place Autocomplete。
您的應用程式會要求 Place Details (例如地點名稱、商家狀態或營業時間)，因此在導入 Place Autocomplete 時，建議使用工作階段符記 (透過程式輔助方式，或是內建於 JavaScript、Android 或 iOS 小工具)，總費用為每個工作階段 $0.017 美元，再加上適用的地點資料 SKU (視您要求的地點資料欄位而定)1。
透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Place Autocomplete 要求和 Place Details 要求。請務必指定 fields 參數，確保您只要求所需的地點資料欄位。
透過程式輔助方式導入
搭配 Place Autocomplete 要求使用工作階段符記。要求所選預測結果的相關 Place Details 時，請加入下列參數：
- Place Autocomplete 回應中的地點 ID
- Place Autocomplete 要求中使用的工作階段符記
- 指定所需地點資料欄位的
fields參數
否，只需要地址和位置資訊
對您的應用程式而言，Geocoding API 可能比 Place Details 更符合成本效益，視 Place Autocomplete 使用效能而定。每個應用程式的自動完成效率各不相同，可能取決於使用者輸入的內容、使用應用程式的位置，以及是否採用效能最佳化最佳做法。
為了找出以下問題的解答，請分析使用者在應用程式中選取 Place Autocomplete 預測結果前，平均輸入的字元數量。
使用者是否會在平均四次以內的要求中選取 Place Autocomplete 預測結果？
可
透過程式輔助方式導入 Place Autocomplete，但不使用工作階段符記，並針對已選取的地點預測結果呼叫 Geocoding API。
Geocoding API 提供地址和經緯度座標，收費為每次要求 $0.005 美元。提出四次 Place Autocomplete - Per Request 要求的費用為 $0.01132 美元，因此如果將四次要求加上所選地點預測結果的相關 Geocoding API 呼叫，總費用就會是 $0.01632 美元，低於自動完成功能「按工作階段」計價的每個工作階段 $0.017 美元1。
建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。
否
搭配 Place Details 使用以工作階段為準的 Place Autocomplete。
您預期使用者在選取 Place Autocomplete 預測結果前提出的平均要求數量，會超過「按工作階段」計價的費用，因此在導入 Place Autocomplete 時，建議針對 Place Autocomplete 要求和相關聯的 Place Details 要求都使用工作階段符記，總費用為每個工作階段 $0.017 美元1。
透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Place Autocomplete 要求和 Place Details 要求。請務必指定 fields 參數，確保只要求需要的 Basic Data 欄位。
透過程式輔助方式導入
搭配 Place Autocomplete 要求使用工作階段符記。要求所選預測結果的相關 Place Details 時，請加入下列參數：
- Place Autocomplete 回應中的地點 ID
- Place Autocomplete 要求中使用的工作階段符記
- 指定地址和幾何圖形等 Basic Data 欄位的
fields參數
考慮延後 Place Autocomplete 要求
您可以運用一些策略，例如將 Place Autocomplete 要求延後到使用者輸入三或四個字元時再開始，藉此減少應用程式提出要求數量。舉例來說，如果您是在使用者輸入第三個字元「之後」才針對每個字元提出 Place Autocomplete 要求，那麼當使用者在輸入七個字元後，選取您透過單次 Geocoding API 要求帶出的一筆預測結果，總費用就是 $0.01632 美元 (4 * $0.00283 Autocomplete Per Request + $0.005 美元 Geocoding)1。
如果延後要求可以讓平均程式輔助要求少於四次，您可以按照使用 Geocoding API 提高 Place Autocomplete 效能的指南操作。請注意，如果使用者希望每輸入一個字就能看到預測結果，可能就會將延後要求視為時間上的延遲。
建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。
-
這裡列出的費用是以美元計算。如需完整計價資訊，請參閱「Google 地圖平台計費方式」頁面。
效能最佳做法
以下準則說明如何將 Place Autocomplete 效能最佳化：
- 針對導入的 Place Autocomplete 加入國家/地區限制、位置自訂調整和 (適用於程式輔助導入) 語言偏好設定。小工具會從使用者的瀏覽器或行動裝置選擇語言偏好設定，因此不需要設定語言偏好。
- 如果 Place Autocomplete 附帶地圖，您就可以根據地圖可視區域進行位置自訂調整。
- 如果使用者沒有選擇任何自動預測結果 (通常是因為這些預測結果並非他們想要的地址)，您可以重複使用原始使用者輸入內容，嘗試取得更相關的結果：
- 如果您預期使用者只會輸入地址資訊，請在 Geocoding API 呼叫中重複使用原始使用者輸入內容。
- 如果您預期使用者會依名稱或地址查詢某個地點，請使用「Find Place」要求。如果希望將結果範圍限制在特定區域，請使用位置自訂調整。
- 使用者輸入的次要場所地址，位於 Place Autocomplete 未能完整提供次要場所地址支援的國家/地區 (例如捷克、愛沙尼亞和立陶宛)。例如，捷克地址「Stroupežnického 3191/17, Praha」在 Place Autocomplete 中會產生不完整的預測結果。
- 使用者輸入的地址含有路段前置字元，例如紐約的「23-30 29th St, Queens」或夏威夷考艾島的「47-380 Kamehameha Hwy, Kaneohe」。
疑難排解
雖然可能發生各種錯誤，但應用程式發生的多數錯誤通常都是由設定錯誤所造成 (例如使用的 API 金鑰有誤，或 API 金鑰設定有誤) 或配額錯誤 (應用程式超出配額)。如要進一步瞭解配額，請參閱使用限制一文。
使用自動完成控制項時發生的錯誤會傳回 onActivityResult() 回呼。呼叫 Autocomplete.getStatus() 取得結果的狀態訊息。