“附近搜索(新)”请求会将要搜索的区域作为输入
以圆形表示,该圆形由
圆和半径(以米为单位)。该请求会返回匹配地点列表,其中每个地点都由
GMSPlace
对象。
默认情况下,响应包含搜索区域内所有类型的地点。您可以选择性地 通过指定要明确包含或排除的地点类型列表来过滤响应, 响应。例如,您可以指定在响应中仅包含以下类型的地点: “餐馆”“面包店”和“咖啡馆”,或排除所有“学校”类型的地点。
“附近搜索(新)”请求
通过调用 来发出“附近搜索”请求
GMSPlacesClient searchNearbyWithRequest:
,
通过一个
GMSPlaceSearchNearbyRequest
对象,该对象定义了请求参数和回调方法,其类型为
GMSPlaceSearchNearbyResultCallback
,
处理响应。
GMSPlaceSearchNearbyRequest
对象指定
必需和可选
参数。必需的参数包括:
GMSPlace
对象中要返回的字段列表,也称为 字段掩码,由GMSPlaceProperty
。 您未在字段列表中指定至少一个字段,或者省略了 字段列表,则该调用会返回错误。- 地理位置限制,表示用来定义搜索区域的圆圈。
此示例附近搜索请求指定响应 GMSPlace
对象
包含地点名称 (GMSPlacePropertyName
) 和地点坐标
为搜索中的每个 GMSPlace
对象指定 (GMSPlacePropertyCoordinate
)
结果。它还过滤响应,仅返回“餐馆”类型的地点和“cafe”
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
对象。
获取营业状态
GMSPlacesClient
对象包含一个名为 isOpenWithRequest
(在 Swift 中为 isOpenRequest
,在 GooglePlacesSwift 中为 isPlaceOpenRequest
)的成员函数,该函数会根据在调用中指定的时间,返回指示该地点当前是否营业的响应。
此方法接受 GMSPlaceIsOpenWithRequest
类型的单个参数,其中包含:
GMSPlace
对象,或用于指定地点 ID 的字符串。如需详细了解如何使用必填字段创建 Place 对象,请参阅地点详情。
- 可选的
NSDate
(Obj-C) 或Date
(Swift) 对象,用于指定您想要检查的时间。如果未指定时间,则默认值为现在。 - 用于处理响应的
GMSPlaceOpenStatusResponseCallback
方法。
GMSPlaceIsOpenWithRequest
方法要求在 GMSPlace
对象中设置以下字段:
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyBusinessStatus
GMSPlacePropertyOpeningHours
GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
如果地点对象中未提供这些字段,或者您传递了地点 ID,该方法会使用 GMSPlacesClient GMSFetchPlaceRequest:
进行提取。
isOpenWithRequest
响应
isOpenWithRequest
会返回一个包含名为 status
的布尔值的 GMSPlaceIsOpenResponse
对象,此值用于指明商家是处于营业状态、已停业还是未知。
语言 | 营业时的值 | 停业时的值 | 状态未知时的值 |
---|---|---|---|
Swift | .open |
.closed |
.unknown |
Objective-C | GMSPlaceOpenStatusOpen |
GMSPlaceOpenStatusClosed |
GMSPlaceOpenStatusUnknown |
GooglePlacesSwift(预览版) | true |
false |
nil |
“isOpenWithRequest
”的结算
GMSPlacePropertyUTCOffsetMinutes
和GMSPlacePropertyBusinessStatus
字段按基本数据 SKU 计费。其余营业时间在地点详情(高级)SKU 下计费。- 如果您的
GMSPlace
对象已包含上一个请求中的这些字段,系统将不会再向您收费。
示例:发出 GMSPlaceIsOpenWithRequest
请求
以下示例展示了如何在现有的 GMSPlace
对象中初始化 GMSPlaceIsOpenWithRequest
。
Swift
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 } }
Objective-C
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 } }];
GooglePlacesSwift
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
对象中。 字段遮盖是一种很好的设计做法,可确保您不会请求不必要的数据, 这有助于避免不必要的处理时间和结算费用。指定以下一个或多个字段:
以下字段会触发 附近搜索(基本)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/excludedTypes,includePrimaryTypes/excludedPrimaryTypes
允许您从类型中指定类型列表 表 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"
。响应包含与以下至少一个匹配的地点: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
对象都可以包含提供方说明和作者提供方说明。
如果您要在应用中显示评价,则还必须显示出处或作者
归因。
有关详情,请参阅 归因。