地點自動完成

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Places SDK for Android 中的自動完成服務會根據使用者搜尋查詢傳回地點預測。使用者輸入時,自動完成服務會傳回地點、地址、加號代碼和搜尋點等地點的建議。

您可以透過下列方式新增自動完成功能:

新增自動完成小工具

自動完成小工具是內建自動完成功能的搜尋對話方塊。當使用者輸入搜尋字詞時,小工具就會顯示預測選項清單。使用者做出選擇時,系統會傳回 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

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

      

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

      

做法 2:使用意圖啟動自動完成活動

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

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

  1. 使用 Autocomplete.IntentBuilder 建立意圖,並傳送所需的 Autocomplete 模式。意圖必須呼叫 startActivityForResult,並傳入識別意圖的要求代碼。
  2. 覆寫 onActivityResult 回呼以接收所選地點。

建立自動完成意圖

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

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // 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);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // 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)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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

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

覆寫 onActivityResult 回呼

如要在使用者選取地點時接收通知,應用程式應覆寫活動的 onActivityResult(),並檢查您傳遞的意圖要求代碼,如以下範例所示。

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

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

您可以建立自訂搜尋 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() 的完整呼叫。

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")
        .setTypeFilter(TypeFilter.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());
        }
    });

      

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")
            .setTypeFilter(TypeFilter.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 中傳回 FindAutocompletePredictionsResponseFindAutocompletePredictionsResponse 包含 AutocompletePrediction 物件清單,代表預測的地點。如果與查詢和篩選器條件沒有已知的已知位置,清單就會留空。

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

  • getFullText(CharacterStyle) 會傳回地點說明的全文。此為主要和次要文字的組合。範例:「&ifft Tower, Avenue Anatole France, Paris, France」)此外,此方法可讓您使用 CharacterStyle,以醒目的方式顯示與搜尋條件相符的說明區段。CharacterStyle 為選用參數。如果您不需要醒目顯示,請設為空值。
  • getPrimaryText(CharacterStyle) 會傳回描述地點的主要文字。通常是地點名稱。例如:「Eiffel Tower」和「123 Pitt Street」
  • getSecondaryText(CharacterStyle) 會傳回地點說明的子文字。舉例來說,顯示自動完成預測時,第二行即可派上用場。例如:「&venuet, Avenue Anatole France, Paris, Canada」和「Sydney, New South Wales」"。
  • getPlaceId() 會傳回預測地點的地點 ID。地點 ID 是可識別地點的文字 ID,可用來日後再次擷取 Place 物件。如要進一步瞭解 Places SDK for Android 中的地點 ID,請參閱 Place Details。如需地點 ID 的一般資訊,請參閱 Place ID 總覽
  • getPlaceTypes() 會傳回與這個地點相關聯的地點類型清單。
  • getDistanceMeters() 會傳回這個地點與要求中指定的起點之間的直線距離 (以公尺為單位)。

工作階段符記

為求計費,工作階段符記會將使用者自動完成搜尋的查詢和選取階段分組為不同的工作階段。工作階段會在使用者開始輸入查詢時開始,並在使用者選取地點時結束。每個工作階段可以有多個查詢,然後再選取一個地點。工作階段結束後,權杖就不再有效;您的應用程式必須為每個工作階段產生即時權杖。建議您為所有程式輔助自動完成工作階段使用工作階段符記 (當您嵌入片段時,或使用意圖啟動自動完成功能時,API 會自動處理這項作業)。

Places SDK for Android 會使用 AutocompleteSessionToken 來識別每個工作階段。應用程式會在每個新工作階段開始時傳送新的工作階段符記,然後針對後續的 fetchPlace() 呼叫傳遞相同的權杖,以及地點 ID,擷取使用者所選地點的 Place Details。

進一步瞭解工作階段符記

限制自動完成結果

您可以將自動完成結果限制為特定地理區域,並/或篩選結果至一或多個地點類型,或最多五個國家/地區。您可以將這些限制套用至自動完成活動、AutocompleteSupportFragment 和程式輔助自動完成 API。

如要限制結果,請執行下列操作:

  • 如要偏好在定義的區域內傳回結果,請呼叫 setLocationBias() (系統可能仍會傳回定義區域外的部分結果)。
  • 如果「只顯示」定義區域內的結果,請呼叫 setLocationRestriction() (系統只會傳回定義區域內的結果)。
  • 如要只傳回符合特定地點類型的結果,請呼叫 setTypeFilter() (例如指定 TypeFilter.ADDRESS 只會傳回包含精確地址的結果)。
  • 如要只傳回最多五個指定國家/地區的結果,請呼叫 setCountries()。國家/地區必須以兩個字元搭配 ISO 3166-1 Alpha-2 相容國家/地區代碼

