Text Search 可根據字串 (例如「臺北披薩」或「渥太華附近的鞋店」或「中正路 123 號」) 傳回一組地點的相關資訊。這項服務會傳回與文字字串和位置自訂調整設定相符的地點清單。
此服務特別適合用於自動化系統中模糊的地址查詢,且字串的非地址元件可能與商家和地址相符。模稜兩可的地址查詢範例包括格式不正確的地址,或是包含非地址元件 (例如商家名稱) 的要求。前兩個範例的要求可能會傳回零結果,除非已設定位置 (例如區域、位置限製或位置自訂調整)。
「10 High Street, UK」或「123 Main Street, US」 | 英國有多個「高街」,美國境內還有多條「主要街道」。 除非已設定位置限制,否則查詢不會傳回符合需求的結果。 |
「臺北中國菜」 | 在紐約有多個「連鎖餐廳」地點;沒有街道地址或甚至街道名稱。 |
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 | 英國 Escher 城市中只有一號「高街」,在美國普萊森頓市只有一道「主要街道」。 |
「Unique 餐廳 Name 紐約」 | 在紐約只使用一間名稱的建築物,不需要區分街道地址。 |
「臺北披薩餐廳」 | 這項查詢包含地點限制,而「披薩餐廳」是定義明確的地點類型。這個方法會傳回多個結果。 |
「+1 514-670-8700」 | 這項查詢包含電話號碼。針對與該電話號碼相關聯的地點,傳回多筆結果。 |
Text Search 要求
Text Search 要求的格式為:
// Specify the list of fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Define latitude and longitude coordinates of the search area. LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874); LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572); // Use the builder to create a SearchByTextRequest object. final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields) .setMaxResultCount(10) .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build(); // Call PlacesClient.searchByText() to perform the search. // Define a response handler to process the returned List of Place objects. placesClient.searchByText(searchByTextRequest) .addOnSuccessListener(response -> { List<Place> places = response.getPlaces(); });
在這個例子中,您會:
將欄位清單設為只包含
Place.Field.ID
和Place.Field.NAME
。也就是說,回應中的Place
物件,代表每個相符地點都只包含這兩個欄位。使用
SearchByTextRequest.Builder
建立用於定義搜尋的SearchByTextRequest
物件。將文字查詢字串設為「Spicy Vegetarian Food」。
將結果地點數量上限設為 10 個。預設值為 20。
將搜尋區域限制在由經緯度座標定義的矩形中。不會傳回這個區域以外的相符項目。
新增
OnSuccessListener
並從SearchByTextResponse
物件取得相符地點。
Text Search 回應
SearchByTextResponse
類別代表搜尋要求的回應。SearchByTextResponse
物件包含:
代表所有相符地點的
Place
物件清單,每個相符地點只有一個Place
物件。每個
Place
物件都只包含由要求傳遞的欄位清單定義的欄位。
例如,在要求中,您將欄位清單定義為:
// Specify the list of fields to return. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
這個欄位清單表示回應中的每個 Place
物件,都只包含每個相符地點的地點 ID 和名稱。接著,您可以使用 Place.getId()
和 Place.getName()
方法存取每個 Place
物件中的這些欄位。
如需存取 Place
物件中資料的更多範例,請參閱「存取地點物件資料欄位」一文
必要參數
-
欄位清單
指定要傳回的地點資料欄位。傳遞
Place.Field
值清單,指定要傳回的資料欄位。回應中沒有傳回欄位的預設清單。欄位清單是不錯的設計做法,可避免要求不必要的資料,避免不必要的處理時間和帳單費用。
請指定下列一或多個欄位:
下列欄位會觸發文字搜尋 (僅限 ID) SKU:
Place.Field.ID
、Place.Field.NAME
下列欄位會觸發 Text Search (Basic) SKU:
Place.Field.ADDRESS_COMPONENTS
、Place.Field.BUSINESS_STATUS
、Place.Field.ADDRESS
、Place.Field.ICON_BACKGROUND_COLOR
、Place.Field.ICON_URL
、Place.Field.LAT_LNG
、Place.Field.PHOTO_METADATAS
、Place.Field.PLUS_CODE
、Place.Field.TYPES
、Place.Field.UTC_OFFSET
、Place.Field.VIEWPORT
、Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
下列欄位會觸發 Text Search (Advanced) SKU:
Place.Field.CURRENT_OPENING_HOURS
、Place.Field.SECONDARY_OPENING_HOURS
、Place.Field.PHONE_NUMBER
、Place.Field.PRICE_LEVEL
、Place.Field.RATING
、Place.Field.OPENING_HOURS
、Place.Field.USER_RATINGS_TOTAL
、Place.Field.WEBSITE_URI
下列欄位會觸發 Text Search (Preferred) SKU:
Place.Field.CURBSIDE_PICKUP
、Place.Field.DELIVERY
、Place.Field.DINE_IN
、Place.Field.EDITORIAL_SUMMARY
、Place.Field.RESERVABLE
、Place.Field.REVIEWS
、Place.Field.SERVES_BEER
、Place.Field.SERVES_BREAKFAST
、Place.Field.SERVES_BRUNCH
、Place.Field.SERVES_DINNER
、Place.Field.SERVES_LUNCH
、Place.Field.SERVES_VEGETARIAN_FOOD
、Place.Field.SERVES_WINE
、Place.Field.TAKEOUT
-
文字查詢
要搜尋的文字字串,例如「餐廳」、「中正路 123 號」或「臺北最好去的地點」。API 會根據這個字串傳回候選相符項目,並會依據觀察到的關聯性排序結果。
自選參數
使用 SearchByTextRequest.Builder
的方法設定這些參數。舉例來說,如要設定結果數量上限,請呼叫 SearchByTextRequest.Builder.setMaxResultCount()
。
包含的類型
讓系統在結果中只限於符合表 A 定義的指定類型的地點。只能指定一種類型。例如:
setIncludedType("bar")
setIncludedType("pharmacy")
位置自訂調整
指定要搜尋的區域。這個位置可以做為自訂調整,這表示系統會傳回指定位置周圍的結果,包括指定區域以外的結果。
您可以指定位置限製或位置自訂調整,但只能擇一。請將位置限制視為指定結果必須落在哪個區域,以及位置自訂調整,就像指定結果的附近地區,但可以位於該區域之外。
將區域指定為矩形可視區域或圓形。
圓形是由中心點和半徑 (以公尺為單位) 所定義。半徑必須介於 0.0 到 50000.0 (含) 之間。預設半徑為 0.0。例如:
// Define latitude and longitude coordinates of the center of the search area. LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874); // Use the builder to create a SearchByTextRequest object. // Set the radius of the search area to 500.0 meters. final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields) .setMaxResultCount(10) .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();
矩形是經緯度可視區域,以兩條對角線對角線和高點對稱。低點標記矩形的西南角,高點則代表矩形的東北角。
系統會將可視區域視為封閉區域,也就是涵蓋區域的邊界。緯度邊界必須介於 -90 到 90 度 (含) 之間,且經度邊界必須介於 -180 到 180 度 (含) 之間:
- 如果
low
=high
,可視區域由該單一點組成。 - 如果
low.longitude
>high.longitude
,經度範圍會反轉 (可視區域與 180 度的經度線相交)。 - 如果
low.longitude
= -180 度且high.longitude
= 180 度,可視區域會包含所有經度。 - 如果
low.longitude
= 180 度且high.longitude
= -180 度,則經度範圍為空白。 - 如果
low.latitude
>high.latitude
,則緯度範圍是空白。
必須填入最低和高的值,代表的方塊不得留空。空白的可視區域會導致錯誤。
以矩形可視區域為例,請參閱「搜尋文字要求」。
- 如果
地區限制
指定要搜尋的區域。系統不會傳回指定區域以外的結果。將區域指定為矩形可視區域。如要瞭解如何定義可視區域,請參閱位置自訂調整的說明。
您可以指定位置限製或位置自訂調整,但只能擇一。位置限制就像是指定結果所在的區域,以及位置自訂調整,就像指定結果的附近地區,但可以位於該區域之外。
-
結果數量上限
指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設) 之間。
最低評分
限制系統只傳回使用者平均評分大於或等於這個上限的結果。值必須介於 0.0 至 5.0 (含) 之間,以 0.5 為單位。例如:0、0.5、1.0、...、5.0 (含頭尾)。值會無條件進位至最接近的 0.5 倍數。舉例來說,如果值為 0.6,則會排除評分小於 1.0 的所有結果。
營業中
如果設為
true
,則僅傳回在查詢時營業中的地點。如果設為false
,則會傳回所有商家 (不論營業狀態為何)。 如果您將這個參數設為false
,系統會傳回 Google 地點介面集資料庫中未指定營業時間的地點。-
價位
將搜尋範圍限制在特定價格等級的地點。 預設設定是選取所有價位。
指定以下一或多個整數值的清單:
- 1 -
PRICE_LEVEL_INEXPENSIVE
- 2 -
PRICE_LEVEL_MODERATE
- 3 至
PRICE_LEVEL_EXPENSIVE
個 - 4 -
PRICE_LEVEL_VERY_EXPENSIVE
- 1 -
排名偏好
指定結果在回應中的排名方式。根據預設,API 會使用
RELEVANCE
(如適用)。舉例來說,如果是「臺北餐廳」這類查詢,則預設值為RELEVANCE
。如果是地理區域查詢 (例如「加州山景城」),或其他類型的查詢,系統不會套用任何預設值,而且結果會依照後端傳回的順序顯示。相關的值包括:
SearchByTextRequest.RankPreference.DISTANCE
:按照距離排名結果。SearchByTextRequest.RankPreference.RELEVANCE
:依關聯性將結果排名。
區域代碼
用於設定回應格式的區碼,指定為 雙字元 CLDR 代碼值。此外,這項參數也會對搜尋結果產生偏誤。沒有預設值。
如果回應中地址欄位的國家/地區名稱與區碼相符,則地址會省略國家/地區代碼。
大多數 CLDR 代碼與 ISO 3166-1 代碼相同,只有少數例外。舉例來說,英國的 ccTLD 是「uk」(.co.uk),而 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。根據適用法律,這個參數可能會影響結果。
嚴格類型篩選
與 include 類型參數搭配使用。如果設為
true
,系統只會傳回與納入類型指定類型相符的地點。預設值為false
時,回應可能包含與指定類型不符的地點。