Place Autocomplete

Places SDK for Android 中的自動完成服務會傳回地點 來回應使用者的搜尋查詢使用者輸入時， 自動完成服務會傳回地點的建議，例如商家、 地址、plus code 和 搜尋點。

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

• 如要儲存，請新增 Autocomplete 小工具 並確保使用者體驗保持一致
• 取得地點預測結果 以程式輔助的方式 量身打造使用者體驗

新增 Autocomplete 小工具

自動完成小工具是內建自動完成功能的搜尋對話方塊 功能。使用者輸入搜尋字詞時，小工具會顯示 預測可供選擇的地點使用者做出選擇後 Place敬上 例項，應用程式就能使用該例項來取得 選取的地點

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

• 方法 1：嵌入 AutocompleteSupportFragment。
• 方法 2：使用意圖啟動 Autocomplete 活動。

選項 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：

    // 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 小工具，請按照下列步驟操作：

1. 使用 Autocomplete.IntentBuilder 建立意圖，傳遞所需的 Autocomplete 模式。
2. 定義活動結果啟動器 registerForActivityResult敬上 可用來啟動意圖和處理使用者選取的位置 預測結果

建立 Autocomplete 意圖

下列範例使用 Autocomplete.IntentBuilder敬上 建立意圖，以意圖啟動 Autocomplete 小工具：

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

      

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

註冊意圖結果的回呼

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

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

      

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

您可以建立自訂搜尋使用者介面，做為 自動完成小工具。也就是說，應用程式必須取得地點預測結果 編寫程式應用程式可取得預測的地點名稱和/或 呼叫自動完成 API 的地址 PlacesClient.findAutocompletePredictions()、 傳送 FindAutocompletePredictionsRequest 並包含以下參數：

• 必要：query 字串，包含使用者輸入的文字。
• 建議：A AutocompleteSessionToken、 ，將使用者搜尋的查詢和選取階段歸類為離散 來處理帳單工作階段是從使用者開始輸入時起算 此過程直到使用者選取地點時結束。
• 建議：RectangularBounds 物件，這個物件會指定經緯度邊界，以限制結果 指定區域。
• 選填：一或多個兩個字母的國家/地區 code (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()。

    // 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 會傳回 FindAutocompletePredictionsResponse敬上 在 Task。FindAutocompletePredictionsResponse 包含一份 AutocompletePrediction 代表預測地點的物件如果沒有 對應到查詢和篩選條件的已知地點。

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

• getFullText(CharacterStyle)敬上 會傳回地點說明的全文。這是 主要和次要文字範例：「Eiffel Tower, Avenue Anatole France, 法國巴黎」一文。此外，這個方法 描述與指定樣式相符的描述，並使用 CharacterStyle。 CharacterStyle 為選用參數，如果不是，請設為空值 需要醒目顯示任何資料
• getPrimaryText(CharacterStyle)敬上 會傳回地點的主要文字。這通常是 。例如：「艾菲爾鐵塔」和「123 Pitt Street」。
• getSecondaryText(CharacterStyle)敬上 會傳回地點說明的子公司文字。這非常實用 例如顯示自動預測結果的第二行範例： 「Avenue Anatole France, Paris, France」和「Sydney, New South Wales」。
• getPlaceId()敬上 會傳回預測地點的地點 ID。地點 ID 是文字 可識別特定地點的專屬 ID，可用來擷取 這個 Place敬上 物件。如要進一步瞭解地點 ID，請參閱 Places SDK for Android，請參閱 Place SDK for Android 詳情。一般問題 地點 ID 相關資訊，請參閱 Place ID 總覽頁面。
• getPlaceTypes()敬上 會傳回與此地點相關聯的地點類型清單。
• getDistanceMeters()敬上 會傳回這個地點與 指定來源。

工作階段符記

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

Places SDK for Android 使用 AutocompleteSessionToken敬上 辨別每個工作階段您的應用程式應在 每個新工作階段都開始，然後將相同的符記連同地點 ID，傳遞至 之間的 fetchPlace()敬上 來擷取使用者所選地點的 Place Details。

進一步瞭解工作階段 符記

限制自動完成結果

您可以將自動完成結果限制在特定地理區域。 篩選出一或多個地點類型的結果，或最多五個國家/地區。個人中心 可以將這些限制條件套用至 Autocomplete 活動 AutocompleteSupportFragment 和程式輔助自動完成 API。

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

• 如要「偏好」指定區域內的結果，請呼叫 setLocationBias() (系統可能仍會傳回所定義區域以外的部分結果)。
• 如要只顯示定義區域內的結果，請呼叫 setLocationRestriction() (只有所定義區域內的結果將會 )。
• 如果只要傳回符合特定地點類型的結果，請呼叫 setTypesFilter() (例如，指定 TypeFilter.ADDRESS 會傳回 這類搜尋結果)
• 如果只要傳回最多 5 個指定國家/地區的結果，請呼叫 setCountries()。傳遞國家/地區時，請務必使用雙字元 ISO 3166-1 與 Alpha-2 相容的國家/地區 程式碼。

針對特定區域調整結果

如要針對特定地理區域調整自動完成結果，請呼叫 setLocationBias()，傳遞 RectangularBounds。 以下程式碼範例示範如何在片段中呼叫 setLocationBias() ，將自動完成建議調整成澳洲雪梨的某區域。

    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() 片段執行個體，將自動完成建議調整成雪梨的區域 澳洲。

    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 中的一種類型。如果指定 值，便無法指定表 1 或表 2 的值。如果 就會發生錯誤

以下程式碼範例會在setTypesFilter() AutocompleteSupportFragment 並指定多個類型值。

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

      

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

      

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

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

      

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

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

      

依國家/地區篩選結果

如要篩選最多 5 個國家/地區的自動完成結果，請呼叫 setCountries()敬上 設定國家/地區代碼。 然後將篩選器傳遞至片段或意圖。國家/地區必須以 雙字元，與 ISO 3166-1 Alpha-2 相容國家/地區 程式碼。

以下程式碼範例顯示，如何在setCountries() AutocompleteSupportFragment，設定篩選器只傳回 指定國家/地區。

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

      

    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 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() 即可取得狀態 訊息中。