偏誤到特定區域的結果

如要將自動完成結果調整為特定地理區域,請呼叫 setLocationBias() 並傳遞 RectangularBounds。以下程式碼範例說明在片段執行個體上呼叫 setLocationBias(),會將自動完成建議調整為澳洲雪梨的區域。

Java


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

      

Kotlin


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

      

限制只查看特定區域的搜尋結果

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

Java


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

      

Kotlin


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

      

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

依地點類型篩選結果

您可以從自動完成要求中限制結果,只傳回特定地點類型。如果結果未受到限制,則系統會傳回所有類型。一般來說,只允許一種類型。唯一的例外情況是,您可以安全地混合使用 GEOCODEESTABLISHMENT 類型;不過,這與指定未指定類型的效果相同。

如要篩選特定地點類型的自動完成結果,請呼叫 setTypeFilter() 來設定要使用的篩選器。接著,將篩選器傳送至片段或意圖。

以下程式碼範例顯示了在 AutocompleteSupportFragment 上呼叫 setTypeFilter(),以設定僅傳回一個精確地址的結果。

Java


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS);

      

Kotlin


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS)

      

以下程式碼範例顯示了在 IntentBuilder 上呼叫 setTypeFilter(),以設定僅傳回精確地址的結果。

Java


    Intent intent = new Autocomplete.IntentBuilder(
        AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

如需地點類型的相關資訊,請參閱地點類型指南。

依國家/地區篩選結果

如要篩選最多 5 個國家/地區的自動完成結果,請呼叫 setCountries() 來設定國家/地區代碼。 接著,將篩選器傳送至片段或意圖。國家/地區必須以兩個字元搭配 ISO 3166-1 Alpha-2 相容國家/地區代碼

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

Java


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

      

Kotlin


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

      

用量限制

使用 Places API (包括 Places SDK for Android) 已達到每日要求數量上限 (QPD)。但仍須遵守以下用量限制:

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

在應用程式中顯示歸因方式

  • 如果應用程式是以程式輔助方式使用自動完成服務,則使用者介面必須顯示 '由 Google 技術提供' 歸因,或顯示在 Google 品牌地圖中。
  • 如果您的應用程式使用自動完成小工具,則無須採取其他行動 (根據預設顯示必要的屬性)。
  • 如果您在依 ID 取得地點後擷取及顯示其他地點資訊,您也必須顯示第三方資訊來源。

詳情請參閱歸因說明文件。

地點自動完成最佳化

本節將說明最佳做法,協助您充分運用 Place Autocomplete 服務。

幾項通則如下:

  • 若想開發有效的使用者介面,最快的方法就是使用 Maps JavaScript API Autocomplete 小工具、Places SDK for Android Autocomplete 小工具或 Places SDK for iOS Autocomplete UI Control
  • 從一開始就瞭解重要的 Place Autocomplete 資料欄位
  • 位置偏誤和位置限制欄位為選填欄位,但對自動完成效能可能會有重大影響。
  • 使用錯誤處理機制,確保 API 傳回錯誤時,應用程式優雅降級。
  • 請確保在沒有選取項目的情況下,應用程式會處理,並為使用者提供繼續的方式。

成本最佳化最佳做法

基本費用最佳化

為了最佳化 Place Autocomplete 服務的使用費用,請使用 Place Details 和 Place Autocomplete 小工具中的欄位遮罩,只傳回您需要的地點資料欄位

進階費用最佳化

考慮以程式輔助的方式實作 Place Autocomplete 功能,以存取按請求計費,並針對所選地點 (而不是 Place Details) 要求 Geocoding API 結果。如果同時符合以下兩個條件,則與 Geocoding API 搭配使用的「按要求計費」價格較單次工作階段 (按工作階段) 定價更佳:

  • 如果您只需要使用者所選地點的經緯度,
  • 如果使用者在平均 4 個自動完成預測要求之間選取自動完成預測,則「每個要求」的定價可能會比「按工作階段的定價」更符合成本效益。
如要選取符合您需求的 Place Autocomplete 導入方式,請選取與下列問題答案對應的分頁標籤。

應用程式是否要求所選預測地址的地址和緯度以外的任何資訊?

是,我需要更多詳細資料

搭配工作階段詳細資料使用以工作階段為基礎的 Place Autocomplete 功能。
由於您的應用程式需要地點詳細資料 (例如地點名稱、商家狀態或營業時間),導入 Place Autocomplete 功能時,應使用工作階段符記 (程式輔助或內建於 JavaScriptAndroidiOS 小工具),通常費用為 $0.017 美元每個工作階段,以及適用的 Places Data SKU}}}

