新一代 Places SDK for Android 現已支援 Places SDK for Android (新版)。

本頁面由 Cloud Translation API 翻譯而成。

Place Autocomplete

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

Places SDK for Android 中的自動完成服務會根據使用者的搜尋查詢，傳回地點預測結果。使用者輸入內容時，自動完成服務會傳回地點建議，例如商家、地址、Plus Codes 和搜尋點。

您可以透過下列方式在應用程式中加入自動完成功能：

新增自動完成小工具，節省開發時間並確保使用者享有一致的體驗。
透過程式輔助取得地點預測結果，打造客製化的使用者體驗。

新增 Autocomplete 小工具

自動完成小工具是內建自動完成功能的搜尋對話方塊功能。使用者輸入搜尋字詞時，小工具會顯示預測地點清單，讓使用者選擇。使用者選取項目時，系統會傳回 Place 例項，應用程式就能使用該例項取得所選地點的詳細資料。

在應用程式中加入 Autocomplete 小工具的方法有兩種：

方法 1：嵌入 AutocompleteSupportFragment。
方法 2：使用意圖啟動 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。
如果您使用自動完成片段，且需要覆寫 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.IntentBuilder 建立意圖，並傳遞所需的 Autocomplete 模式。
定義活動結果啟動器 registerForActivityResult 可用來啟動意圖和處理使用者選取的位置預測結果

建立自動完成意圖

下列範例使用 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);

使用意圖啟動 Autocomplete 小工具時，您可以選擇疊加或全螢幕顯示模式。以下螢幕截圖顯示顯示模式：

在疊加模式下顯示時，自動完成小工具會顯示在呼叫 UI 上方。 — **圖 1**：OVERLAY 模式中的 Autocomplete 小工具

以全螢幕模式顯示時，自動完成小工具會填滿整個螢幕。 — **圖 2**：全螢幕模式中的自動完成小工具

註冊意圖結果的回呼

如要在使用者選取地點時收到通知，請定義 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 物件，從 Autocomplete API 取得預測地點名稱和/或地址的清單：

必要：包含使用者輸入文字的 query 字串。
建議做法：使用 AutocompleteSessionToken，將使用者搜尋的查詢和選取階段歸入不同的工作階段，以便計費。工作階段是從使用者開始輸入時起算此過程直到使用者選取地點時結束。
建議：RectangularBounds 物件，這個物件會指定經緯度邊界，以限制結果指定區域。
選用：一或多個兩個字母的國家/地區代碼 (ISO 3166-1 Alpha-2)，用於指定結果應限制的國家/地區。
選填： TypeFilter, ，可用來將結果限制為指定的地點類型。支援下列地點類型：
- TypeFilter.GEOCODE - 只傳回地理編碼結果，而非傳回地理編碼結果的商機。使用這項要求，可釐清指定位置可能不明確的結果。
- TypeFilter.ADDRESS：只傳回包含精確地址的自動完成結果。如果您知道使用者正在尋找完整指定地址
- TypeFilter.ESTABLISHMENT：只會傳回商家地點。
- TypeFilter.REGIONS – 只傳回與其中一個選項相符的地點下列類型：
- LOCALITY
- SUBLOCALITY
- POSTAL_CODE
- COUNTRY
- ADMINISTRATIVE_AREA_LEVEL_1
- ADMINISTRATIVE_AREA_LEVEL_2
- TypeFilter.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 會傳回 FindAutocompletePredictionsResponse 在 Task。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 物件。如要進一步瞭解 Places SDK for Android 中的地點 ID，請參閱「地點詳細資料」。如需地點 ID 的一般資訊，請參閱「地點 ID 總覽」。
getPlaceTypes() 會傳回與此地點相關聯的地點類型清單。
getDistanceMeters() 會傳回此地點與要求中指定的起點之間的直線距離 (以公尺為單位)。

注意：如要進一步瞭解如何初始化 PlacesClient，請參閱「初始化 Places API 用戶端」。

工作階段符記

