“附近搜索(新)”请求将要搜索的区域指定为圆形,该区域由圆形中心点的纬度和经度坐标以及半径(以米为单位)定义。该请求会返回指定搜索区域内的匹配地点列表,其中每个地点都由一个 GMSPlace
对象表示。
默认情况下,响应包含搜索区域内所有类型的地点。您可以选择性地过滤响应,方法是指定要在响应中明确包含或排除的地点类型列表。例如,您可以指定在响应中仅包含“餐馆”“面包店”和“咖啡馆”类型的地点,或者排除“学校”类型的所有地点。
“附近搜索(新)”请求
通过调用 GMSPlacesClient searchNearbyWithRequest:
发出“附近搜索”请求,并传递一个用于定义请求参数的 GMSPlaceSearchNearbyRequest
对象和一个 GMSPlaceSearchNearbyResultCallback
类型的回调方法来处理响应。
GMSPlaceSearchNearbyRequest
对象指定请求的所有必需和可选参数。必需参数包括:
GMSPlace
对象中要返回的字段列表,也称为字段掩码,由GMSPlaceProperty
定义。如果您没有在字段列表中指定至少一个字段,或省略字段列表,则调用会返回错误。- 位置限制,表示定义搜索区域的圆圈。
此示例附近搜索请求指定响应 GMSPlace
对象包含搜索结果中每个 GMSPlace
对象的地点名称 (GMSPlacePropertyName
) 和地点坐标 (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 API 会以GMSPlace
对象的形式返回一个匹配项数组,其中每个匹配的地点都有一个 GMSPlace
对象。
响应中的 GMSPlace
对象除了包含数据字段之外,还包含以下成员函数:
-
isOpen
用于计算某个地点在给定时间是否营业。 isOpenAtDate
用于计算某个地点在指定日期是否营业。
必需参数
使用 GMSPlaceSearchNearbyRequest
对象指定搜索所需的参数。
-
字段列表
请求地点详情时,您必须在
GMSPlace
对象中指定地点要返回的数据作为字段掩码。如需定义字段掩码,请将GMSPlaceProperty
中的值数组传递给GMSPlaceSearchNearbyRequest
对象。 字段遮盖是一种很好的设计做法,可确保您不会请求不必要的数据,这有助于避免不必要的处理时间和结算费用。指定以下一个或多个字段:
以下字段会触发附近搜索(基本)SKU:
GMSPlacePropertyAddressComponents
、GMSPlacePropertyBusinessStatus
、GMSPlacePropertyCoordinate
、GMSPlacePropertyFormattedAddress
、GMSPlacePropertyName
、GMSPlacePropertyIconBackgroundColor
、GMSPlacePropertyIconImageURL
、GMSPlacePropertyPhotos
、GMSPlacePropertyPlaceID
、GMSPlacePropertyPlusCode
、GMSPlacePropertyTypes
、GMSPlacePropertyUTCOffsetMinutes
、GMSPlacePropertyViewport
、GMSPlacePropertyWheelchairAccessibleEntrance
以下字段会触发附近搜索(高级)SKU:
GMSPlacePropertyCurrentOpeningHours
,GMSPlacePropertySecondaryOpeningHours
,GMSPlacePropertyPhoneNumber
,GMSPlacePropertyPriceLevel
,GMSPlacePropertyRating
,GMSPlacePropertyOpeningHours
,GMSPlacePropertyUserRatingsTotal
,GMSPlacePropertyWebsite
以下字段会触发附近搜索(首选)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 和 50000.0)。默认半径为 0.0。您必须在请求中将其设置为大于 0.0 的值。
可选参数
使用 GMSPlaceSearchNearbyRequest
对象指定用于搜索的可选参数。
-
includeTypes/excludedType、includedPrimaryTypes/excludedPrimaryTypes
允许您指定表 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(默认值)之间,包括 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
对象可以包含提供方说明和作者提供方说明。如果您在应用中显示评价,则还必须显示提供方说明或作者出处。
如需了解详情,请参阅有关归因的文档。