地点详情

请选择平台: Android iOS JavaScript 网络服务

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

地点详情

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

请求地点时,您必须指定要返回的地点数据类型。为此,请传递一个 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);
  

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

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。
  • currentOpeningHourssecondaryOpeningHours - 用于调整地点时间表的节假日和临时变化的字段。
  • addressComponents - GMSAddressComponent 对象数组,表示地点地址的组成部分。提供这些组件是为了提取有关地点地址的结构化信息,例如查找地点所在的城市。请勿使用这些组件进行地址格式设置,而应使用 formattedAddress 属性,它会提供本地化格式的地址。

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

    • 地址组成部分的数组包含的组成部分可能多于 formattedAddress
    • 除了 formattedAddress 中包含的政治实体之外,该数组不一定包括包含地址的所有政治实体。
    • 两次请求之间的响应格式不一定相同。特别是,addressComponents 的数量因所请求的地址而异,对于同一地址,数量也可能会随着时间推移而发生变化。组成部分在数组中的位置可能会发生变化。组成部分的类型也可能发生变化。后续响应中可能缺少特定组成部分。
  • userRatingsTotal - 表示地点评分中包含多少条评价。

GMSPlace 类包含以下成员函数:

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

    请观看此视频,了解如何将 isOpen 与“地点详情”搭配使用。

获得特殊营业时间

正常营业时间是通过 openingHours 获取的,currentOpeningHourssecondaryOpeningHours 则支持节假日和临时的时间表变更。 可以过滤和显示这些特殊日子的特殊营业时间(如果有)。

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