Place Autocomplete

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

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

• 新增自動完成小工具以節省開發時間，並確保使用者體驗一致。
• 透過程式輔助方式取得地點預測結果，藉此建立自訂的使用者體驗。

新增 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 中新增事件監聽器：

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

      

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

      

選項 2：使用意圖啟動自動完成活動

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

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

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

建立自動完成意圖

以下範例使用 Autocomplete.IntentBuilder 建立意圖，以便啟動自動完成小工具做為意圖：

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

      

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

      

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

為意圖結果註冊回呼

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

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

      

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

      

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

除了自訂小工具提供的 UI，您也可以建立自訂搜尋 UI。為此，您的應用程式必須透過程式輔助方式取得地點預測結果。應用程式可以呼叫 PlacesClient.findAutocompletePredictions() 並傳遞下列參數的 FindAutocompletePredictionsRequest 物件，藉此從自動完成 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() 的完整呼叫。

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

      

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

      

API 會在 Task 中傳回 FindAutocompletePredictionsResponse。FindAutocompletePredictionsResponse 包含 AutocompletePrediction 物件清單，代表預測地點。如果沒有符合查詢和篩選條件的條件，清單可能會空白。

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

• getFullText(CharacterStyle) 會傳回地點說明的完整文字。這是主要與次要文字的組合。例如：「Eiffel Tower, Avenue Anatole France, Paris, France」。此外，此方法還可讓您使用 CharacterStyle，以您選擇的方式醒目顯示符合搜尋樣式的區段。CharacterStyle 參數為選用項目。如果不需醒目顯示任何項目，請設為空值。
• getPrimaryText(CharacterStyle) 會傳回描述地點的主要文字。通常是地點的名稱。例如：「艾菲爾鐵塔」和「中正路 123 號」。
• getSecondaryText(CharacterStyle) 會傳回地點說明的子文字。舉例來說，在顯示自動完成預測時，例如第二行。例如：「A 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()，以向其澳洲雪梨的區域提供自動完成建議。

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

      

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

      

將結果限制在特定地區

如要將自動完成結果限制在特定的地理區域，請呼叫 setLocationRestriction() 並傳遞 RectangularBounds。以下程式碼範例顯示針對片段執行個體呼叫 setLocationRestriction()，以向其澳洲雪梨的區域提供自動完成建議。

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

      

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

      

注意：這項限制只會套用至整個路徑，系統可能會忽略在邊界邊界外的綜合結果，也就是根據位置限制重疊的路徑。

依據地點類型或類型集合篩選結果

您可以限制自動完成要求中的結果，只傳回特定地點類型。使用地點類型 1、2 和 3 列的地點類型指定篩選器。如未指定，則會傳回所有類型。

如要篩選自動完成結果，請呼叫 setTypesFilter() 來設定篩選器。

如何指定類型或類型集合篩選器：

• 呼叫 setTypesFilter() 表指定表 1 和資料表 2 中的類型值地點類型。類型值是由 PlaceTypes 中的常數定義。

• 呼叫 setTypesFilter()，並指定「地點類型」一文中表 3 的類型集合。集合值是由 PlaceTypes 中的常數定義。

  在要求中只能使用表 3 中的一種類型。如果您指定表 3 的值，就無法指定表 1 或資料表 2 的值。否則系統會發生錯誤。

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

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

      

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

      

以下程式碼範例示範如何在 AutocompleteSupportFragment 上呼叫 setTypesFilter()，以設定類型集合來設定只傳回包含精確地址結果的篩選器。

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

      

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

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

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

      

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

      

依國家/地區篩選結果

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

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

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

      

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

      

用量限制

Places API for Android 的用量限制 (包含 Places SDK for Android) 限制為每日要求數量上限 (QPD)。但仍須遵守下列用量限制：

• 頻率限制為每秒 100 個要求 (QPS)。這會針對使用相同專案憑證的所有應用程式，計算用戶端和伺服器端要求的總和。

在應用程式中顯示出處

• 如果應用程式透過程式輔助方式使用自動完成服務，則 UI 必須顯示「由 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 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() 以取得結果的狀態訊息。