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

自動完成 (新推出)

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

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

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

傳回的地點預測結果旨在協助使用者讓他們選擇您想要的地點您可以製作 Place Details (新增) 要求更多任一傳回地點預測結果的相關資訊。

自動完成 (新版) 要求

應用程式可取得預測的地點名稱和/或呼叫自動完成 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 為選用參數，如果不需要，請設為空值即可醒目顯示任何醒目顯示的內容
getPrimaryText(CharacterStyle) 會傳回地點的主要文字。這通常是。例如：「艾菲爾鐵塔」和「123 Pitt Street」。
getSecondaryText(CharacterStyle) 會傳回地點說明的子公司文字。這非常實用例如顯示自動預測結果的第二行範例：「Avenue Anatole France, Paris, France」和「Sydney, New South Wales」。
getPlaceId() 會傳回預測地點的地點 ID。地點 ID 是文字可識別特定地點的專屬 ID，可用來擷取這個 Place 物件。如要進一步瞭解地點 ID，請參閱 Autocomplete，請參閱 Place Details (新功能)。一般問題地點 ID 相關資訊，請參閱 Place ID 總覽頁面。
getTypes() 會傳回與此地點相關聯的地點類型清單。
getDistanceMeters() 會傳回這個地點與指定來源。

必要參數

查詢

要搜尋的文字字串。指定完整字詞和子字串地點名稱、地址和 plus code。 Autocomplete (新版) 服務根據這個字串傳回候選相符項目，並會依據他們認為關聯性。

如要設定查詢參數，請呼叫 setQuery() 方法。FindAutocompletePredictionsRequest

選用參數

主要類型

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

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

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

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

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

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

從零開始的 Unicode 字元偏移值，指出遊標在查詢中的位置。遊標位置會影響傳回的預測查詢字串。如果空白，系統會預設為查詢的長度。

如要設定輸入偏移值參數，請呼叫 setInputOffset() 方法。FindAutocompletePredictionsRequest
位置自訂調整或位置限制

您可以指定位置自訂調整或位置限制定義搜尋區域您可以將位置限制視為結果所在的區域，以及位置自訂調整為用於指定結果必須鄰近的區域。主要差異在於位置自訂調整，可能還是會傳回指定區域以外的結果。
- 位置自訂調整
  
  指定要搜尋的區域。這個位置只是偏見而非限制，因此搜尋結果所指定的區域外，仍可能會傳回。
  
  如要設定位置自訂調整參數，請呼叫 setLocationBias() 方法。FindAutocompletePredictionsRequest
- 地區限制
  
  指定要搜尋的區域。不是指定區域以外的結果。
  
  如要設定地點限制參數，請呼叫 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() 存取)。如果此值為省略，不會傳回直線距離。必須指定為經緯度座標：

如要設定來源參數，請呼叫 setOrigin() 方法。FindAutocompletePredictionsRequest
區域代碼

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

注意：區域代碼代表要求的來源區域，不一定是查詢的目標區域。

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

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

工作階段符記是使用者產生的字串，可追蹤自動完成 (新) 呼叫做為「工作階段」。自動完成功能會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段帳單用途工作階段是從使用者開始輸入查詢，並在使用者選取地點時結束。每堂課可以包含多個查詢，緊接著選擇一個地點。工作階段套用完畢後得出結論，符記已失效。您的應用程式必須產生新的符記。建議您為所有程式輔助方式使用工作階段符記自動完成工作階段 (在嵌入片段或使用自動完成功能啟動自動完成工作階段時) 意圖，API 會自動處理這種情況)。

自動完成功能會使用 AutocompleteSessionToken 辨別每個工作階段您的應用程式應在每個新工作階段都開始，然後將相同的符記連同地點 ID，傳遞至對 fetchPlace() 的後續呼叫來擷取使用者所選地點的 Place Details。

如要設定工作階段符記參數，請呼叫 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 參數來限制來自要求是特定類型的要求，如表 A 和表格 B.您可以最多包含五個值的陣列。如果省略，系統會傳回所有類型。

以下範例會指定「足球」這個查詢字串並使用主要的 types 參數，將結果限制為類型建築物的結果 "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 標誌以及出處。

自動完成 (新推出)

自動完成 (新版) 要求

自動完成 (新版) 回應

必要參數

查詢

選用參數

主要類型

國家/地區

輸入偏移

位置自訂調整或位置限制

位置自訂調整

地區限制

來源

區域代碼

工作階段符記

自動完成 (新版) 範例

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

使用主要類型

使用來源

歸因