自動完成 (新推出)

Autocomplete (新版) 會在回應要求時傳回地點預測結果，要求中包含文字搜尋字串和控制搜尋區域的地理範圍。自動完成功能可比對輸入內容的完整字詞和子字串，解析地點名稱、地址和 Plus Codes。應用程式可在使用者輸入內容時傳送查詢，即時提供地點和查詢預測結果。

舉例來說，您可以使用含有部分使用者輸入內容的字串「Sicilian piz」做為輸入內容，呼叫 Autocomplete，並將搜尋範圍限制在加州舊金山。回應會包含符合搜尋字串和搜尋區域的地點預測清單，例如名為「Sicilian Pizza Kitchen」的餐廳。傳回的地點預測結果會顯示給使用者，協助他們選取所需地點。您可以發出 Place Details (New) 要求，取得任何傳回地點預測結果的詳細資訊。

您可以透過兩種主要方式，將 Autocomplete (New) 功能整合到應用程式中：

• 新增 Place Autocomplete 小工具：透過 PlaceAutocomplete 類別提供即時可用的搜尋自動完成體驗，在使用者輸入內容時顯示預測結果。
• 透過程式輔助方式取得地點預測結果：直接呼叫 API 擷取預測結果，並顯示在自訂使用者介面中。

新增 Place Autocomplete 小工具

如要更輕鬆地提供一致的 Place Autocomplete 體驗，您可以將 Place Autocomplete 小工具新增至應用程式。這個小工具提供專用的全螢幕介面，可處理使用者輸入內容、向使用者顯示地點預測結果，並將 AutocompletePrediction 物件傳回應用程式。接著，您可以發出 Place Details (New) 要求，取得任何地點預測結果的額外資訊。

與透過程式輔助方式取得地點預測結果類似，Place Autocomplete 小工具可讓您使用工作階段符記，將自動完成要求分組為工作階段，以用於計費。呼叫 setAutocompleteSessionToken() 為小工具建立意圖時，您可以傳遞會期權杖。如果您未提供工作階段權杖，小工具會為您建立權杖，您可以呼叫 getSessionTokenFromIntent() 存取權杖。如要進一步瞭解如何使用工作階段符記，請參閱「關於工作階段符記」。

如要在應用程式中加入「地點自動完成」小工具，請按照下列步驟操作：

1. (選用) 定義工作階段權杖。如未提供會期權杖，小工具會為您建立一個。

2. 使用所需參數和工作階段權杖定義 autocompleteIntent。

3. 定義 StartActivityForResult 的 ActivityResultLauncher。這個啟動器會處理自動完成活動傳回的結果。

4. 在 ActivityResultLauncher 的回呼中處理結果。這包括擷取 AutocompletePrediction 和 AutocompleteSessionToken (如果您尚未提供自己的)，處理錯誤，以及視需要發出 fetchPlace() 要求，取得地點的額外詳細資料。

5. 使用 placeAutocompleteActivityResultLauncher 啟動意圖

以下範例示範如何使用 Kotlin 和 Java 新增 Place Autocomplete 小工具：

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

自訂主題

例項化 Autocomplete 體驗時，您可以指定主題，覆寫任何預設樣式屬性。您可以自訂 Place Autocomplete 元件的顏色、字體、間距、邊框和圓角。預設值為 PlacesMaterialTheme。未覆寫的主題屬性會使用預設樣式。

您可以在 …/res/values/themes.xml 中定義主題覆寫。例如：

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

接著，您可以呼叫 setAutocompleteUiCustomization 參照覆寫樣式：

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

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

應用程式可以呼叫 PlacesClient.findAutocompletePredictions()，並傳遞 FindAutocompletePredictionsRequest 物件，從自動完成 API 取得預測的地點名稱和/或地址清單。以下範例顯示對 PlacesClient.findAutocompletePredictions() 的完整呼叫。

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Autocomplete (新版) 回應

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

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

