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 標誌和出處來源」。