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

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

Place Autocomplete

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

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

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

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

新增 Autocomplete 小工具

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

您可以透過兩種方式將自動完成小工具新增至應用程式：

選項 1：嵌入 AutocompleteSupportFragment。
選項 2：使用意圖啟動自動完成活動。

方法 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 中新增監聽器：

KotlinJava

    // 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")
        }
    })

    // 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 建立意圖，以便啟動自動完成小工具：

KotlinJava

    // 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)

    // 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);

使用意圖啟動自動完成小工具時，您可以選擇疊加或全螢幕顯示模式。以下螢幕截圖分別顯示各個顯示模式：

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

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

註冊意圖結果的回呼

如要在使用者選取地點時收到通知，請定義 registerForActivityResult() 啟動器，啟動活動並處理結果，如以下範例所示。如果使用者選取某項預測結果，這項結果會透過結果物件中的意圖提供。這個意圖是由 Autocomplete.IntentBuilder 所建立，因此 Autocomplete.getPlaceFromIntent() 方法可以從中擷取 Place 物件。

KotlinJava

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")
        }
    }

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 物件：

必要：包含使用者輸入文字的 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() 的完整呼叫。

KotlinJava

    // 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}")
            }
        }

    // 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 物件清單。如果沒有與查詢和篩選條件相符的已知地點，清單可能會是空白的。

針對每個預測地點，您可以呼叫下列方法來擷取地點詳細資料：

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 和程式輔助 Autocomplete API。

如要限制結果，請按照下列步驟操作：

如要優先採用所定義區域內的結果，請呼叫 setLocationBias() (系統仍可能會傳回部分定義區域外的結果)。
如要只顯示所定義區域內的結果，請呼叫 setLocationRestriction() (只會傳回所定義區域內的結果)。
如要只傳回符合特定地點類型的結果，請呼叫 setTypesFilter() (例如指定 TypeFilter.ADDRESS 只會傳回包含精確地址的結果)。
如要只傳回最多五個指定國家/地區的結果，請呼叫 setCountries()。傳遞國家/地區時，請務必使用雙字元 ISO 3166-1 Alpha-2 相容國家/地區代碼。

針對特定區域調整結果

如要將自動完成結果偏向特定地理區域，請呼叫 setLocationBias()，並傳遞 RectangularBounds。以下程式碼範例說明如何在片段例項上呼叫 setLocationBias()，將自動完成建議偏向澳洲雪梨的某個區域。

KotlinJava

    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

將結果限制在特定區域

如要將自動完成結果限制在特定地理區域，請呼叫 setLocationRestriction()，並傳遞 RectangularBounds。以下程式碼範例說明如何在片段例項上呼叫 setLocationRestriction()，將自動完成建議偏向澳洲雪梨的某個區域。

KotlinJava

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

    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()，並指定多個類型值。

KotlinJava

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

以下程式碼範例說明如何在 AutocompleteSupportFragment 上呼叫 setTypesFilter()，藉由指定類型集合，設定只傳回具有精確地址的結果的篩選器。

KotlinJava

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

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

以下程式碼範例說明如何在 IntentBuilder 上呼叫 setTypesFilter()，藉由指定類型集合，設定只傳回精確地址的篩選器。

KotlinJava

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

依國家/地區篩選結果

如要將自動完成結果篩選至最多五個國家/地區，請呼叫 setCountries() 來設定國家/地區代碼。接著，將篩選器傳遞至片段或意圖。傳遞國家/地區時，請務必使用雙字元 ISO 3166-1 Alpha-2 相容國家/地區代碼。

以下程式碼範例顯示在 AutocompleteSupportFragment 上呼叫 setCountries()，以設定只傳回指定國家/地區內結果的篩選器。

KotlinJava

    autocompleteFragment.setCountries("AU", "NZ")

    autocompleteFragment.setCountries("AU", "NZ");

用量限制

您使用 Places API (包括 Places SDK for Android) 時，不再受每日要求次數上限 (QPD) 限制。不過，下列用量限制仍會套用：

頻率限制為每分鐘 6,000 次查詢 (每分鐘的要求數量)。計算方式為使用相同專案憑證的所有應用程式用戶端和伺服器端要求的總和。

在應用程式中顯示出處資訊

如果應用程式以程式輔助方式使用自動完成服務，使用者介面必須顯示「由 Google 提供技術支援」出處註明，或是顯示在 Google 品牌地圖中。
如果您的應用程式使用自動完成小工具，則無須採取其他行動 (系統會預設顯示必要的歸屬資訊)。
如果您在透過 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 Autocomplete 時，請使用工作階段符記 (以程式輔助方式或內建於 JavaScript、Android 或 iOS 小工具)。每個工作階段加上適用的 Places Data 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 提供地址和經緯度座標。提出四次 Place Autocomplete - Per Request 要求，再加上針對所選地點預測結果的 Geocoding API 呼叫，費用低於自動完成功能「按工作階段」計價的每個工作階段費用。¹

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

搭配 Place Details 使用以工作階段為準的 Place Autocomplete。
由於使用者選取 Place Autocomplete 預測結果前，您預期提出的平均要求數量會超過「按工作階段」計價的費用，因此導入 Place Autocomplete 時，請在 Place Autocomplete 要求和相關 Place Details 要求中使用按工作階段的會話方塊。¹

透過小工具導入
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 要求，總費用就是 4 次自動完成功能「按請求」計價 + 地理編碼。¹

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

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

如需費用資訊，請參閱 Google 地圖平台定價表。

這對你有幫助嗎？

效能最佳做法

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

針對導入的 Place Autocomplete 加入國家/地區限制、位置自訂調整和 (適用於程式輔助導入) 語言偏好設定。小工具會從使用者的瀏覽器或行動裝置選擇語言偏好設定，因此不需要設定語言偏好。
如果 Place Autocomplete 附帶地圖，您就可以根據地圖可視區域進行位置自訂調整。
如果使用者沒有選擇任何自動預測結果 (通常是因為這些預測結果並非他們想要的地址)，您可以重複使用原始使用者輸入內容，嘗試取得更相關的結果：
- 如果您預期使用者只會輸入地址資訊，請在 Geocoding API 呼叫中重複使用原始使用者輸入內容。
- 如果您預期使用者會依名稱或地址查詢某個地點，請使用「Find Place」要求。如果希望將結果範圍限制在特定區域，請使用位置自訂調整。
適合改回使用 Geocoding API 的其他情況如下：
- 使用者輸入子區域地址，例如建築物內特定單位或公寓的地址。例如，捷克地址「Stroupežnického 3191/17, Praha」在 Place Autocomplete 中會產生不完整的預測結果。
- 使用者輸入的地址含有路段前置字元，例如紐約的「23-30 29th St, Queens」或夏威夷考艾島的「47-380 Kamehameha Hwy, Kaneohe」。

疑難排解

雖然可能發生各種錯誤，但應用程式可能會遇到的大部分錯誤通常是設定錯誤 (例如使用錯誤的 API 金鑰，或錯誤設定 API 金鑰) 或配額錯誤 (應用程式已超出配額) 所致。如要進一步瞭解配額，請參閱「用量限制」。

使用自動完成控制項時發生的錯誤會在 onActivityResult() 回呼中傳回。呼叫 Autocomplete.getStatus() 即可取得結果的狀態訊息。