• getFullText(CharacterStyle) 傳回地點說明的完整文字。這是主要和次要文字的組合。範例：「法國巴黎阿納托勒法蘭斯大道艾菲爾鐵塔」。此外，這個方法還可讓您使用 CharacterStyle，以您選擇的樣式醒目顯示與搜尋內容相符的說明部分。CharacterStyle 參數為選用參數。如果不需要任何醒目顯示，請將其設為空值。
• getPrimaryText(CharacterStyle)：傳回說明地點的主要文字。這通常是地點名稱。例如「艾菲爾鐵塔」和「123 Pitt Street」。
• getSecondaryText(CharacterStyle) 傳回地點說明的附屬文字。舉例來說，在顯示自動完成預測時，這項功能可做為第二行。範例：「法國巴黎阿納托爾法蘭斯大道」和「澳洲新南威爾斯州雪梨」。
• getPlaceId() 傳回預測地點的地點 ID。地點 ID 是用來識別特定地點的文字 ID，可用於日後再次擷取Place物件。如要進一步瞭解 Autocomplete 中的地點 ID，請參閱Place Details (新推出)。如需地點 ID 的一般資訊，請參閱「地點 ID 總覽」。
• getTypes() 傳回與這個地點相關聯的地點類型清單。
• getDistanceMeters() 傳回這個地點與要求中指定原點之間的直線距離 (以公尺為單位)。

必要參數

• 查詢

  要搜尋的文字字串。指定完整字詞和子字串、地點名稱、地址和 Plus Codes。Autocomplete (New) 服務會根據這個字串傳回候選相符項目，並依據觀察到的關聯性排序結果。

  如要設定查詢參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setQuery() 方法。

選用參數

• 主要類型

  最多可列出五個類型值，這些值來自表 A 或表 B，用於篩選回應中傳回的地點。地點必須符合其中一個指定的主要類型值，才會納入回應。

  一個地點只能有一個主要類型，且該類型必須來自表 A 或表 B。舉例來說，主要類型可能是 "mexican_restaurant" 或 "steak_house"。

  如有下列情況，要求就會遭拒，並傳回 INVALID_REQUEST 錯誤：

  • 指定超過五個類型。
  • 指定任何無法辨識的類型。

  如要設定主要類型參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setTypesFilter() 方法。

• 國家/地區

  只納入指定國家/地區清單中的結果，最多可指定 15 個ccTLD (「頂層網域」) 雙字元值。如果省略，系統不會對回覆套用任何限制。舉例來說，如要將地區限制為德國和法國，請執行下列操作：

  如果同時指定 locationRestriction 和 includedRegionCodes，結果會位於這兩項設定的交集區域。

  如要設定國家/地區參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setCountries() 方法。

• 輸入偏移

  以零為基準的 Unicode 字元位移值，表示查詢中的游標位置。 游標位置可能會影響系統傳回的預測結果。如果為空白，則預設為查詢長度。

  如要設定輸入位移參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setInputOffset() 方法。

• 地點偏誤或地點限制

  您可以指定地點偏好或地點限制 (但不能同時指定兩者)，定義搜尋範圍。您可以將地點限制視為指定結果必須位於的區域，而地點偏向設定則可視為指定結果必須靠近的區域。主要差異在於，使用地點偏誤時，系統仍可能會傳回指定區域外的結果。

  • 位置偏誤

    指定要搜尋的區域。這個位置是偏誤，而非限制，因此系統仍可能會傳回指定區域外的結果。

    如要設定位置偏誤參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setLocationBias() 方法。

  • 地點限制

    指定要搜尋的區域。系統不會傳回指定區域外的結果。

    如要設定位置限制參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setLocationRestriction() 方法。

  將地點偏誤或地點限制區域指定為矩形可視區域或圓形。

  • 圓形是由中心點和半徑 (以公尺為單位) 定義。半徑必須介於 0.0 至 50000.0 之間 (含首尾)。預設值為 0.0。如要限制地點，半徑必須設為大於 0.0 的值。否則要求不會傳回任何結果。

  • 矩形是經緯度可視區域，以兩個對角相對的 low 和 high 點表示。可視區域視為封閉區域，因此包含邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾)，經度範圍則必須介於 -180 到 180 度之間 (含首尾)：

    • 如果 low = high，可視區域就是該單一點。
    • 如果 low.longitude > high.longitude，經度範圍會反轉 (可視區域會跨越 180 度經度線)。
    • 如果 low.longitude = -180 度且 high.longitude = 180 度，可視區域會包含所有經度。
    • 如果 low.longitude = 180 度且 high.longitude = -180 度，經度範圍會空白。

    low 和 high 都必須填入值，且代表的方塊不得為空。如果檢視區塊為空白，就會發生錯誤。

