「搜尋附近」(New) 要求會採用以圓形形式指定搜尋區域,由圓形中心點的經緯度座標及半徑 (以公尺為單位) 定義。該要求會在指定搜尋區域中傳回相符地點的清單,每個地點以 GMSPlace
物件表示。
根據預設,回應會包含搜尋區域中所有類型的地點。您可以選擇篩選回應,指定要在回應中明確加入或排除的地點類型清單。舉例來說,您可以指定只在回應中納入「餐廳」、「麵包店」和「咖啡店」類型的地點,也可以排除「學校」類型的所有地點。
Nearby Search (新) 要求
呼叫 GMSPlacesClient searchNearbyWithRequest:
並傳遞用於定義要求參數和回呼方法 (類型為 GMSPlaceSearchNearbyResultCallback
) 的 GMSPlaceSearchNearbyRequest
物件,即可提出 Nearby Search 要求來處理回應。
GMSPlaceSearchNearbyRequest
物件會指定要求的所有必要和選用參數。必要參數包括:
- 要在
GMSPlace
物件中傳回的欄位清單,該欄位也稱為「欄位遮罩」,定義由GMSPlaceProperty
定義。如果您未在欄位清單中指定至少一個欄位,或是省略欄位清單,呼叫會傳回錯誤。 - 地區限制:代表搜尋區域的圓形範圍。
這個鄰近搜尋要求範例指定回應 GMSPlace
物件包含地點名稱 (GMSPlacePropertyName
),以及搜尋結果中每個 GMSPlace
物件的地點座標 (GMSPlacePropertyCoordinate
)。而且只會篩選回應,只傳回「餐廳」和「咖啡廳」類型的地點。
Swift
// 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)
Objective-C
// 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; } } ];
GooglePlacesSwift
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
物件。
除了資料欄位,回應中的 GMSPlace
物件還包含下列成員函式:
-
isOpen
會計算地點在特定時間是否營業中。 isOpenAtDate
會計算地點在特定日期是否營業。
必要參數
請使用 GMSPlaceSearchNearbyRequest
物件指定搜尋所需的參數。
-
欄位清單
要求 Place Details 時,您必須指定要在地點的
GMSPlace
物件中傳回的資料做為欄位遮罩。若要定義欄位遮罩,請將GMSPlaceProperty
的值陣列傳遞至GMSPlaceSearchNearbyRequest
物件。欄位遮罩是良好的設計做法,可確保您不會要求不必要的資料,避免不必要的處理時間和帳單費用。請指定下列一或多個欄位:
下列欄位會觸發 Nearby Search (Basic) SKU:
GMSPlacePropertyAddressComponents
、GMSPlacePropertyBusinessStatus
、GMSPlacePropertyCoordinate
、GMSPlacePropertyFormattedAddress
、GMSPlacePropertyName
、GMSPlacePropertyIconBackgroundColor
、GMSPlacePropertyIconImageURL
、GMSPlacePropertyPhotos
、GMSPlacePropertyPlaceID
、GMSPlacePropertyPlusCode
、GMSPlacePropertyTypes
、GMSPlacePropertyUTCOffsetMinutes
、GMSPlacePropertyViewport
、GMSPlacePropertyWheelchairAccessibleEntrance
下列欄位會觸發 Nearby Search (Advanced) SKU:
GMSPlacePropertyCurrentOpeningHours
、GMSPlacePropertySecondaryOpeningHours
、GMSPlacePropertyPhoneNumber
、GMSPlacePropertyPriceLevel
、GMSPlacePropertyRating
、GMSPlacePropertyOpeningHours
、GMSPlacePropertyUserRatingsTotal
、GMSPlacePropertyWebsite
下列欄位會觸發 Nearby Search (Preferred) SKU:
GMSPlacePropertyCurbsidePickup
、GMSPlacePropertyDelivery
、GMSPlacePropertyDineIn
、GMSPlacePropertyEditorialSummary
、GMSPlacePropertyReservable
、GMSPlacePropertyReviews
、GMSPlacePropertyServesBeer
、GMSPlacePropertyServesBreakfast
、GMSPlacePropertyServesBrunch
、GMSPlacePropertyServesDinner
、GMSPlacePropertyServesLunch
、GMSPlacePropertyServesVegetarianFood
、GMSPlacePropertyServesWine
、GMSPlacePropertyTakeout
以下範例會傳遞兩個欄位值的清單,指定要求傳回的
GMSPlace
物件包含name
和placeID
欄位:Swift
// Specify the place data types to return. let fields: [GMSPlaceProperty] = [.placeID, .name]
Objective-C
// Specify the place data types to return. NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
GooglePlacesSwift
// Specify the place data types to return. let fields: [PlaceProperty] = [.placeID, .displayName]
-
locationRestriction
GMSPlaceLocationRestriction
物件會定義要搜尋的區域,以圓形為指定,由中心點和半徑 (以公尺為單位) 定義。半徑必須介於 0.0 到 50000.0 (含) 之間。預設半徑為 0.0。您必須在要求中設定大於 0.0 的值。
自選參數
使用 GMSPlaceSearchNearbyRequest
物件指定搜尋的選用參數。
-
includeType/excludedTypes、includePrimaryTypes/excludedPrimaryType
可讓您從表 A 類型中指定類型清單,用來篩選搜尋結果。每個類型限制類別中最多可指定 50 種類型。
地點只能擁有相關聯表 A 類型的單一主要類型。舉例來說,主要類型可能是
"mexican_restaurant"
或"steak_house"
。使用includedPrimaryTypes
和excludedPrimaryTypes
即可依據地點的主要類型篩選結果。地點也可以擁有相關聯表 A 類型的多個類型值。舉例來說,餐廳可能會有下列類型:
"seafood_restaurant"
、"restaurant"
、"food"
、"point_of_interest"
、"establishment"
。使用includedTypes
和excludedTypes
即可篩選地點相關類型清單的結果。如果指定搜尋時設有多種類型限制,系統只會傳回符合所有限制的地點。舉例來說,如果您指定
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
,傳回的地點會提供"restaurant"
相關服務,但不主要以"steak_house"
形式運作。includedTypes
從表格 A 搜尋的地點類型清單。如果省略這個參數,系統會傳回所有類型的地點。
excludedTypes
要從表格 A 中排除的地點類型清單。
如果您在要求中同時指定
includedTypes
(例如"school"
) 和excludedTypes
(例如"primary_school"
),則回應會包含分類為"school"
,但不歸為"primary_school"
的地點。回應會包含至少與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
物件皆可包含作者資訊和作者作者資訊。如果您在應用程式中顯示評論,則您也必須顯示所有作者資訊或作者作者資訊。
如需更多資訊,請參閱歸因說明文件。