地点详情

选择平台Android iOS JavaScript Web 服务

Places SDK for iOS 为您的应用提供关于地点的丰富信息,包括地点的名称和地址、以纬度/经度坐标指定的地理位置、地点类型(如夜总会、宠物店、博物馆)等。如需访问特定地点的此类信息,您可以使用地点 ID,这是一个唯一标识地点的稳定标识符。

地点详情

GMSPlace 类可提供有关特定地点的信息。您可以通过以下方式获取 GMSPlace 对象:

地点字段

请求地点时,您必须指定要返回哪些类型的地点数据。为此,请传递 GMSPlaceField 并指定要返回的数据类型。这是一项重要的考虑因素,因为这会影响每个请求的费用。由于地点数据结果不能为空,因此系统只会返回包含数据的地点结果(例如,如果请求的地点没有照片,photos 字段就不会出现在结果中)。您可以指定以下一个或多个字段:

  • GMSPlaceFieldName
  • GMSPlaceFieldPlaceID
  • GMSPlaceFieldPlusCode
  • GMSPlaceFieldBusinessStatus
  • GMSPlaceFieldCoordinate
  • GMSPlaceFieldOpeningHours
  • GMSPlaceFieldPhoneNumber
  • GMSPlaceFieldFormattedAddress
  • GMSPlaceFieldRating
  • GMSPlaceFieldPriceLevel
  • GMSPlaceFieldTypes
  • GMSPlaceFieldWebsite
  • GMSPlaceFieldViewport
  • GMSPlaceFieldAddressComponents
  • GMSPlaceFieldPhotos
  • GMSPlaceFieldUserRatingsTotal
  • GMSPlaceFieldIconImageURL
  • GMSPlaceFieldIconBackgroundColor
  • GMSPlaceFieldUTCOffsetMinutes
  • GMSPlaceFieldAll

详细了解地点字段。如需详细了解地点数据请求的结算方式,请参阅用量和结算

GMSPlace 类可包含以下地点数据:

  • name – 地点的名称。
  • placeID - 地点的文本标识符。如需详细了解地点 ID,请参阅本页面的其余部分。
  • coordinate - 地点的地理位置,指定为纬度和经度坐标。
  • businessStatus - 地点的营业状态(如果是商家)。它可以包含以下任一值:GMSBusinessStatusOperationalGMSBusinessStatusClosedTemporarilyGMSBusinessStatusClosedPermanentlyGMSBusinessStatusUnknown
  • phoneNumber - 地点的电话号码,采用国际格式。
  • formattedAddress - 此营业地点的人类可读地址。

    此地址通常相当于邮政地址。请注意,由于许可限制,某些国家/地区(例如英国)不允许发布真实的邮政地址。

    设有格式的地址在逻辑上包含一个或多个地址组成部分。例如,地址“111 8th Avenue, New York, NY”包含以下组成部分:“111”(门牌号)、“8th Avenue”(道路名称)、“New York”(城市)和“NY”(美国州名)。

    请勿以程序化方式解析设有格式的地址。您应改用单独的地址组成部分,API 响应除了包含设有格式的地址字段外,还包含这些组成部分。

  • rating - 地点的汇总评分,以浮点值形式返回,以用户总体评价为依据,其值范围为 1.0 到 5.0。
  • openingHours - 地点的营业时间(以 GMSOpeningHours 表示)。调用 GMSOpeningHours.weekdayText 获取一周中每日营业时间的本地化字符串列表。调用 GMSOpeningHours.Periods 可返回 GMSPeriod 列表,其中包含更详细的信息,等效于 weekdayText 提供的数据。注意:如果某个地点一直营业,则时间段会以星期日的午夜来表示,并且 closeEvent 为 null。
  • plusCode - 地点的 Plus 代码表示形式。
  • priceLevel - 此地点的价格水平,以整数形式返回,其值介于 0(最便宜)到 4(最昂贵)之间。
  • types - 描述此地点特征的地点类型列表。此数组可以包含多个值,也可以为空。我们可能会在未事先通知您的情况下引入新值。请参阅支持的类型列表。
  • website - 地点网站的 URI(如果已知)。这是由与该地点关联的商家或其他实体维护的网站。
  • attributions - 这是一个 NSAttributedString,其中包含在您的应用使用从 Places SDK for iOS 检索到的地点详情时必须向用户显示的提供方信息。如需详细了解如何检索和显示归因,请参阅归因指南
  • addressComponents - 一组 GMSAddressComponent 对象,表示地点的地址组成部分。提供这些组件的目的是提取地点地址的结构化信息,例如查找地点所在的城市。请勿使用这些组件设置地址格式;而应使用 formattedAddress 属性,此属性可提供本地化格式的地址。

    请注意关于 addressComponents 数组的以下事实:

    • 地址组成部分的数组可能包含比 formattedAddress 更多的组成部分。
    • formattedAddress 中包含的政治实体之外,该数组不一定包含所有政治实体。
    • 响应的格式不能保证各个请求保持不变。具体而言,addressComponents 数量取决于所请求的地址,并且可能会随着同一地址而不断变化。组件可以更改在数组中的位置。组成部分的类型也可能发生变化。特定组件在后续响应中可能会缺失。
  • userRatingsTotal - 表示地点的评分评价数量。
  • GMSPlaceFieldIconImageURL - 表示地点类型(PNG 格式)的图标的网址。
  • GMSPlaceFieldIconBackgroundColor - 地点类型图标的背景颜色。
  • UTCOffsetMinutes - 地点的时区偏移量(以分钟为单位)。

GMSPlace 类包含以下成员函数:

  • isOpen 会根据 openingHoursUTCOffsetMinutes 以及当前的日期和时间,计算地点在给定时间是否开放。
  • isOpenAtDate 会根据 openingHoursUTCOffsetMinutes 以及当前的日期和时间,计算地点在指定日期是否营业。
  • 使用这些函数获取开放时间和/或日期时,原始的 fetchPlaceFromPlaceID:findPlaceLikelihoodsFromUserLocationWithPlaceFields: 请求必须同时指定 GMSPlaceFieldOpeningHoursGMSPlaceFieldUTCOffsetMinutes 字段。如果缺少其中任何一个字段,生成的 GMSPlace 对象将不包含打开时间或日期,并且调用将返回 GMSPlaceOpenStatusUnknown。为确保结果准确,请在原始地点请求中请求 GMSPlaceFieldBusinessStatusGMSPlaceFieldUTCOffsetMinutes 字段。如果未被请求,系统会假定商家正在营业。

    如需了解如何将 isOpen 与地点详情结合使用,请观看此视频

按 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 概览