• 來源

  計算目的地直線距離的起點 (使用 getDistanceMeters() 存取)。如果省略這個值，系統就不會傳回直線距離。必須指定為經緯度座標：

  如要設定來源參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setOrigin() 方法。

• 區域代碼

  用來格式化回應的區域碼，包括地址格式，指定為 ccTLD (「頂層網域」) 的兩位字元值。大多數 ccTLD 代碼與 ISO 3166-1 代碼相同，但有一些需要注意的例外情況。舉例來說，英國的 ccTLD 是「uk」(即 .co.uk)，而 ISO 3166-1 代碼是「gb」(技術上是指「大不列顛及北愛爾蘭聯合王國」實體的代碼)。

  如果指定無效的地區代碼，API 會傳回 INVALID_ARGUMENT 錯誤。根據適用法律，這項參數可能會影響結果。

  如要設定區域代碼參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setRegionCode() 方法。

• 工作階段符記

  工作階段符記是使用者產生的字串，可將透過小工具發出的呼叫和程式輔助呼叫，一併追蹤為「工作階段」。自動完成功能會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。工作階段是從使用者輸入查詢時開始，到使用者選取地點時結束。在每個工作階段中，使用者可以輸入多筆查詢，最終選擇一個地點。工作階段結束後，符記就會失效。您的應用程式必須為每個工作階段產生新的符記。建議您在所有程式輔助自動完成工作階段使用工作階段符記 (當您嵌入片段或使用意圖啟動自動完成功能時，API 會自動處理這項作業)。

  自動完成功能會使用 AutocompleteSessionToken 識別每個工作階段。應用程式應在每個新工作階段開始時傳遞新的工作階段符記，然後在後續呼叫 fetchPlace() 時，傳遞相同符記和地點 ID，以擷取使用者選取地點的地點詳細資料。

  如要設定會期權杖參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setSessionToken() 方法。

  詳情請參閱「工作階段符記」。

Autocomplete (新版) 範例

使用地點限制和地點偏誤

Autocomplete (新版) 預設會使用 IP 偏誤來控管搜尋區域。使用 IP 偏誤時，API 會使用裝置的 IP 位址來偏誤結果。您可以選擇使用位置限制或位置偏誤 (但不能同時使用)，指定要搜尋的區域。

地點限制會指定搜尋區域。系統不會傳回指定區域外的結果。以下範例使用位置限制，將要求限制在以舊金山為中心、半徑 5000 公尺的圓形位置限制內：

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

位置偏向功能會將位置當做偏向，也就是說，系統可能會傳回指定位置附近的結果，包括指定區域外的結果。下一個範例會變更先前的要求，改為使用位置偏誤：

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

使用主要類型

使用 primary types 參數，將要求結果限制為表 A 和表 B 中列出的特定類型。您最多可以指定五個值的陣列。如果省略，系統會傳回所有類型。

下列範例指定「Soccer」的查詢字串，並使用主要類型參數將結果限制為 "sporting_goods_store" 類型的場所：

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

如果省略主要類型參數，結果可能會包含您不想要的類型機構，例如 "athletic_field"。

使用來源

在要求中加入 origin 參數 (指定為經緯度座標) 時，API 會在回應中加入從起點到目的地的直線距離 (使用 getDistanceMeters() 存取)。 這個範例會將起點設為舊金山的中心：

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Autocomplete (新版) 最佳化

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

以下列出幾項一般準則：

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

費用最佳化最佳做法

基本費用最佳化

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

進階費用最佳化

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

• 如果您只需要針對使用者選取的地點取得經緯度或地址，透過 Geocoding API 擷取這項資訊，支付的費用會比使用 Place Details (New) 呼叫更低。
• 如果使用者在平均四次以內的自動預測結果要求選取了自動預測結果，則「按要求」計價可能會比「按工作階段」計價更符合成本效益。

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

效能最佳做法

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

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

位置偏誤

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

限制位置

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

您也可以新增 locationRestriction 參數，將結果限制在 location 和 radius 參數定義的區域內。這會指示 Autocomplete (New) 只傳回該區域內的結果。