Places SDK for iOS 为您的应用提供关于地点的丰富信息,包括地点的名称和地址、指定为纬度/经度坐标的地理位置、地点类型(如夜总会、宠物店、博物馆等)。若要访问特定地点的这一信息,您可以使用地点 ID,这是一个唯一标识地点的稳定标识符。
地点详情
GMSPlace
类可提供有关特定地点的信息。您可以通过以下方式持有 GMSPlace
对象:
- 调用
GMSPlacesClient findPlaceLikelihoodsFromUserLocationWithPlaceFields:
。请参阅有关获取当前地点的指南。 - 调用
GMSPlacesClient fetchPlaceFromPlaceID:
,并传递GMSPlaceField
、地点 ID 和回调方法。对于“地点详情”请求,如果您没有在请求中指定至少一个字段,或在请求中忽略了fields
参数,系统将返回所有可能的字段,并向您收取相应费用。请参阅有关按 ID 获取地点的指南。
请求地点时,您必须指定要返回哪些类型的地点数据。为此,请传递 GMSPlaceField
以指定要返回的数据类型。这是一项重要的考虑因素,因为这会影响每个请求的费用。
由于地点数据结果不得为空,因此系统只会返回包含数据的地点结果(例如,如果请求的地点没有照片,photos
字段将不会显示在结果中)。
以下示例会传递两个字段值的列表,以指定请求返回的数据:
Swift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" // Specify the place data types to return. let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) | UInt(GMSPlaceField.placeID.rawValue))
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID);
GMSPlaceLikelihoodList
地点对象不支持
详细了解地点字段。如需详细了解地点数据请求的结算方式,请参阅用量和结算。
GMSPlace
类可能包含以下地点数据:
name
- 地点的名称。editorialSummary
- 提供地点的简单说明。placeID
- 地点的文本标识符。您可以在本页面的其余部分详细了解地点 ID。coordinate
- 地点的地理位置,以纬度和经度坐标形式指定。phoneNumber
- 地点的电话号码(国际电话号码格式)。formattedAddress
- 此位置直观易懂的地址。此地址通常相当于邮政地址。请注意,由于许可限制,某些国家/地区(例如英国)不允许发布真实的邮政地址。
设置了格式的地址在逻辑上包含一个或多个地址组成部分。例如,地址“111 8th Avenue, New York, NY”包含以下组成部分:“111”(门牌号)、“8th Avenue”(道路名称)、“New York”(城市)和“NY”(美国州名)。
请勿以程序化方式解析设有格式的地址。您应改用单独的地址组成部分,API 响应除了包含设有格式的地址字段外,还包含这些组成部分。
openingHours
- 地点的营业时间(用GMSOpeningHours
表示)。调用GMSOpeningHours.weekdayText
可获取一周中每日营业时间的本地化字符串列表。调用GMSOpeningHours.Periods
会返回GMSPeriod
列表,其中包含更详细的信息,等效于weekdayText
提供的数据。注意:如果某个地点始终营业,则时间段会显示为星期日午夜,且closeEvent
为 null。currentOpeningHours
和secondaryOpeningHours
- 用于对地点进行节假日和临时更改的字段。addressComponents
- 一个GMSAddressComponent
对象数组,表示地点的地址组成部分。提供这些组件的目的是提取有关地点地址的结构化信息,例如查找地点所在的城市。请勿使用这些组件设置地址格式,而应使用formattedAddress
属性,该属性可提供本地化格式的地址。请注意关于
addressComponents
数组的事实:- 地址组成部分的数组包含的组成部分可能多于
formattedAddress
。 - 该数组不一定包含
formattedAddress
中包含的所有地址的政治实体。 - 两次请求之间的响应格式不一定相同。特别是,
addressComponents
的数量因所请求的地址而异,对于同一个地址,数量也可能会随着时间推移而发生变化。组成部分在数组中的位置可能发生变化。组成部分的类型也可能发生变化。后续响应中可能缺少特定组件。
- 地址组成部分的数组包含的组成部分可能多于
userRatingsTotal
- 表示地点评分的条数。
GMSPlace
类包含以下成员函数:
-
isOpen
会根据openingHours
和UTCOffsetMinutes
以及当前日期和时间,计算地点在给定时间是否营业。 isOpenAtDate
会根据openingHours
和UTCOffsetMinutes
以及当前日期和时间,计算某个地点在指定日期是否营业。
使用这些函数获取营业时间和/或日期时,原始的 fetchPlaceFromPlaceID:
或 findPlaceLikelihoodsFromUserLocationWithPlaceFields:
请求必须指定 GMSPlaceFieldOpeningHours
和 GMSPlaceFieldUTCOffsetMinutes
字段。如果缺少其中任何一个字段,生成的 GMSPlace
对象将不包含营业时间或日期,并且调用将返回 GMSPlaceOpenStatusUnknown
。为确保结果准确,请在原始地点请求中请求 GMSPlaceFieldBusinessStatus
和 GMSPlaceFieldUTCOffsetMinutes
字段。如果未请求,则假定商家开展业务。
isOpen
与“地点详情”搭配使用。享受特别营业时间
常规营业时间是通过openingHours
获取的,而currentOpeningHours
和secondaryOpeningHours
支持节假日和临时变更时间表。
系统会过滤和显示这些特殊日子的例外营业时间(如有)。
Swift
func examineOpeningHours(place: GMSPlace) { // Check if the current opening hours contains a special day that has exceptional hours guard let currentOpeningHours = place.currentOpeningHours else { return } if let specialDays = currentOpeningHours.specialDays { guard !specialDays.isEmpty else { return } if let specialDay = specialDays.filter { $0.isExceptional }.first { // Indicate exceptional hours } } // Check if current opening hours contains a truncated time period let periods = currentOpeningHours.periods if !periods.isEmpty { for period in periods { let open = period.open let close = period.close if let open = open { let date = open.date if open.isTruncated { // Indicate truncated time period } } } } // Check if the place's secondary opening hours indicate when delivery is available let secondaryOpeningHours = place.secondaryOpeningHours guard let hoursType = secondaryOpeningHours.first?.hoursType else { return } if (hoursType == GMSPlaceHoursTypeDelivery) { // Indicate hours where delivery is available } }
Objective-C
- (void)examineOpeningHours:(GMSPlace *) place { // Check if the current opening hours contains a special day that has exceptional hours GMSOpeningHours *currentOpeningHours = place.currentOpeningHours; if (currentOpeningHours != nil) { NSArray<GMSPlaceSpecialDay *> *specialDays = currentOpeningHours.specialDays; if ([specialDays count] != 0) { for (GMSPlaceSpecialDay *specialDay in specialDays) { NSDate *date = specialDay.date; if ([specialDay isExceptional]) { // Indicate exceptional hours } } } } // Check if current opening hours contains a truncated time period NSArray <GMSPeriod *> * periods = currentOpeningHours.periods; if ([periods count] != 0) { for (GMSPeriod * period in periods) { GMSTimeOfWeek *open = period.open; GMSTimeOfWeek *close = period.close; if (open) { if ([open isTruncated]) { // Indicate truncated time period } } } } // Check if the place's secondary opening hours indicate when delivery is available GMSOpeningHours *secondaryOpeningHours = place.secondaryOpeningHours; GMSPlaceHoursType hoursType = secondaryOpeningHours.getHoursType; if (hoursType == GMSPlaceHoursTypeDelivery) { // Indicate hours where delivery is available } }
按 ID 获取地点
地点 ID 是唯一标识地点的文本标识符。在 Places SDK for iOS 中,您可以从 GMSPlace
对象中检索地点的 ID。您可以存储地点 ID,以便日后再次检索 GMSPlace
对象。
如需按 ID 获取地点,请调用 GMSPlacesClient
fetchPlaceFromPlaceID:
,并传递以下参数:
- 包含地点 ID 的字符串。
- 一个或多个
GMSPlaceField
,指定要返回的数据类型。 - 一个会话令牌(如果已发出调用以完成自动补全查询)。 否则,传递 nil。
- 处理结果的
GMSPlaceResultCallback
。
该 API 会调用指定的回调方法,传入 GMSPlace
对象。如果未找到地点,则地点对象为零值。
Swift
// A hotel in Saigon with an attribution. let placeID = "ChIJV4k8_9UodTERU5KXbkYpSYs" // Specify the place data types to return. let fields: GMSPlaceField = GMSPlaceField(rawValue: UInt(GMSPlaceField.name.rawValue) | UInt(GMSPlaceField.placeID.rawValue))! placesClient?.fetchPlace(fromPlaceID: placeID, placeFields: fields, sessionToken: nil, callback: { (place: GMSPlace?, error: Error?) in if let error = error { print("An error occurred: \(error.localizedDescription)") return } if let place = place { self.lblName?.text = place.name print("The selected place is: \(place.name)") } })
Objective-C
// A hotel in Saigon with an attribution. NSString *placeID = @"ChIJV4k8_9UodTERU5KXbkYpSYs"; // Specify the place data types to return. GMSPlaceField fields = (GMSPlaceFieldName | GMSPlaceFieldPlaceID); [_placesClient fetchPlaceFromPlaceID:placeID placeFields:fields sessionToken:nil callback:^(GMSPlace * _Nullable place, NSError * _Nullable error) { if (error != nil) { NSLog(@"An error occurred %@", [error localizedDescription]); return; } if (place != nil) { NSLog(@"The selected place is: %@", [place name]); } }];
在应用中显示提供方说明
当您的应用显示从 GMSPlacesClient
lookUpPlaceID:callback:
获取的信息时,还必须显示提供方信息。请参阅有关归因的文档。
更多关于地点 ID 的内容
Places SDK for iOS 中使用的地点 ID 与 Places API、Places SDK for Android 和其他 Google API 中使用的标识符相同。
每个地点 ID 只能引用一个地点,但单个地点可以有多个地点 ID。
在某些情况下,地点可能会获得新的地点 ID。例如,如果商家搬到新位置,会获取新的地点 ID。
通过指定地点 ID 来请求地点时,您可以确信自己在响应中始终会收到同一地点(如果该地点仍然存在)。但请注意,响应中包含的地点 ID 可能与请求中的地点 ID 不同。
如需了解详情,请参阅地点 ID 概览。