Place Autocomplete (舊版)

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

Place Autocomplete (舊版) 會根據使用者的搜尋查詢，傳回地點預測結果。使用者輸入內容時，自動完成服務會傳回地點建議，例如商家、地址、Plus Codes 和搜尋點。

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

新增 Autocomplete 小工具

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

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

選項 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)。
  • 如果您使用自動完成片段，且需要覆寫 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.DISPLAY_NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            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.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(TAG, "An error occurred: " + status);
        }
    });

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

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

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

  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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .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.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);
    startAutocomplete.launch(intent);

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

在疊加模式下，自動完成小工具會疊加在呼叫 UI 上。
圖 1：OVERLAY 模式下的自動完成小工具
在全螢幕模式下，自動完成小工具會填滿整個螢幕。
圖 2：全螢幕模式下的自動完成小工具

註冊意圖結果的回呼

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

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } else if (result.resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
            binding.autocompleteResult.setText(R.string.user_canceled_autocomplete)
            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);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                binding.autocompleteResult.setText(R.string.user_canceled_autocomplete);
                Log.i(TAG, "User canceled autocomplete");
            }
        });

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

您可以建立自訂搜尋使用者介面，取代自動完成小工具提供的使用者介面。如要這麼做，應用程式必須透過程式輔助方式取得地點預測結果。應用程式可以呼叫 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.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            val builder = StringBuilder()
            for (prediction in response.autocompletePredictions) {
                builder.append(prediction.getPrimaryText(null).toString()).append("\n")
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
            binding.autocompleteResult.text = builder.toString()
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
                binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message)
            }
        }

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(List.of(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        StringBuilder builder = new StringBuilder();
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            builder.append(prediction.getPrimaryText(null).toString()).append("\n");
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
        binding.autocompleteResult.setText(builder.toString());
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException apiException) {
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            binding.autocompleteResult.setText(getString(R.string.place_not_found, apiException.getMessage()));
        }
    });

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

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

  • getFullText(CharacterStyle) 會傳回地點說明的完整文字。這是主要和次要文字的組合。例如：「Eiffel Tower, Avenue Anatole France, Paris, 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() 傳回這個地點與要求中指定原點之間的直線距離 (以公尺為單位)。

工作階段符記

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

Kotlin

        autocompleteFragment.setLocationBias(bounds)

Java

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

將結果限制在特定區域

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

Kotlin

        autocompleteFragment.setLocationRestriction(bounds)

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(List.of("landmark", "restaurant", "store"));

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

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Java

    autocompleteFragment.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));

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

Kotlin

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

Java

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .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 品牌地圖中。
  • 如果應用程式使用自動完成小工具，則不需採取任何額外動作 (系統預設會顯示必要的出處資訊)。
  • 如果您在依 ID 取得地點後，擷取並顯示其他地點資訊，也必須顯示第三方出處資訊。

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

Place Autocomplete (舊版) 最佳化

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

以下列出幾項一般準則：

  • 如要開發有效的使用者介面，最快的方法就是使用 Maps JavaScript API Place Autocomplete (舊版) 小工具、Places SDK for Android Place Autocomplete (舊版) 小工具，或 Places SDK for iOS Place Autocomplete (舊版) UI 控制項。
  • 從一開始就瞭解 Place Autocomplete (舊版) 的必要資料欄位。
  • 「位置自訂調整」和「位置限制」為自選欄位，但可能會對自動完成效能產生重大影響。
  • 使用錯誤處理機制，可以減輕 API 傳回錯誤時對應用程式效能造成的影響。
  • 確保應用程式能處理未選取任何項目的情況，以便使用者繼續操作。

費用最佳化最佳做法

基本費用最佳化

為了讓 Place Autocomplete (舊版) 服務費用發揮最大效益，請使用 Place Details (舊版) 和 Place Autocomplete (舊版) 小工具中的欄位遮罩，只傳回所需的 Place Autocomplete (舊版) 資料欄位。

進階費用最佳化

建議您透過程式輔助方式導入 Place Autocomplete (舊版)，採用 SKU：Autocomplete - Per Request 定價，並要求已選地點 (而非 Place Details (舊版)) 的相關 Geocoding API 結果。如果同時符合以下兩項條件，搭配 Geocoding API 使用「按要求」計價會比使用「按工作階段」(以工作階段為準) 計價更具成本效益：

  • 如果您只需要針對使用者選取的地點取得經緯度或地址，透過 Geocoding API 擷取這項資訊，支付的費用會比使用 Place Details (舊版) 呼叫更低。
  • 如果使用者在平均四次以內的 Place Autocomplete (舊版) 預測要求選取了自動預測結果，則「按要求」計價可能會比「按工作階段」計價更符合成本效益。
如要瞭解如何選取符合需求的 Place Autocomplete (舊版) 導入方式，請回答下列問題，並選取對應的分頁標籤。

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

是，需要更多詳細資料

搭配 Place Details (舊版) 使用以工作階段為準的 Place Autocomplete (舊版)。
由於您的應用程式需要 Place Details (舊版)，例如地點名稱、商家狀態或營業時間，因此 Place Autocomplete (舊版) 的實作方式應使用程式輔助或內建於 JavaScript、Android 或 iOS 小工具中的工作階段符記，每個工作階段加上適用的 Places Data SKU，視您要求哪些地點資料欄位而定。1

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

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

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

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

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

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

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

是

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

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

否

搭配 Place Details (舊版) 使用以工作階段為準的 Place Autocomplete (舊版)。
由於您預期在使用者選取 Place Autocomplete (舊版) 預測結果前發出的要求平均數量，會超過「按工作階段」計價的費用，因此 Place Autocomplete (舊版) 的實作應針對 Place Autocomplete (舊版) 要求和相關聯的 Place Details (舊版) 要求，使用工作階段符記進行按工作階段計價。 1

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

透過程式輔助方式導入
搭配 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。1

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

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

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

效能最佳做法

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

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

位置偏誤

傳送 location 參數和 radius 參數，針對特定區域調整結果。這會指示 Place Autocomplete (舊版)「優先」顯示指定區域內的結果。不過，系統還是有可能會顯示定義區域外的結果。您可以使用 includedRegionCodes 參數篩選結果，只顯示特定國家/地區內的地點。

位置限制

傳送 locationRestriction 參數，將結果限制在指定區域。

您也可以加入 strictbounds 參數，將結果限制在 location 和 radius 參數定義的區域內。這會指示 Place Autocomplete (舊版) 只傳回該區域內的結果。

疑難排解

雖然可能發生各種錯誤，但應用程式可能遇到的大多數錯誤通常是由設定錯誤 (例如，使用了錯誤的 API 金鑰，或 API 金鑰設定不正確) 或配額錯誤 (應用程式已超出配額) 引起。如要進一步瞭解配額，請參閱「用量限制」。

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