Text Search (新版) 可根據字串 (例如「台南魯肉飯」、「西門町附近的鞋店」或「中正路 123 號」),傳回一組地點的相關資訊。這項服務會傳回與文字字串及位置自訂調整設定相符的地點清單。
此服務特別適合在自動化系統中執行明確的地址查詢,而字串的非地址元件可能會比對商家和地址。模稜兩可的地址查詢是格式有誤的地址,或包含非地址元件 (例如商家名稱) 的要求。除非已設定地區、位置限製或位置自訂調整等位置,否則前兩個範例等要求可能會傳回零結果。
Text Search (新版) 和 Nearby Search (新版) 類似。兩者的主要差異在於,Text Search (新版) 可讓您指定任意搜尋字串,而 Nearby Search (新版) 需要搜尋的特定區域。
「英國 10 號」或「美國中正路 123 號」 | 英國的多個「高街」;美國的多個「中正路」。 如未設定位置限制,查詢就不會傳回理想的結果。 |
「臺北市中餐廳」 | 紐約有多個「中菜餐廳」地點,沒有街道地址或街道名稱。 |
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 | 英國埃塞爾 (Escher) 的英國城市「高街」;在加州普萊桑頓市內只有一個「Main Street」(主街)。 |
「UniqueRestaurantName New York」 | 紐約只能有一間名稱的建築物,不需要街道地址即可區分。 |
「臺北市的披薩店」 | 這項查詢包含地點限制,而「披薩餐廳」是定義明確的地點類型。並傳回多項結果。 |
「+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
物件資料的範例,請參閱「存取地點物件資料欄位」
必要參數
SearchByTextRequest
的必要參數如下:
-
欄位清單
指定要傳回的地點資料欄位。請傳遞
Place.Field
值清單,指定要傳回的資料欄位。回應中沒有傳回欄位的預設清單。欄位清單很適合用來確保您不會要求不必要的資料,這有助於避免不必要的處理時間和帳單費用。
指定下列一或多個欄位:
下列欄位會觸發 Text Search (ID Only) SKU:
Place.Field.ID
、Place.Field.NAME
下列欄位會觸發 Text Search (基本) 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 (進階) 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
如要設定欄位清單參數,請在建構
SearchByTextRequest
物件時呼叫setPlaceFields()
方法。 -
文字查詢
要搜尋的文字字串,例如「餐廳」、「中正路 123 號」或「臺北最佳觀光景點」。API 會根據這個字串傳回候選相符項目,並會依據觀察到的關聯性排序結果。
如要設定文字查詢參數,請在建立
SearchByTextRequest
物件時呼叫setTextQuery()
方法。
自選參數
使用 SearchByTextRequest
物件指定要求的選用參數。
納入的類型
將結果限制在符合表 A 定義的指定類型的地點。您只能指定一個類型。例如:
setIncludedType("bar")
setIncludedType("pharmacy")
如要設定隨附的類型參數,請在建立
SearchByTextRequest
物件時呼叫setIncludedType()
方法。位置自訂調整
指定要搜尋的區域。這個位置只是自訂調整,因此可傳回指定位置附近的結果,包括指定區域以外的結果。
您可以指定位置限製或位置自訂調整,但不能同時指定兩者。您可以將位置限制視為指定結果所在的區域,以及位置自訂調整指定結果必須鄰近但可以超出該區域的區域。
請將區域指定為矩形可視區域或圓形。
圓形是由中心點和半徑 (以公尺為單位) 所定義。半徑必須介於 0.0 至 50000.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
,緯度範圍會是空白。
這個值必須填入下限和高,代表方塊不得留空。空白的可視區域會導致錯誤。
舉例來說,如果是矩形可視區域,請參閱「Text Search 要求」。
如要設定位置自訂調整參數,請在建立
SearchByTextRequest
物件時呼叫setLocationBias()
方法。- 如果
地區限制
指定要搜尋的區域。系統不會傳回指定區域以外的結果。將區域指定為矩形可視區域。如要瞭解如何定義可視區域,請參閱位置自訂調整的說明。
您可以指定位置限製或位置自訂調整,但不能同時指定兩者。您可以將位置限制視為指定結果所在的區域,以及位置自訂調整指定結果必須鄰近但可以超出該區域的區域。
如要設定位置限制參數,請在建立
SearchByTextRequest
物件時呼叫setLocationRestriction()
方法。-
結果數量上限
指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設) 之間 (含 1 至 20)。
如要設定結果計數上限參數,請在建立
SearchByTextRequest
物件時呼叫setMaxResultCount()
方法。 最低評分
限制只傳回平均使用者評分大於或等於這個上限的結果。值必須介於 0.0 至 5.0 (含) 之間,以 0.5 為單位。例如:0、0.5、1.0、...、5.0 (含)。值會無條件進位至最接近的 0.5 倍數。舉例來說,如果值是 0.6,則會刪除評分低於 1.0 的所有結果。
如要設定最低評分參數,請在建立
SearchByTextRequest
物件時呼叫setMinRating()
方法。營業中
如果設為
true
,則只傳回傳送查詢時營業中的地點。如為false
,則無論營業狀態為何,都傳回所有商家。 如果將這個參數設為false
,系統就會傳回未在 Google 地點介面集資料庫中指定營業時間的地點。如要設定開放立即使用的參數,請在建構
SearchByTextRequest
物件時呼叫setOpenNow()
方法。-
價位
根據預設,搜尋結果會包含不限價位服務的地點。如要將結果限制於特定價格等級的地點,您可以傳遞與待傳回地點價格等級對應的整數值清單:
1
- 地點提供低價服務。2
- 地點提供定價一般的服務。3
- 地點提供昂貴的服務。4
- 地點提供價格高昂的服務。
如要設定價格等級參數,請在建立
SearchByTextRequest
物件時呼叫setPriceLevels()
方法。 排名偏好設定
依據查詢類型指定結果在回應中的排名方式:
- 如果是「紐約市餐廳」這類類別查詢,系統預設會使用
SearchByTextRequest.RankPreference.RELEVANCE
(依照搜尋關聯性為搜尋結果排名)。您可以將排名偏好設為SearchByTextRequest.RankPreference.RELEVANCE
或SearchByTextRequest.RankPreference.DISTANCE
(按照距離排名結果)。 - 如果是非類別查詢,例如「Mountain View, CA」,建議你不要設定排名偏好設定參數。
如要設定排名偏好設定參數,請在建立
SearchByTextRequest
物件時呼叫setRankPreference()
方法。- 如果是「紐約市餐廳」這類類別查詢,系統預設會使用
區域代碼
用於設定回應格式的區碼,以 雙字元 CLDR 代碼值指定。這個參數也可能會對搜尋結果造成偏誤。沒有預設值。
如果回應中地址欄位的國家/地區名稱與區碼相符,系統就會從地址中排除國家/地區代碼。
大部分 CLDR 代碼與 ISO 3166-1 代碼相同,只有一些值得注意的例外狀況。舉例來說,英國的 ccTLD 是「uk」(.co.uk),而其 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。這個參數會根據適用法律影響結果。
如要設定區碼參數,請在建立
SearchByTextRequest
物件時呼叫setRegionCode()
方法。嚴格類型篩選
與 include 類型參數搭配使用。如果設為
true
,系統只會傳回符合納入類型指定類型的商家。如果預設為false
,回應會包含與指定類型不符的地點。如要設定嚴格類型篩選參數,請在建立
SearchByTextRequest
物件時呼叫setStrictTypeFiltering()
方法。