Place Autocomplete

歐洲經濟區 (EEA) 開發人員

如果您的帳單地址位於歐洲經濟區，自 2025 年 7 月 8 日起，使用服務時將適用《 Google Maps Platform 歐洲經濟區服務條款》。功能會因區域而異。 瞭解詳情。

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

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

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

新增 Autocomplete 小工具

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

將自動完成小工具新增至應用程式的方法有兩種：

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

方法 1：嵌入 AutocompleteSupportFragment

如要在應用程式中新增 AutocompleteSupportFragment，請按照下列步驟操作：

1. 在活動的 XML 版面配置中新增片段。
2. 在活動或片段中新增監聽器。

將 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：使用意圖啟動自動完成活動

如果想讓應用程式使用不同的導覽流程 (例如從圖示而非搜尋欄觸發自動完成體驗)，應用程式可以使用意圖啟動自動完成功能。

注意：如果您是嵌入片段，則不需要執行這些步驟。

注意：請勿直接啟動 AutcompleteActivity。請改用啟動 Autocomplete 的意圖 (相容性程式庫中的 PlaceAutocomplete)。

如要使用意圖啟動自動完成小工具，請按照下列步驟操作：

1. 使用 Autocomplete.IntentBuilder 建立意圖，並傳遞所需的 Autocomplete 模式。
2. 定義活動結果啟動器 registerForActivityResult，可用於啟動意圖，並處理結果中使用者選取的地點預測。

建立自動完成意圖

下例會使用 Autocomplete.IntentBuilder 建立意圖，以意圖形式啟動自動完成小工具：

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

      

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

圖 1：OVERLAY 模式下的自動完成小工具

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

      

以程式輔助方式取得地點預測結果

您可以建立自訂搜尋使用者介面，取代自動完成小工具提供的介面。如要這麼做，應用程式必須以程式輔助方式取得地點預測結果。應用程式可以呼叫 PlacesClient.findAutocompletePredictions()，並傳遞含有下列參數的 FindAutocompletePredictionsRequest 物件，從 Autocomplete API 取得預測的地點名稱和/或地址清單：

• 必要：包含使用者輸入文字的 query 字串。
• 建議：A 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 會在 Task 中傳回 FindAutocompletePredictionsResponse。FindAutocompletePredictionsResponse 包含代表預測地點的 AutocompletePrediction 物件清單。如果沒有與查詢和篩選條件相符的已知地點，清單可能會是空白的。

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

• getFullText(CharacterStyle) 傳回地點說明的完整文字。這是主要和次要文字的組合。範例：「艾菲爾鐵塔，阿納托爾法蘭斯大道， 法國巴黎」。此外，這個方法可讓您使用 CharacterStyle，以所選樣式醒目顯示與搜尋內容相符的說明部分。CharacterStyle 參數為選用參數。如不需要任何醒目顯示效果，請設為 null。
• getPrimaryText(CharacterStyle) 傳回說明地點的主要文字。這通常是地點名稱。例如「艾菲爾鐵塔」和「123 Pitt Street」。
• getSecondaryText(CharacterStyle) 傳回地點說明的附屬文字。舉例來說，在顯示自動完成預測時，這項功能可做為第二行。範例：「法國巴黎阿納托爾法蘭斯大道」和「澳洲新南威爾斯州雪梨」。
• getPlaceId() 傳回預測地點的地點 ID。地點 ID 是用來識別特定地點的文字 ID，可用於日後再次擷取Place物件。如要進一步瞭解 Android 版 Places SDK 中的地點 ID，請參閱「地點詳細資料」。如需地點 ID 的一般資訊，請參閱「地點 ID 總覽」。
• getPlaceTypes() 傳回與這個地點相關聯的地點類型清單。
• getDistanceMeters() 傳回這個地點與要求中指定原點之間的直線距離 (以公尺為單位)。

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

您可以透過 CancellationToken 嘗試取消對任何要求類別的要求 (例如 FetchPlaceRequest)。系統會盡力取消要求。取消要求發出後，系統不會傳回任何回應。 發出取消權杖「無法」保證特定要求會取消，即使未傳回任何回應，您仍可能需要支付要求費用。

工作階段符記

工作階段符記會將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。工作階段是從使用者輸入查詢時開始，到使用者選取地點時結束。在每個工作階段中，使用者可以輸入多筆查詢，最終選擇一個地點。工作階段結束後，符記就會失效。您的應用程式必須為每個工作階段產生新的符記。建議您在所有透過程式輔助方式進行的自動完成工作階段使用工作階段符記 (當您嵌入片段或使用意圖啟動自動完成功能時，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 中的 type 值 (最多五個)。類型值是由 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);

      

