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

自動完成 (新推出)

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

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

舉例來說，您可以使用輸入字串來呼叫 Autocomplete，且該字串內含部分使用者輸入內容「Sicilian piz」，且搜尋區域僅限於加州舊金山。回應隨後包含符合搜尋字串和搜尋區域的地點預測結果清單，例如名稱為「Sicilian Pizza Kitchen」的餐廳。

傳回的地點預測結果旨在協助使用者選取所需地點。您可以提出 Place Details (新版) 要求，取得任何傳回地點預測結果的詳細資訊。

自動完成 (新版) 要求

應用程式可以呼叫 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());
        })
    );

自動完成 (新版) 回應

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

針對每個預測的地點，您可以呼叫下列方法以擷取 Place Details：

getFullText(CharacterStyle) 會傳回地點說明的完整文字。這是主要和次要文字的組合。例如：「Eiffel Tower, Avenue Anatole France, Paris, France」。此外，此方法也可讓您使用 CharacterStyle，醒目顯示符合搜尋樣式的說明區段。CharacterStyle 為選用參數，如果您不需要任何醒目顯示，請設為空值。
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 的一般資訊，請參閱「地點 ID 總覽」。
getTypes() 會傳回與這個地點相關聯的地點類型清單。
getDistanceMeters() 會傳回這個地點與要求中指定的起點之間的直線距離 (以公尺為單位)。

必要參數

查詢

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

如要設定查詢參數，請在建立 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 度之間 (含首尾)：
  
  注意：支援的偏誤類型會因使用的 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 錯誤。這個參數會根據適用法律影響結果。

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

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

Autocomplete 使用 AutocompleteSessionToken 來識別各個工作階段。應用程式應在每個新的工作階段開始時傳遞新的工作階段符記，然後在後續對 fetchPlace() 的呼叫中傳遞相同的權杖和地點 ID，以擷取使用者所選地點的 Place Details。

如要設定工作階段符記參數，請在建立 FindAutocompletePredictionsRequest 物件時呼叫 setSessionToken() 方法。

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

自動完成 (新版) 範例

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

自動完成 (新版) 預設會使用 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());
        })
    );

使用主要類型

使用「主要類型」參數將要求的結果限制為特定類型的要求，如表 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 (新版)，如要顯示地圖，則必須使用 Google 地圖。如果不使用地圖的情況下，透過 Autocomplete (新版) 服務顯示預測結果，您必須加入顯示在搜尋欄位/結果中的 Google 標誌。詳情請參閱「顯示 Google 標誌與作者資訊」。

自動完成 (新推出)

自動完成 (新版) 要求

自動完成 (新版) 回應

必要參數

查詢

自選參數

主要類型

國家/地區

輸入偏移

位置自訂調整或位置限制

位置自訂調整

地區限制

來源

區域代碼

工作階段符記

自動完成 (新版) 範例

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

使用主要類型

使用來源

出處