Nearby Search (新版) 要求會將要搜尋的區域做為輸入內容,並以圓形表示,該圓形的定義取決於圓心點的經緯度座標,以及半徑 (以公尺為單位)。要求會傳回符合條件的地點清單,每個地點都由 GMSPlace
物件代表,位於指定搜尋範圍內。
根據預設,回應會包含搜尋區域內的所有類型地點。您可以選擇篩選回應,方法是指定要明確納入或排除回應中的地點類型清單。舉例來說,您可以指定回應中只包含類型為「餐廳」、「烘焙坊」和「咖啡廳」的場所,或是排除所有類型為「學校」的場所。
Nearby Search (新版) 要求
呼叫 GMSPlacesClient searchNearbyWithRequest:
即可提出附近搜尋要求,並傳遞定義要求參數的 GMSPlaceSearchNearbyRequest
物件,以及 GMSPlaceSearchNearbyResultCallback
類型的回呼方法,以便處理回應。
GMSPlaceSearchNearbyRequest
物件會指定要求的所有必要和選用參數。必要參數包括:
- 在
GMSPlace
物件中傳回的欄位清單,也稱為GMSPlaceProperty
定義的欄位遮罩。如果您未在欄位清單中指定至少一個欄位,或是省略欄位清單,則呼叫會傳回錯誤。 - 位置限制,也就是定義搜尋區域的圓形。
這個附近搜尋要求範例會指定回應 GMSPlace
物件包含搜尋結果中每個 GMSPlace
物件的位置名稱 (GMSPlacePropertyName
) 和位置座標 (GMSPlacePropertyCoordinate
)。並篩選回應,只傳回「餐廳」和「咖啡廳」類型的地點。
// Array to hold the places in the response var placeResults: [GMSPlace] = [] // Define the search area as a 500 meter diameter circle in San Francisco, CA. let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500) // Specify the fields to return in the GMSPlace object for each place in the response. let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue} // Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return. var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties) let includedTypes = ["restaurant", "cafe"] request.includedTypes = includedTypes let callback: GMSPlaceSearchNearbyResultCallback = { [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 } placeResults = results } GMSPlacesClient.shared().searchNearby(with: request, callback: callback)
// Array to hold the places in the response _placeResults = [NSArray array]; // Define the search area as a 500 meter diameter circle in San Francisco, CA. id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500); // Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return. GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc] initWithLocationRestriction:circularLocation placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]]; // Set the place types to filter on. NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ]; request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes]; [_placesClient searchNearbyWithRequest:request callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } else { // Get list of places. _placeResults = places; } } ];
let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500) let searchNearbyRequest = SearchNearbyRequest( locationRestriction: restriction, placeProperties: [ .name, .coordinate], includedTypes: [ .restaurant, .cafe ], ) switch await placesClient.searchNearby(with: searchNearbyRequest) { case .success(let places): // Handle places case .failure(let placesError): // Handle error }
Nearby Search 回應
Nearby Search API 會以GMSPlace
物件的形式傳回相符項目陣列,每個相符地點對應一個 GMSPlace
物件。取得開放狀態
GMSPlacesClient
物件包含名為 isOpenWithRequest
的會員函式 (在 Swift 中為 isOpenRequest
,在 GooglePlacesSwift 中為 isPlaceOpenRequest
),可根據呼叫中指定的時間,傳回回應,指出地點目前是否營業。
這個方法會使用單一 GMSPlaceIsOpenWithRequest
型別的引數,其中包含:
GMSPlace
物件,或指定地點 ID 的字串。如要進一步瞭解如何建立含有必要欄位的 Place 物件,請參閱「Place 詳細資料」。
- 選用的
NSDate
(Obj-C) 或Date
(Swift) 物件,可指定您要檢查的時間。如未指定時間,則預設為現在。 - 用於處理回應的
GMSPlaceOpenStatusResponseCallback
方法。 >
GMSPlaceIsOpenWithRequest
方法需要在 GMSPlace
物件中設定下列欄位:
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyBusinessStatus
GMSPlacePropertyOpeningHours
GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
如果 Place 物件未提供這些欄位,或是您傳遞地點 ID,該方法會使用 GMSPlacesClient GMSFetchPlaceRequest:
擷取這些欄位。
isOpenWithRequest
則回應
isOpenWithRequest
會傳回 GMSPlaceIsOpenResponse
物件,其中包含名為 status
的布林值,可指出商家是否營業、是否已關閉,或狀態不明。
語言 | 如果已開啟,則為值 | 關閉時的值 | 狀態不明時的值 |
---|---|---|---|
Swift | .open |
.closed |
.unknown |
Objective-C | GMSPlaceOpenStatusOpen |
GMSPlaceOpenStatusClosed |
GMSPlaceOpenStatusUnknown |
GooglePlacesSwift (預先發布版) | true |
false |
nil |
「isOpenWithRequest
」的帳單
- 系統會針對
GMSPlacePropertyUTCOffsetMinutes
和GMSPlacePropertyBusinessStatus
欄位收取 Basic Data SKU 費用。系統會根據 Place Details Enterprise SKU收取其他營業時間的費用。 - 如果
GMSPlace
物件已包含先前要求中的這些欄位,就不會再向您收費。
範例:提出 GMSPlaceIsOpenWithRequest
要求
以下範例說明如何在現有的 GMSPlace
物件中初始化 GMSPlaceIsOpenWithRequest
。let isOpenRequest = GMSPlaceIsOpenRequest(place: place, date: nil) GMSPlacesClient.shared().isOpen(with: isOpenRequest) { response, error in if let error = error { // Handle Error } switch response.status { case .open: // Handle open case .closed: // Handle closed case .unknown: // Handle unknown } }
GMSPlaceIsOpenRequest *isOpenRequest = [[GMSPlaceIsOpenRequest alloc] initWithPlace:place date:nil]; [[GMSPlacesClient sharedClient] isOpenWithRequest:isOpenRequest callback:^(GMSPlaceIsOpenResponse response, NSError *_Nullable error) { if (error) { // Handle error } switch (response.status) { case GMSPlaceOpenStatusOpen: // Handle open case GMSPlaceOpenStatusClosed: // Handle closed case GMSPlaceOpenStatusUnknown: // Handle unknown } }];
let isOpenRequest = IsPlaceOpenRequest(place: place) switch await placesClient.isPlaceOpen(with: isOpenRequest) { case .success(let isOpenResponse): switch isOpenResponse.status { case true: // Handle open case false: // Handle closed case nil: // Handle unknown case .failure(let placesError): // Handle error }
必要參數
使用 GMSPlaceSearchNearbyRequest
物件指定搜尋作業的必要參數。
-
欄位清單
要求地點詳細資料時,您必須在
GMSPlace
物件中指定要傳回的地點資料,並以欄位遮罩的形式呈現。如要定義欄位遮罩,請將值陣列從GMSPlaceProperty
傳遞至GMSPlaceSearchNearbyRequest
物件。欄位遮罩是良好的設計做法,可確保您不會要求不必要的資料,進而避免不必要的處理時間和帳單費用。指定下列一或多個欄位:
以下欄位會觸發 Nearby Search Pro SKU:
GMSPlacePropertyAddressComponents
GMSPlacePropertyBusinessStatus
GMSPlacePropertyCoordinate
GMSPlacePropertyFormattedAddress
GMSPlacePropertyName
GMSPlacePropertyIconBackgroundColor
GMSPlacePropertyIconImageURL
GMSPlacePropertyPhotos
GMSPlacePropertyPlaceID
GMSPlacePropertyPlusCode
GMSPlacePropertyTypes
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyViewport
GMSPlacePropertyWheelchairAccessibleEntrance
以下欄位會觸發 Nearby Search Enterprise SKU:
GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
GMSPlacePropertyPhoneNumber
GMSPlacePropertyPriceLevel
GMSPlacePropertyRating
GMSPlacePropertyOpeningHours
GMSPlacePropertyUserRatingsTotal
GMSPlacePropertyWebsite
以下欄位會觸發 Nearby Search Enterprise Plus SKU:
GMSPlacePropertyCurbsidePickup
GMSPlacePropertyDelivery
GMSPlacePropertyDineIn
GMSPlacePropertyEditorialSummary
GMSPlacePropertyReservable
GMSPlacePropertyReviews
GMSPlacePropertyServesBeer
GMSPlacePropertyServesBreakfast
GMSPlacePropertyServesBrunch
GMSPlacePropertyServesDinner
GMSPlacePropertyServesLunch
GMSPlacePropertyServesVegetarianFood
GMSPlacePropertyServesWine
GMSPlacePropertyTakeout
以下範例會傳遞兩個欄位值清單,指定要求傳回的
GMSPlace
物件包含name
和placeID
欄位:// Specify the place data types to return. let fields: [GMSPlaceProperty] = [.placeID, .name]
// Specify the place data types to return. NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
// Specify the place data types to return. let fields: [PlaceProperty] = [.placeID, .displayName]
-
locationRestriction
GMSPlaceLocationRestriction
物件會將要搜尋的區域定義為圓形,並以圓心和半徑 (以公尺為單位) 定義圓形。半徑必須介於 0.0 和 50000.0 之間 (含首尾)。預設半徑為 0.0。您必須在要求中將其設為大於 0.0 的值。
選用參數
使用 GMSPlaceSearchNearbyRequest
物件指定搜尋的選用參數。
-
includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes
讓您從 Table A 的類型指定用於篩選搜尋結果的類型清單。每個類型限制類別最多可指定 50 個類型。
地點只能有 單一主要類型,且該類型必須與 表格 A 中的類型相關聯。例如,主要類型可能是
"mexican_restaurant"
或"steak_house"
。使用includedPrimaryTypes
和excludedPrimaryTypes
篩選地點的主要類型結果。地點也可以有多個類型值,這些值來自與其相關聯的 表 A 類型。舉例來說,餐廳可能有以下類型:
"seafood_restaurant"
、"restaurant"
、"food"
、"point_of_interest"
、"establishment"
。使用includedTypes
和excludedTypes
篩選與地點相關聯的類型清單結果。指定一般主要類型 (例如
"restaurant"
或"hotel"
) 時,回應可能包含比指定類型更具體的類型。舉例來說,您可以指定要納入主要類型的"restaurant"
。回應可以包含主要類型為"restaurant"
的地點,但也可以包含主要類型更具體的地點,例如"chinese_restaurant"
或"seafood_restaurant"
。如果搜尋指定多個類型限制,系統只會傳回符合所有限制的場所。舉例來說,如果您指定
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
,則傳回的位置會提供"restaurant"
相關服務,但主要不會以"steak_house"
的形式運作。includedTypes
表 A 中要搜尋的地點類型清單。如果省略這個參數,系統會傳回所有類型的地點。
excludedTypes
表 A 中要排除的場所類型清單。
如果您在要求中同時指定
includedTypes
(例如"school"
) 和excludedTypes
(例如"primary_school"
),回應就會包含歸類為"school"
但非"primary_school"
的 Places。回應會包含與includedTypes
的至少一個和excludedTypes
的沒有一個相符的地點。如果有任何相衝突的類型,例如同時出現在
includedTypes
和excludedTypes
中的類型,系統會傳回INVALID_REQUEST
錯誤。includedPrimaryTypes
表 A中的主要地點類型清單,可用於搜尋。
excludedPrimaryTypes
表 A中的主要地點類型清單,用於在搜尋中排除。
如果有任何衝突的主要類型,例如
includedPrimaryTypes
和excludedPrimaryTypes
都出現同一個類型,系統會傳回INVALID_ARGUMENT
錯誤。 -
maxResultCount
指定要傳回的地點結果數量上限。必須介於 1 到 20 (預設值) 之間。
-
rankPreference
要使用的排名類型。如果省略這個參數,系統會依熱門程度排序結果。可能是下列其中一個值:
.popularity
(預設) 依據結果的熱門程度排序。.distance
依遞增順序排序結果,依據的是地點與指定位置之間的距離。
-
regionCode
用於格式化回應的區碼,指定為 兩個字元的 CLDR 代碼值。沒有預設值。
如果回應中
formattedAddress
欄位的國家/地區名稱與regionCode
相符,formattedAddress
就會省略國家/地區代碼。這個參數不會影響adrFormatAddress
(一律包含國家/地區名稱) 或shortFormattedAddress
(一律不包含國家/地區名稱)。大多數 CLDR 代碼與 ISO 3166-1 代碼相同,但有一些例外情況。舉例來說,英國的 ccTLD 是「uk」(.co.uk),而 ISO 3166-1 代碼是「gb」(技術上是「大不列顛與北愛爾蘭聯合王國」實體)。這個參數可能會影響根據適用法律產生的結果。
在應用程式中顯示出處資訊
如果應用程式會顯示從 GMSPlacesClient
取得的資訊 (例如相片和評論),則也必須顯示必要的出處資訊。
舉例來說,GMSPlacesClient
物件的 reviews
屬性包含最多五個 GMSPlaceReview
物件的陣列。每個 GMSPlaceReview
物件都包含歸屬資訊和作者歸屬資訊。如果您在應用程式中顯示評論,則必須一併顯示任何出處資訊或作者出處資訊。
詳情請參閱歸因說明文件。