依國家/地區篩選結果

如要將自動完成結果篩選至最多五個國家/地區，請呼叫 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 次查詢 (每分鐘的要求數量)。計算方式為使用相同專案憑證的所有應用程式，其用戶端和伺服器端要求的總和。

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

• 如果應用程式以程式輔助方式使用自動完成服務，使用者介面必須顯示「Powered by Google」出處註明，或顯示在 Google 品牌的 Google 地圖中。
• 如果應用程式使用自動完成小工具，則無須採取其他行動 (系統預設會顯示必要出處資訊)。
• 如果您在依 ID 取得地點後擷取並顯示其他地點資訊，也必須顯示第三方出處資訊。

詳情請參閱出處說明文件。

Place Autocomplete (舊版) 最佳化

本節將說明最佳做法，協助您充分運用 Place Autocomplete (舊版) 服務。

以下列出幾項一般準則：

• 如要開發有效的使用者介面，最快的方法就是使用 Maps JavaScript API Place Autocomplete (Legacy) 小工具、Places SDK for Android Place Autocomplete (Legacy) 小工具，或 Places SDK for iOS Place Autocomplete (Legacy) 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 Autocomplete (舊版) 導入方式，請回答下列問題，並選取對應的分頁標籤。

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

是，需要更多詳細資料

搭配 Place Details (舊版) 使用以工作階段為準的 Place Autocomplete (舊版)。
由於應用程式需要地點詳細資料 (舊版)，例如地點名稱、商家狀態或營業時間，因此實作地點自動完成 (舊版) 時，應使用工作階段符記 (以程式輔助方式或內建於 JavaScript、Android 或 iOS 小工具)。系統會根據您要求的地點資料欄位，按每個工作階段計費，並加上適用的 Places Data SKU。¹

透過小工具導入
JavaScript、Android 或 iOS 小工具自動內建工作階段管理功能，其中包含對已選取的預測結果提出的 Place Autocomplete (舊版) 要求和 Place Details (舊版) 要求。請務必指定 fields 參數，確保您只要求所需的地點資料欄位。

透過程式輔助方式導入
搭配 Place Autocomplete (舊版) 要求使用工作階段符記。要求所選預測結果的相關 Place Details (舊版) 時，請加入下列參數：

1. Place Autocomplete (舊版) 回應中的地點 ID
2. Place Autocomplete (舊版) 要求中使用的工作階段符記
3. 指定所需地點資料欄位的 fields 參數

否，只需要地址和位置資訊

對您的應用程式而言，Geocoding API 可能比 Place Details (舊版) 更符合成本效益，視 Place Autocomplete (舊版) 使用效能而定。每個應用程式的 Place Autocomplete (舊版) 效率各不相同，可能取決於使用者輸入的內容、使用應用程式的位置，以及是否採用效能最佳化最佳做法。

為了找出以下問題的解答，請分析使用者在應用程式中選取 Place Autocomplete (舊版) 預測結果前，平均輸入的字元數量。

使用者是否會在平均四次以內的要求中選取 Place Autocomplete (舊版) 預測結果？

是

透過程式輔助方式導入 Place Autocomplete (舊版)，但不使用工作階段符記，並針對已選取的地點預測結果呼叫 Geocoding API。
Geocoding API 提供地址和經緯度座標。提出四次 Place Autocomplete (舊版) - Per Request 要求，加上所選地點預測結果的相關 Geocoding API 呼叫，費用會低於 Place Autocomplete (舊版)「按工作階段」計價的每個工作階段費用¹。

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

否

搭配 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 (舊版) 時，請加入下列參數：

1. Place Autocomplete (舊版) 回應中的地點 ID
2. Place Autocomplete (舊版) 要求中使用的工作階段符記
3. 指定地址和幾何圖形等 Basic Data 欄位的 fields 參數

考慮延後 Place Autocomplete (舊版) 要求
您可以運用一些策略，例如將 Place Autocomplete (舊版) 要求延後到使用者輸入三或四個字元時再開始，藉此減少應用程式提出要求數量。舉例來說，如果使用者輸入第三個字元後，您就為每個字元提出 Place Autocomplete (舊版) 要求，那麼使用者輸入七個字元後，您為所選預測結果提出一次 Geocoding API 要求，總費用就會是 4 次 Place Autocomplete (舊版) Per Request + Geocoding。¹

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

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

---

1. 如要瞭解費用，請參閱 Google 地圖平台價目表。

效能最佳做法

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

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