本頁面由 Cloud Translation API 翻譯而成。

自動完成 (新推出)

選取平台： Android iOS JavaScript 網頁服務

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

舉例來說，您呼叫 Autocomplete 時，使用的會是字串，內含部分使用者輸入內容「Sicilian piz」，並使用搜尋區域僅適用於加州舊金山回應會包含與搜尋字串和搜尋區域相符的地點預測結果清單，例如名為「Sicilian Pizza Kitchen」的餐廳。

系統會將傳回的地點預測結果呈現給使用者，協助他們選擇所需地點。您可以提出 Place Details (新版) 要求，進一步瞭解任何傳回的地點預測資訊。

Autocomplete (New) 要求

應用程式可取得預測的地點名稱和/或呼叫自動完成 API 的地址 PlacesClient.findAutocompletePredictions(), 傳送 FindAutocompletePredictionsRequest 物件。以下範例顯示對 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());
        })
    );

注意：如要進一步瞭解如何初始化 PlacesClient，請參閱初始化 Places API 用戶端。

自動完成 (新版) 回覆

API 會傳回 FindAutocompletePredictionsResponse 風格 Task。 FindAutocompletePredictionsResponse 包含最多五個代表預測地點的 AutocompletePrediction 物件清單。如果沒有對應到查詢和篩選條件的已知地點。

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

getFullText(CharacterStyle) 會傳回地點說明的全文。這是主要文字和次要文字的組合。範例：「Eiffel Tower, Avenue Anatole 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 物件。如要進一步瞭解 Autocomplete 中的地點 ID，請參閱「Place Details (新版)」。一般問題地點 ID 相關資訊，請參閱 Place ID 總覽頁面。
getTypes() 會傳回與此地點相關聯的地點類型清單。
getDistanceMeters() 會傳回這個地點與指定來源。

必要參數

查詢

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

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

選用參數

主要類型

列出最多五個類型類型值的清單表 A 或表 B ，用來篩選回應中傳回的地點。地點必須符合指定的主要類型值，才能納入回應中。

每個地點只能有一種主要類型的主要類型表 A 或表 B 相關聯的。例如，主要類型可能是 "mexican_restaurant" 或 "steak_house"。

如有下列情況，要求就會遭到拒絕，並傳回 INVALID_REQUEST 錯誤：
- 指定的類型超過五個。
- 指定了任何無法辨識的類型。
如要設定主要類型參數，請呼叫 setTypesFilter() 方法。FindAutocompletePredictionsRequest
國家/地區

只納入指定國家/地區清單中的結果，該清單會以最多 15 個 ccTLD (「頂層網域」) 兩位字元值的清單形式指定。如果省略，則系統不會對回應套用任何限制。例如，如要將地區限制為德國和法國：

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

如要設定國家/地區參數，請呼叫 setCountries() 方法。FindAutocompletePredictionsRequest
輸入偏移

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

如要設定輸入偏移參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setInputOffset() 方法。
地區偏差或地區限制

您可以指定位置自訂調整或位置限制定義搜尋區域您可以將位置限制視為結果所在的區域，以及位置自訂調整為用於指定結果必須鄰近的區域。主要差異在於位置自訂調整，可能還是會傳回指定區域以外的結果。
- 位置自訂調整
  
  指定要搜尋的區域。這個位置是偏好設定，而非限制，因此系統仍可能會傳回指定區域外的結果。
  
  如要設定位置偏差參數，請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setLocationBias() 方法。
- 地區限制
  
  指定要搜尋的區域。系統不會傳回指定區域以外的結果。
  
  如要設定地點限制參數，請呼叫 setLocationRestriction() 方法。FindAutocompletePredictionsRequest
將位置自訂調整或位置限制區域指定為矩形可視區域或圓形
- 圓形的定義是中心點和半徑 (以公尺為單位)。半徑必須介於 0.0 和 50000.0 (含首尾)。預設值為 0.0。針對位置限制，您必須將半徑設為大於 0.0 的值。否則，要求不會傳回任何結果。
- 矩形是經緯度可視區域，以兩個 low 和 high 點對角線。我們將可視區域視為封閉區域，表示包含其邊界。緯度界限必須介於 -90 到 90 度 (含經度邊界) 之間必須介於 -180 到 180 度之間 (含首尾)：
  
  注意：支援的偏差類型會因您使用的 SDK 版本而異。CircularBounds 僅適用於 Autocomplete (新版)
  - 如果 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 錯誤。這個參數會根據適用法律影響結果。

如要設定區碼參數，請呼叫 setRegionCode() 方法。FindAutocompletePredictionsRequest
工作階段符記

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

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

如要設定工作階段符記參數，請呼叫 setSessionToken() 方法。FindAutocompletePredictionsRequest

若需更多資訊，請參閲工作階段符記。

自動完成 (新版) 範例

使用位置限制和位置自訂調整功能

系統預設會使用 IP 偏差控制搜尋範圍。透過 IP 自訂調整，API 會使用調整結果。您可以選擇使用 Location 限制或位置自訂調整，但不包含都能指定要搜尋的區域

地點限制可用來指定要搜尋的區域。指定範圍以外的結果。下例示範如何使用位置限制請求請求以半徑為 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 參數來限制來自要求是特定類型的要求，如表和表格 B：您可以最多包含五個值的陣列。如果省略，系統會傳回所有類型。

以下範例會指定「足球」查詢字串，並使用主要類型參數，將結果限制為 "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 (新版)。如果就必須使用 Google 地圖當您要顯示沒有地圖的自動完成 (新版) 服務，必須包含顯示於搜尋欄位/結果中的 Google 標誌。適用對象如需更多資訊，請參閱顯示 Google 標誌以及出處。

自動完成 (新推出)

Autocomplete (New) 要求

自動完成 (新版) 回覆

必要參數

查詢

選用參數

主要類型

國家/地區

輸入偏移

地區偏差或地區限制

位置自訂調整

地區限制

來源

區域代碼

工作階段符記

自動完成 (新版) 範例

使用位置限制和位置自訂調整功能

使用主要類型

使用來源

歸因