Places SDK for iOS(新)可为您的应用提供丰富的信息 包括地点的名称和地址、地理位置 以纬度/经度坐标形式指定的位置、地点类型(例如 例如夜总会、宠物店、博物馆)等等。要访问 那么您可以使用地点 ID, 用于标识地点。
获取地点详情
通过
GMSPlace
类包含有关特定地点的信息,其中包括
地点数据字段(新)。获取
GMSPlace
对象(通过调用
GMSPlacesClient
fetchPlaceWithRequest:
,
传递一个 GMSFetchPlaceRequest
对象和一个
类型的回调方法
GMSPlaceResultCallback
。
GMSFetchPlaceRequest
对象会指定:
- (必填)地点 ID,即 Google 商家信息中地点的唯一标识符 并在 Google 地图上显示。
- (必需)
GMSPlace
对象中要返回的字段列表,也称为 字段掩码,由GMSPlaceProperty
。 您未在字段列表中指定至少一个字段,或者省略了 字段列表,则该调用会返回错误。 - (可选)用来设置响应格式的地区代码。
- (可选)用于结束“自动补全(新)”会话的会话令牌。
发出“地点详情”请求
此示例通过传递以下参数按 ID 获取地点:
ChIJV4k8_9UodTERU5KXbkYpSYs
的地点 ID。- 指定返回地点名称和网站网址的字段列表。
GMSPlaceResultCallback
来处理结果。
API 调用指定的回调方法,传入
GMSPlace
对象。如果未找到地点,则地点对象为零值。
Swift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" // Specify the place data types to return. let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.website].map {$0.rawValue} // Create the GMSFetchPlaceRequest object. let fetchPlaceRequest = GMSFetchPlaceRequest(placeID: placeID, placeProperties: myProperties, sessionToken: nil) client.fetchPlace(with: fetchPlaceRequest, callback: { (place: GMSPlace?, error: Error?) in guard let place, error == nil else { return } print("Place found: \(String(describing: place.name))") })
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. NSArray<NSString *> *myProperties = @[GMSPlacePropertyName, GMSPlacePropertyWebsite]; // Create the GMSFetchPlaceRequest object. GMSFetchPlaceRequest *fetchPlaceRequest = [[GMSFetchPlaceRequest alloc] initWithPlaceID:placeID placeProperties: myProperties sessionToken:nil]; [placesClient fetchPlaceWithRequest: fetchPlaceRequest callback: ^(GMSPlace *_Nullable place, NSError *_Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } else { NSLog(@"Place Found: %@", place.name); NSLog(@"The place URL: %@", place.website); } }];
GooglePlacesSwift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" let fetchPlaceRequest = FetchPlaceRequest( placeID: placeID, placeProperties: [.name, .website] ) switch await placesClient.fetchPlace(with: fetchPlaceRequest) { case .success(let place): // Handle place case .failure(let placesError): // Handle error }
“地点详情”响应
地点详情会返回
包含地点详情的 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 }
必需参数
使用 GMSFetchPlaceRequest
对象指定所需的参数。
地点 ID
Places SDK for iOS 中使用的地点 ID 是 标识符与 Places API、Places SDK for Android 中使用的标识符相同 和其他 Google API。每个地点 ID 只能指代一个地点,但单个地点可以有多个地点 多个地点 ID。
在某些情况下,可能会导致地点获得新的地点 ID。 例如,如果商家搬到新位置,会获取新的地点 ID。
通过指定地点 ID 请求地点时,您可以确信 您一定会在响应中收到相同的地点(如果该地点仍然 存在)。但请注意,响应可能包含 与您的要求中的代码不同。
字段列表
请求地点详情时,必须指定
在该地点的 GMSPlace
对象中返回,作为字段掩码。定义字段掩码
从
GMSPlaceProperty
添加到 GMSFetchPlaceRequest
对象中。
字段遮盖是一种很好的设计做法,可确保您不会请求不必要的数据,
有助于避免不必要的处理时间和结算费用。
指定以下一个或多个字段:
以下字段会触发地点详情(仅 ID)SKU:
GMSPlacePropertyPlaceID
、GMSPlacePropertyName
、GMSPlacePropertyPhotos
以下字段会触发地点详情(仅限位置)SKU:
GMSPlacePropertyAddressComponents
,GMSPlacePropertyFormattedAddress
,GMSPlacePropertyCoordinate
,GMSPlacePropertyPlusCode
,GMSPlacePropertyTypes
,GMSPlacePropertyViewport
以下字段会触发地点详情(基本)SKU:
GMSPlacePropertyBusinessStatus
,GMSPlacePropertyIconBackgroundColor
,GMSPlacePropertyIconImageURL
,GMSPlacePropertyUTCOffsetMinutes
,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]
可选参数
使用 GMSFetchPlaceRequest
对象指定可选参数。
regionCode
用于设置响应格式的地区代码,指定为 <ph type="x-smartling-placeholder"></ph> 两个字符的 CLDR 代码值。此参数也可能具有偏差效应 。没有默认值。
如果响应中地址字段的国家/地区名称与 区号,则地址中省略了国家/地区代码。
大多数 CLDR 代码与 ISO 3166-1 代码相同, 但有一些值得注意的例外情况。例如,英国的 ccTLD 为 "uk"(.co.uk),而其 ISO 3166-1 代码为“gb”(从技术层面来讲, “大不列颠及北爱尔兰联合王国”)。 根据适用法律,该参数可能会影响结果。
sessionToken
会话令牌是用户生成的字符串,用于跟踪自动补全情况 (新)调用作为“会话”。自动补全(新)会使用会话令牌 将用户自动补全搜索的查询和地点选择阶段分组到一个单独的会话中 用于结算目的会话令牌会传递到地点详情(新) 跟随“自动补全(新)”调用的调用。如需了解详情,请参阅 会话令牌。
在应用中显示提供方说明
当应用显示从
GMSPlacesClient
、
如照片和评价,则应用还必须显示必要的提供方说明。
例如,GMSPlacesClient
对象的 reviews
属性
包含一个数组,该数组最多包含五个
GMSPlaceReview
对象的操作。每个 GMSPlaceReview
对象都可以包含提供方说明和作者提供方说明。
如果您要在应用中显示评价,则还必须显示出处或作者
归因。
有关详情,请参阅 归因。