自動完成 (新推出)

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

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

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

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

Autocomplete (New) 要求

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

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

  • getFullText(CharacterStyle) 會傳回地點說明的完整文字。這是主要文字和次要文字的組合。例如：艾菲爾鐵塔，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 的一般資訊，請參閱「地點 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() 方法。

  • 工作階段符記

    工作階段符記是使用者產生的字串，可追蹤 Autocomplete (New) 呼叫的「工作階段」。Autocomplete 會使用工作階段符記，將使用者自動完成搜尋的查詢和選取階段歸入不同的工作階段，以用於計費。工作階段是從使用者輸入查詢時開始，到使用者選取地點時結束。在每個工作階段中，使用者可以輸入多筆查詢，最終選擇一個地點。工作階段結束後，符記就會失效；您的應用程式必須為每個工作階段產生新的符記。建議您在所有程式輔助自動完成工作階段中使用工作階段符記 (當您嵌入片段，或使用意圖啟動自動完成功能時，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」參數，將要求的結果限制為特定類型，如表 A和表 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 地圖。如果您要顯示 Autocomplete (New) 服務的預測結果，但不顯示地圖，則必須在搜尋欄位/結果中顯示 Google 標誌。詳情請參閱「顯示 Google 標誌和版權資訊」。