小工具實作
工作階段管理會自動內建至
JavaScriptAndroidiOS 小工具中。包含所選預測的 Place Autocomplete 要求和 Place Details 要求。請務必指定 fields 參數,確保只要求所需的地點資料欄位

程式輔助導入
將「工作階段符記」用於 Place Autocomplete 要求。要求所選預測的 Place Details 時,請加入下列參數:

  1. 地點自動完成回應的地點 ID
  2. 「地點自動完成」要求中使用的工作階段符記
  3. fields 參數會指定你需要的地點資料欄位

否,只需要提供地址和位置

視「地點自動完成」使用效能的效能而定,Geocoding API 的應用程式成本可能比「地點詳細資料」更具成本效益。每個應用程式的自動完成效率會因使用者輸入的內容、應用程式使用位置,以及是否導入效能最佳化最佳做法而異。

為了回答以下問題,請先在應用程式中分析使用者輸入的字元平均數量,然後再選取 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 Autocomplete 功能。
由於使用者選取 Place Autocomplete 預測所需的平均要求數量,超出了每工作階段的費用,因此導入 Place Autocomplete 要求時,您必須同時使用工作階段符記和相關聯的 Place Details 要求,但每個工作階段的總費用為 $0.017 美元1

小工具實作
工作階段管理會自動內建至 JavaScriptAndroidiOS 小工具中。包含所選預測的 Place Autocomplete 要求和 Place Details 要求。請務必指定 fields 參數,確保您只要求 Basic Data 欄位。

程式輔助導入
將「工作階段符記」用於 Place Autocomplete 要求。要求所選預測的 Place Details 時,請加入下列參數:

  1. 地點自動完成回應的地點 ID
  2. 「地點自動完成」要求中使用的工作階段符記
  3. fields 參數,指定地址和幾何圖形等基本資料欄位

考慮延後 Place Autocomplete 要求
您可以利用策略來延遲 Place Autocomplete 要求,直到使用者輸入前 3 或 4 個半形字元時,再要求應用程式減少要求。舉例來說,在使用者輸入第三個字元「之後」,系統會為每個字元發出 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 功能附有地圖,您就可以根據地圖可視區域,偏誤位置。
  • 如果使用者未選擇其中一個自動完成預測功能,一般而言,由於這些預測作業都不是預期的結果地址,您可以重複使用原始使用者輸入內容,取得更相關的搜尋結果:
    • 如果您預期使用者只能輸入地址資訊,請在 Geocoding API 呼叫中重複使用原始的使用者輸入內容。
    • 如果您預期使用者可透過名稱或地址輸入特定地點的查詢內容,請使用「尋找地點」要求。 如果希望只在特定區域取得結果,請使用位置偏誤功能。
    但最適合使用 Geocoding API 的其他情境包括:
    • 使用者輸入澳洲、紐西蘭或加拿大以外的國家/地區。舉例來說,自動完成功能不支援美國地址「123 Bowdoin St #456, Boston MA, USA"」。(自動完成功能僅支援澳洲、紐西蘭和加拿大的子公司位址。這三種國家/地區支援的地址格式包括「91321 Pitt Street, Sydney, New South Wales, Australia」或「14/19 Langana Avenue, Browns Bay, Auckland, New Zealand」或「145-112 Renfrew Dr, Markham, Ontario, Canada&」
    • 使用者輸入的地址含有地址區隔前置字串,例如「11-20 29th St, Queens」(位於紐約市,臺北市中正區或臺北市中正區路四段 47-380 號),這組目的地包括位於夏威夷考奈島 (Kaaiai)。

疑難排解

雖然可能發生各種錯誤,但應用程式可能會遇到的大部分錯誤通常都是由設定錯誤 (例如使用錯誤的 API 金鑰,或 API 金鑰設定錯誤) 或配額錯誤 (應用程式已超出配額)。如要進一步瞭解配額,請參閱使用限制

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