自動完成 (新推出)

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 中傳回 FindAutocompletePredictionsResponseFindAutocompletePredictionsResponse 包含最多五個代表預測地點的 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 (「頂層網域」) 兩位字元值的清單形式指定。如果省略,系統不會對回應套用任何限制。例如,如要將地區限制為德國和法國:

    如果同時指定 locationRestrictionincludedRegionCodes,結果會位於兩個設定的交集區域。

    如要設定國家/地區參數,請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setCountries() 方法。

  • 輸入偏移

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

    如要設定輸入偏移參數,請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setInputOffset() 方法。

  • 地區偏差或地區限制

    您可以指定地點偏好設定或地點限制 (但不能同時指定),用來定義搜尋區域。您可以將位置限制視為指定結果必須位於其中的區域,而位置偏差則是指定結果必須位於附近的區域。主要差異在於,使用位置偏好設定時,系統仍可能會傳回指定區域以外的結果。

    • 位置偏差

      指定要搜尋的區域。這個位置是偏好設定,而非限制,因此系統仍可能會傳回指定區域外的結果。

      如要設定位置偏差參數,請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setLocationBias() 方法。

    • 地區限制

      指定要搜尋的區域。系統不會傳回指定區域以外的結果。

      如要設定位置限制參數,請在建構 FindAutocompletePredictionsRequest 物件時呼叫 setLocationRestriction() 方法。

    將位置偏差或位置限制區域指定為矩形可視區域或圓形。

    • 圓形的定義是中心點和半徑 (以公尺為單位)。半徑必須介於 0.0 和 50000.0 之間 (含首尾)。預設值為 0.0。針對位置限制,您必須將半徑設為大於 0.0 的值。否則,要求不會傳回任何結果。

    • 矩形是經緯度可視區域,以兩個對角相反的 lowhigh 點表示。可視區域視為封閉區域,也就是包含邊界。緯度範圍必須介於 -90 到 90 度之間 (含首尾),經度範圍則需介於 -180 到 180 度之間 (含首尾):

      • 如果 low = high,可視區域就會包含該單一點。
      • 如果 low.longitude > high.longitude,經度範圍會反轉 (可視區域會跨越 180 度經線)。
      • 如果 low.longitude = -180 度且 high.longitude = 180 度,則可視區域會包含所有經度。
      • 如果 low.longitude = 180 度且 high.longitude = -180 度,則經度範圍為空白。

      lowhigh 都必須填入資料,且所代表的方塊不得空白。空白的檢視區會導致錯誤。

  • 來源

    計算到目的地的直線距離時所用的起點 (使用 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 標誌和出處來源」。