地点详情（新）

适用于 iOS 的 Places SDK（新版）可为您的应用提供有关地点的丰富信息，包括地点的名称和地址、以纬度/经度坐标形式指定的地理位置、地点类型（例如夜总会、宠物店、博物馆）等。如需访问特定地点的这些信息，您可以使用地点 ID（一种可唯一标识地点的稳定标识符）。

获取地点详情

GMSPlace 类包含有关特定地点的信息，包括地点数据字段（新）中显示的所有数据字段。通过调用 GMSPlacesClient fetchPlaceWithRequest: 并传递 GMSFetchPlaceRequest 对象和 GMSPlaceResultCallback 类型的回调方法，获取 GMSPlace 对象。

GMSFetchPlaceRequest 对象指定：

• （必需）地点 ID，Google Places 数据库和 Google 地图中某个地点的唯一标识符。
• （必需）要在 GMSPlace 对象中返回的字段列表，也称为字段掩码，由 GMSPlaceProperty 定义。 如果您未在字段列表中指定至少一个字段，或者省略了字段列表，则该调用会返回错误。
• （可选）用于设置响应格式的地区代码。
• （可选）用于结束自动补全（新）会话的会话令牌。

发出“地点详情”请求

此示例通过 ID 获取地点，并传递以下参数：

• ChIJV4k8_9UodTERU5KXbkYpSYs 的地点 ID。
• 一个字段列表，用于指定返回地点名称和网站网址。
• 用于处理结果的 GMSPlaceResultCallback。

该 API 会调用指定的回调方法，并传入一个 GMSPlace 对象。如果未找到地点，则地点对象为零值。

// 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
}

// 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))")
})

// 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);
  }
}];

“地点详情”响应

地点详情会返回一个 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 会返回一个 GMSPlaceIsOpenResponse 对象，其中包含一个名为 status 的布尔值，用于指示商家是营业、停业还是状态未知。

“isOpenWithRequest”的结算卡片

• GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 字段的费用计入基本数据 SKU。其余营业时间信息则按地点详情企业版 SKU 收费。
• 如果您的 GMSPlace 对象已经包含之前请求中的这些字段，则不会再次收费。

示例：发出 GMSPlaceIsOpenWithRequest 请求

        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
        }
        

    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
        }
      }
        

          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
            }
          }];
          

必需参数

使用 GMSFetchPlaceRequest 对象指定必需的参数。

地点 ID

Places SDK for iOS 中使用的地点 ID 与 Places API、Places SDK for Android 和其他 Google API 中使用的标识符相同。每个地点 ID 只能指代一个地点，但一个地点可以有多个地点 ID。

在某些情况下，地点可能会获得新的地点 ID。例如，如果商家搬到新位置，会获取新的地点 ID。

如果您通过指定地点 ID 来请求地点，则可以确信，您始终会在响应中收到同一地点（如果该地点仍然存在）。不过请注意，响应中可能包含与请求中不同的地点 ID。

字段列表

请求地点详情时，您必须在 GMSPlace 对象中指定要返回的地点数据，作为字段掩码。如需定义字段掩码，请将 GMSPlaceProperty 中的值数组传递给 GMSFetchPlaceRequest 对象。使用字段遮盖是一种良好的设计做法，可确保您不会请求不必要的数据，这有助于避免产生不必要的处理时间和结算费用。

指定以下一个或多个字段：

• 以下字段会触发地点详情精简版（仅 ID）SKU：

  GMSPlacePropertyPlaceID
GMSPlacePropertyPhotos

• 以下字段会触发地点详情精简版 SKU：

  GMSPlacePropertyAddressComponents
GMSPlacePropertyFormattedAddress
GMSPlacePropertyCoordinate
GMSPlacePropertyPlusCode
GMSPlacePropertyTypes
GMSPlacePropertyViewport

• 以下字段会触发地点详情专业版 SKU：

  GMSPlacePropertyBusinessStatus
GMSPlacePropertyIconBackgroundColor
GMSPlacePropertyIconImageURL
GMSPlacePropertyName
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 字段：

// Specify the place data types to return.
let fields: [PlaceProperty] = [.placeID, .displayName]
    

// Specify the place data types to return.
let fields: [GMSPlaceProperty] = [.placeID, .name]
  

// Specify the place data types to return.
NSArray<GMSPlaceProperty *> *fields = @[GMSPlacePropertyPlaceID, GMSPlacePropertyName];
  

可选参数

使用 GMSFetchPlaceRequest 对象指定可选参数。

regionCode

用于设置响应格式的地区代码，以 双字符 CLDR 代码值指定。此参数还可能会对搜索结果产生偏差效应。没有默认值。

如果响应中地址字段的国家/地区名称与地区代码一致，则地址中会省略国家/地区代码。

除了某些明显的例外情况之外，大多数 CLDR 代码都与 ISO 3166-1 代码完全一致。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（从技术上讲，是指“大不列颠及北爱尔兰联合王国”这一实体）。 此参数可能会根据适用法律影响结果。

sessionToken

会话令牌是用户生成的字符串，用于将“自动补全（新）”调用跟踪为“会话”。自动补全（新）使用会话令牌将用户自动补全搜索的查询和地点选择阶段归入不同的会话，以便进行结算。会话令牌会传递到“自动补全（新）”调用之后的“地点详情（新）”调用中。如需了解详情，请参阅会话令牌。

在应用中显示提供方说明

如果应用显示从 GMSPlacesClient 获取的信息（例如照片和评价），则还必须显示必要的提供方信息。

例如，GMSPlacesClient 对象的 reviews 属性包含一个最多包含 5 个 GMSPlaceReview 对象的数组。每个 GMSPlaceReview 对象都可以包含提供方信息和作者提供方信息。 如果您在应用中显示评价，则还必须显示任何提供方信息或作者信息。

如需了解详情，请参阅有关提供方信息的文档。