工作階段符記會將使用者自動完成的查詢和選取階段分組執行付費查詢工作階段是從使用者輸入查詢時開始，到使用者選取地點時結束。每堂課可以包含多個查詢，緊接著選擇一個地點。工作階段結束後，符記就會失效；您的應用程式必須為每個工作階段產生新的符記。建議您在所有程式輔助自動完成工作階段中使用工作階段符記 (當您嵌入片段或使用意圖啟動自動完成功能時，API 會自動處理這項作業)。

Places SDK for Android 使用 AutocompleteSessionToken 辨別每個工作階段應用程式應在開始每個新工作階段時傳遞新的會話方塊符記，然後在後續呼叫 fetchPlace() 時傳遞相同的符記和地點 ID，以便擷取使用者選取的地點詳細資料。

進一步瞭解工作階段符記

限制自動完成結果

您可以將自動完成結果限制在特定地理區域，並/或將結果篩選為一或多個地點類型，或最多五個國家/地區。個人中心可以將這些限制條件套用至 Autocomplete 活動 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"));

以下程式碼範例顯示，如何在setTypesFilter() AutocompleteSupportFragment：設定篩選器只傳回含有請指定類型集合，精確找出地址

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Java

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

以下程式碼範例顯示，如何在setTypesFilter() IntentBuilder：設定篩選器，只傳回含有精確地址的結果指定類型集合

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 Autocomplete 導入方式，請回答下列問題，並選取對應的分頁標籤。

除了所選預測結果的地址和經緯度，應用程式是否需要任何其他資訊？

是，需要更多詳細資料

搭配 Place Details 使用以工作階段為準的 Place Autocomplete。
您的應用程式會要求 Place Details (例如地點名稱、商家狀態或營業時間)，因此在導入 Place Autocomplete 時，建議使用工作階段符記 (透過程式輔助方式，或是內建於 JavaScript、Android 或 iOS 小工具)，總費用為每個工作階段 $0.017 美元，再加上適用的地點資料 SKU (視您要求的地點資料欄位而定)¹。

透過小工具導入
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 美元¹。

建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。

否

搭配 Place Details 使用以工作階段為準的 Place Autocomplete。
您預期使用者在選取 Place Autocomplete 預測結果前提出的平均要求數量，會超過「按工作階段」計價的費用，因此在導入 Place Autocomplete 時，建議針對 Place Autocomplete 要求和相關聯的 Place Details 要求都使用工作階段符記，總費用為每個工作階段 $0.017 美元¹。

透過小工具導入
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)¹。

如果延後要求可以讓平均程式輔助要求少於四次，您可以按照使用 Geocoding API 提高 Place Autocomplete 效能的指南操作。請注意，如果使用者希望每輸入一個字就能看到預測結果，可能就會將延後要求視為時間上的延遲。

建議您採用效能最佳做法，讓使用者以更少的字元找到需要的預測結果。

這裡列出的費用是以美元計算。如需完整計價資訊，請參閱「Google 地圖平台計費方式」頁面。

效能最佳做法

以下準則說明如何將 Place Autocomplete 效能最佳化：

針對導入的 Place Autocomplete 加入國家/地區限制、位置自訂調整和 (適用於程式輔助導入) 語言偏好設定。小工具會從使用者的瀏覽器或行動裝置選擇語言偏好設定，因此不需要設定語言偏好。
如果 Place Autocomplete 附帶地圖，您就可以根據地圖可視區域進行位置自訂調整。
如果使用者沒有選擇任何自動預測結果 (通常是因為這些預測結果並非他們想要的地址)，您可以重複使用原始使用者輸入內容，嘗試取得更相關的結果：
- 如果您預期使用者只會輸入地址資訊，請在 Geocoding API 呼叫中重複使用原始使用者輸入內容。
- 如果您預期使用者會依名稱或地址查詢某個地點，請使用「Find Place」要求。如果希望將結果範圍限制在特定區域，請使用位置自訂調整。
適合改回使用 Geocoding API 的其他情況如下：
- 使用者輸入的次要場所地址，位於 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() 即可取得結果的狀態訊息。