Text Search 可根據字串傳回一組地點的相關資訊。例如「臺北披薩」、「渥太華附近的鞋店」或「中正路 123 號」。這項服務會傳回與文字字串和任何已設定的位置自訂調整相符的地點清單。
此服務特別適合在自動化系統中執行明確的地址查詢,而字串的非地址元件可能會比對商家和地址。模稜兩可的地址查詢是格式有誤的地址,或包含非地址元件 (例如商家名稱) 的要求。除非已設定位置 (例如區域、位置限製或位置自訂調整),否則前兩個範例類似的要求可能不會傳回結果。
「英國 10 號」或「美國中正路 123 號」 | 英國的多個「高街」;美國的多個「中正路」。 如未設定位置限制,查詢就不會傳回理想的結果。 |
「臺北市中餐廳」 | 紐約有多個「中菜餐廳」地點,沒有街道地址或街道名稱。 |
「10 High Street, Escher UK」或「123 Main Street, Pleasanton US」 | 英國埃塞爾 (Escher) 的英國城市「高街」;在加州普萊桑頓市內只有一個「Main Street」(主街)。 |
「UniqueRestaurantName New York」 | 紐約只能有一間名稱的建築物,不需要街道地址即可區分。 |
「臺北市的披薩店」 | 這項查詢包含地點限制,而「披薩餐廳」是定義明確的地點類型。並傳回多項結果。 |
「+1 514-670-8700」 | 這項查詢包含電話號碼。並傳回多個與該電話號碼相關聯的地點結果。 |
透過文字搜尋取得地點清單
呼叫 GMSPlacesClient
searchByTextWithRequest:
,並傳遞定義要求參數和 GMSPlaceSearchByTextResultCallback
類型的回呼方法的 GMSPlaceSearchByTextRequest
物件,即可發出 Text Search 要求來處理回應。
GMSPlaceSearchByTextRequest
物件會指定要求的所有必要和選用參數。必要參數包括:
- 要在
GMSPlace
物件中傳回的欄位清單,也稱為「欄位遮罩」,由GMSPlaceProperty
定義。如果未在欄位清單中指定至少一個欄位,或者省略欄位清單,呼叫會傳回錯誤。 - 文字查詢。
這個文字搜尋要求範例會指定回應中的 GMSPlace
物件,包含搜尋結果中每個 GMSPlace
物件的地點名稱和地點 ID。也會篩選回應,只傳回「餐廳」類型的地點。
Swift
// Create the GMSPlaceSearchByTextRequest object. let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID]; let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties) request.isOpenNow = true request.includedType = "restaurant" request.maxResultCount = 5 request.minRating = 3.5 request.rankPreference = .distance request.isStrictTypeFiltering = true request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue] request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2D(latitude: 20, longitude: 30), CLLocationCoordinate2D(latitude: 40, longitude: 50) ) // Array to hold the places in the response placeResults = []; let callback: GMSPlaceSearchByTextResultCallback = { [weak self] results, error in guard let self, error == nil else { if let error { print(error.localizedDescription) } return } guard let results = results as? [GMSPlace] else { return } self.placeResults = results } GMSPlacesClient.shared().searchByTextWithRequest(with: request, callback: callback)
Objective-C
// Create the GMSPlaceSearchByTextRequest object. GMSPlaceSearchByTextRequest *request = [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]]; request.isOpenNow = YES; request.includedType = @"restaurant"; request.maxResultCount = 5; request.minRating = 3.5; request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance; request.isStrictTypeFiltering = YES; request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ]; request.locationRestriction = GMSPlaceRectangularLocationOption( CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50)); request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.0); // Array to hold the places in the response _placeResults = [NSArray array]; // Create the GMSPlaceSearchByTextRequest object. [_placesClient searchByTextWithRequest:request callback:^(NSArray<GMSPlace *> _Nullable placeResults, NSError * _Nullable error) { if (placeResults.count > 0) { // Get list of places. _placeResults = placeResults; } }];
GooglePlacesSwift
let restriction = RectangularLocationRestriction( northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30), southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50) ) let searchByTextRequest = SearchByTextRequest( textQuery: "pizza in New York", placeProperties: [ .name, .placeID ], locationRestriction: restriction, includedType: .restaurant, maxResultCount: 5, minRating: 3.5, priceLevels: [ .moderate, .inexpensive ], isStrictTypeFiltering: true ) switch await placesClient.searchByText(with: searchByTextRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
Text Search 回應
Text Search API 會以 GMSPlace
物件的形式傳回相符陣列,每個相符地點各有一個 GMSPlace
物件。
除了資料欄位以外,回應中的 GMSPlace
物件還包含下列成員函式:
-
isOpen
會計算地點在指定時間是否營業。 isOpenAtDate
會計算地點在指定日期是否營業。
必要參數
請使用 GMSPlaceSearchByTextRequest
物件指定搜尋的必要參數。
-
欄位清單
指定要傳回的地點資料屬性。請傳遞
GMSPlace
屬性清單,指定要傳回的資料欄位。如果省略欄位遮罩,要求就會傳回錯誤。欄位清單很適合用來確保您不會要求不必要的資料,這有助於避免不必要的處理時間和帳單費用。
指定下列一或多個欄位:
下列欄位會觸發 Text Search (ID Only) SKU:
GMSPlacePropertyPlaceID
、GMSPlacePropertyName
下列欄位會觸發 Text Search (基本) SKU:
GMSPlacePropertyAddressComponents
、GMSPlacePropertyBusinessStatus
、GMSPlacePropertyFormattedAddress
、GMSPlacePropertyIconBackgroundColor
、GMSPlacePropertyIconImageURL
、GMSPlacePropertyCoordinate
、GMSPlacePropertyPhotos
、GMSPlacePropertyPlusCode
、GMSPlacePropertyTypes
、GMSPlacePropertyUTCOffsetMinutes
、GMSPlacePropertyViewport
、GMSPlacePropertyWheelchairAccessibleEntrance
下列欄位會觸發 Text Search (進階) SKU:
GMSPlacePropertyCurrentOpeningHours
、GMSPlacePropertySecondaryOpeningHours
、GMSPlacePropertyPhoneNumber
、GMSPlacePropertyPriceLevel
、GMSPlacePropertyRating
、GMSPlacePropertyOpeningHours
、GMSPlacePropertyUserRatingsTotal
、GMSPlacePropertyWebsite
下列欄位會觸發 Text Search (Preferred) SKU:
GMSPlacePropertyCurbsidePickup
、GMSPlacePropertyDelivery
、GMSPlacePropertyDineIn
、GMSPlacePropertyEditorialSummary
、GMSPlacePropertyReservable
、GMSPlacePropertyReviews
、GMSPlacePropertyServesBeer
、GMSPlacePropertyServesBreakfast
、GMSPlacePropertyServesBrunch
、GMSPlacePropertyServesDinner
、GMSPlacePropertyServesLunch
、GMSPlacePropertyServesVegetarianFood
、GMSPlacePropertyServesWine
、GMSPlacePropertyTakeout
-
textQuery
要搜尋的文字字串,例如「餐廳」、「中正路 123 號」或「臺北最佳觀光景點」。
自選參數
請使用 GMSPlaceSearchByTextRequest
物件指定搜尋的選用參數。
includedType
將結果限制在符合表 A 定義的指定類型的地點。您只能指定一個類型。例如:
request.includedType = "bar"
request.includedType = "pharmacy"
isOpenNow
如果設為
true
,則只傳回傳送查詢時營業中的地點。如為false
,則無論營業狀態為何,都傳回所有商家。 如果將這個參數設為false
,系統就會傳回未在 Google 地點介面集資料庫中指定營業時間的地點。isStrictTypeFiltering
與
includeType
參數搭配使用。如果設為true
,系統只會傳回符合includeType
指定類型的地點。設為 false 時,回應可能會包含與指定類型不符的地點。locationBias
指定要搜尋的區域。這個位置只是自訂調整,因此可傳回指定位置附近的結果,包括指定區域以外的結果。
您可以指定
locationRestriction
或locationBias
,但不能同時指定兩者。您可以將locationRestriction
視為指定結果必須位於哪個區域,而locationBias
則能指定結果必須鄰近但可以超出該區域的區域。請將區域指定為矩形可視區域或圓形。
圓形是由中心點和半徑 (以公尺為單位) 所定義。半徑必須介於 0.0 至 50000.0 (含) 之間。預設半徑為 0.0。例如:
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.0)
矩形是指經緯度可視區域,以對角線和低點的對角線表示。低點會標示矩形的西南角,高點則代表矩形的東北角。
系統會將可視區域視為封閉區域,也就是包含邊界。緯度邊界必須介於 -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
,緯度範圍會是空白。
- 如果
locationRestriction
指定要搜尋的區域。系統不會傳回指定區域以外的結果。將區域指定為矩形可視區域。如要瞭解如何定義可視區域,請參閱
locationBias
的說明。您可以指定
locationRestriction
或locationBias
,但不能同時指定兩者。您可以將locationRestriction
視為指定結果必須位於哪個區域,而locationBias
則能指定結果必須鄰近但可以超出該區域的區域。-
maxResultCount
指定要傳回的地點結果數量上限。必須介於 1 至 20 (預設) 之間 (含 1 至 20)。
minRating
限制只傳回平均使用者評分大於或等於這個上限的結果。值必須介於 0.0 至 5.0 (含) 之間,以 0.5 為單位。例如:0、0.5、1.0、...、5.0 (含)。值會無條件進位至最接近的 0.5 倍數。舉例來說,如果值是 0.6,則會刪除評分低於 1.0 的所有結果。
-
priceLevels
僅搜尋標有特定價格等級的地點。預設設定是選取所有價位。
指定
PriceLevel
定義的一或多個值陣列。例如:
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
rankPreference
依據查詢類型指定結果在回應中的排名方式:
- 如果是「紐約市餐廳」這類類別查詢,系統預設會使用
.relevance
(依照搜尋關聯性為搜尋結果排名)。您可以將rankPreference
設為.relevance
或.distance
(按照距離排名結果)。 - 如果是非類別查詢,例如「Mountain View, CA」,建議不設定
rankPreference
。
- 如果是「紐約市餐廳」這類類別查詢,系統預設會使用
regionCode
用於設定回應格式的區碼,以 雙字元 CLDR 代碼值指定。這個參數也可能會對搜尋結果造成偏誤。沒有預設值。
如果回應中地址欄位的國家/地區名稱與區碼相符,系統就會從地址中排除國家/地區代碼。
大部分 CLDR 代碼與 ISO 3166-1 代碼相同,只有一些值得注意的例外狀況。舉例來說,英國的 ccTLD 是「uk」(.co.uk),而其 ISO 3166-1 代碼卻是「gb」(正式的國名是「大不列顛暨北愛爾蘭聯合王國」)。這個參數會根據適用法律影響結果。
在應用程式中顯示作者資訊
如果應用程式顯示從 GMSPlacesClient
取得的資訊 (例如相片和評論),也必須顯示必要的作者資訊。
舉例來說,GMSPlacesClient
物件的 reviews
屬性包含最多包含五個 GMSPlaceReview
物件的陣列。每個 GMSPlaceReview
物件都可以包含作者和作者資訊。如果您在應用程式中顯示評論,您也必須顯示所有作者資訊或作者資訊。
詳情請參閱歸因相關說明文件。