Place Autocomplete

Places SDK for Android 的自動完成服務會根據使用者搜尋查詢傳回地點預測結果。在使用者輸入內容時,自動完成服務會傳回商家、地址、plus code 和搜尋點等地點的建議。

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

新增 Autocomplete 小工具

自動完成小工具是內建自動完成功能的搜尋對話方塊。當使用者輸入搜尋字詞時,小工具會提供預測地點清單,讓您選擇。使用者做出選擇時,系統會傳回 Place 執行個體,接著您的應用程式可以使用該例項取得所選地點的詳細資料。

在應用程式中新增 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) 中。
  • 如果您使用自動完成片段,且需要覆寫 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:使用意圖啟動自動完成活動

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

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

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

建立自動完成意圖

以下範例使用 Autocomplete.IntentBuilder 建立意圖來啟動 Autocomplete 小工具做為意圖:

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

      

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

在重疊模式中顯示時,自動完成小工具會疊加在呼叫 UI 上。
圖 1:OVERLAY 模式下的 Autocomplete 小工具
以全螢幕模式顯示時,自動完成小工具會填滿整個螢幕。
圖 2:在全螢幕模式下使用 Autocomplete 小工具

註冊意圖結果的回呼

如要在使用者選取地點時收到通知,請定義 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");
            }
        });

      

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

除了自動完成小工具提供的 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:只傳回與 LOCALITYADMINISTRATIVE_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 中傳回 FindAutocompletePredictionsResponseFindAutocompletePredictionsResponse 包含代表預測地點的 AutocompletePrediction 物件清單。如果沒有對應至查詢和篩選條件的已知地點,清單可能就不會顯示任何內容。

您可以呼叫下列方法,擷取每個預測地點的詳細資料:

  • getFullText(CharacterStyle) 會傳回地點說明的全文。此為主要與次要文字的組合。例如:「艾菲爾鐵塔, 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 物件。如要進一步瞭解 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(),以將自動完成建議調整為澳洲雪梨的地區。

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

      

注意:這項限制僅適用於整個路線,位於矩形邊界之外的合成結果可能會根據與位置限制重疊的路線傳回。

按照地點類型或集合類型篩選結果

您可以限制 Autocomplete 要求的結果,讓系統只傳回特定地點類型。請使用「地點類型」中表 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(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 次查詢 (每分鐘的要求數量)。計算方式為使用相同專案憑證的所有應用程式的用戶端和伺服器端要求總和。

在應用程式中顯示作者資訊

  • 如果您的應用程式以程式輔助方式使用自動完成服務,您的 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 Details 使用以工作階段為準的 Place Autocomplete。
您的應用程式會要求 Place Details (例如地點名稱、商家狀態或營業時間),因此在導入 Place Autocomplete 時,建議使用工作階段符記 (透過程式輔助方式,或是內建於 JavaScriptAndroidiOS 小工具),總費用為每個工作階段 $0.017 美元,再加上適用的地點資料 SKU (視您要求的地點資料欄位而定)1

透過小工具導入
JavaScriptAndroidiOS 小工具自動內建工作階段管理功能,其中包含對已選取的預測結果提出的 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,但不使用工作階段符記,並針對已選取的地點預測結果呼叫 Geocoding API。
Geocoding API 提供地址和經緯度座標,收費為每次要求 $0.005 美元。提出四次 Place Autocomplete - Per Request 要求的費用為 $0.01132 美元,因此如果將四次要求加上所選地點預測結果的相關 Geocoding API 呼叫,總費用就會是 $0.01632 美元,低於自動完成功能「按工作階段」計價的每個工作階段 $0.017 美元1

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

搭配 Place Details 使用以工作階段為準的 Place Autocomplete。
您預期使用者在選取 Place Autocomplete 預測結果前提出的平均要求數量,會超過「按工作階段」計價的費用,因此在導入 Place Autocomplete 時,建議針對 Place Autocomplete 要求和相關聯的 Place Details 要求都使用工作階段符記,總費用為每個工作階段 $0.017 美元1

透過小工具導入
JavaScriptAndroidiOS 小工具自動內建工作階段管理功能,其中包含對已選取的預測結果提出的 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 要求帶出的一筆預測結果,總費用就是 $0.01632 美元 (4 * $0.00283 Autocomplete Per Request + $0.005 美元 Geocoding)1

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

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


  1. 這裡列出的費用是以美元計算。如需完整計價資訊,請參閱「Google 地圖平台計費方式」頁面。

效能最佳做法

以下準則說明如何將 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() 以取得結果的狀態訊息。