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 度之間 (含首尾):- 如果
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 標誌與作者資訊」。