自動完成 (新推出)

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

Autocomplete (New) 會在回應要求時傳回地點預測結果，該要求包含文字搜尋字串和用於控制搜尋範圍的地理邊界。Autocomplete 可比對輸入內容的完整字詞和子字串，解析地點名稱、地址和 plus code。應用程式可在使用者輸入內容時傳送查詢，即時提供地點和查詢預測結果。

舉例來說，您可以使用包含部分使用者輸入內容的字串 (「Sicilian piz」) 做為輸入內容，並將搜尋區域限制在加州舊金山。回應隨後會包含與搜尋字串和搜尋區域相符的地點預測結果清單，例如名為「Sicilian Pizza Kitchen」的餐廳。

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

自動完成 (新) 要求

應用程式可以呼叫 PlacesClient.findAutocompletePredictions()，傳遞 FindAutocompletePredictionsRequest 物件，從 Autocomplete 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 物件清單。如果沒有與查詢和篩選器條件相符的已知地點，清單可能會是空白的。

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

  • 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，請參閱「地點詳情 (新版)」。如需地點 ID 的一般資訊，請參閱「地點 ID 總覽」。
  • getTypes() 會傳回與此地點相關的地點類型清單。
  • getDistanceMeters() 會傳回此地點與要求中指定的起點之間的直線距離 (以公尺為單位)。

必要參數

  • 查詢

    要搜尋的文字字串。指定完整字詞和子字串、地點名稱、地址和加號代碼。Autocomplete (New) 服務會根據這個字串傳回候選相符項目，並依據相符程度排序結果。

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

選用參數

  • 主要類型

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

    地點只能有一個主要類型，來自與其相關聯的 Table A 或 Table 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 (「頂層網域」) 兩個字元的值指定。大多數的頂層國家/地區代碼與 ISO 3166-1 代碼相同，但也有少數例外狀況。舉例來說，英國的 ccTLD 是「uk」(.co.uk)，而 ISO 3166-1 代碼則是「gb」(技術上是「The United Kingdom of Great Britain and Northern Ireland」實體)。

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

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

  • 工作階段符記

    工作階段權杖是使用者產生的字串，可追蹤 Autocomplete (New) 呼叫為「工作階段」。自動完成功能會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段分組為個別工作階段，以便計費。工作階段會在使用者開始輸入查詢時開始，並在使用者選取地點時結束。每個工作階段可包含多個查詢，並接著進行一次地點選取作業。工作階段結束後，權杖就會失效；應用程式必須為每個工作階段產生新的權杖。建議您在所有程式輔助自動完成工作階段中使用工作階段符記 (當您嵌入片段或使用意圖啟動自動完成功能時，API 會自動處理這項作業)。

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

    如要設定工作階段權杖參數，請在建構 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());
        })
    );

使用主要類型

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

以下範例會指定「Soccer」查詢字串，並使用 primary_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());
        })
    );

歸因

即使沒有地圖，您還是可以使用自動完成 (新版)。如果您要顯示地圖，則必須是 Google 地圖。如果您在沒有地圖的情況下顯示自動完成 (新版) 服務的預測結果，則必須在搜尋欄位/結果中顯示 Google 標誌。詳情請參閱「顯示 Google 標誌和出處來源」。