此页面由 Cloud Translation API 翻译。

地点详情（新）

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

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

获取地点详情

GMSPlace 类包含特定地点的相关信息，包括地点数据字段（新）中显示的所有数据字段。通过调用 GMSPlacesClient fetchPlaceWithRequest: 获取 GMSPlace 对象，并传递 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);
  }
}];

Places Swift SDK for iOS（预览版）

// 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 对象中仅填充字段列表中指定的字段。

注意：响应 GMSPlace 对象的字段不能为空。例如，如果字段列表包含 GMSPlacePropertyPhotos 以请求响应中的 photos 字段，而响应中的 photos 字段为空，则该字段会从响应 GMSPlace 对象中省略。

获取开放状态

GMSPlacesClient 对象包含一个名为 isOpenWithRequest（在 Swift 中为 isOpenRequest，在 GooglePlacesSwift 中为 isPlaceOpenRequest）的成员函数，该函数会根据调用中指定的时间返回一个响应，指示相应地点目前是否处于营业状态。

注意：已废弃的 GMSPlace isOpen: 和 GMSPlace isOpenAtDate: 函数可能不准确，不适用于 Places API（新版）。

此方法接受一个类型为 GMSPlaceIsOpenWithRequest 的参数，其中包含：

GMSPlace 对象或用于指定地点 ID 的字符串。如需详细了解如何使用必要字段创建地点对象，请参阅地点详情。

注意：地点对象必须包含有效的地点 ID。
一个可选的 NSDate (Obj-C) 或 Date (Swift) 对象，用于指定您要检查的时间。如果未指定时间，则默认为当前时间。
用于处理响应的 GMSPlaceOpenStatusResponseCallback 方法。

GMSPlaceIsOpenWithRequest 方法要求在 GMSPlace 对象中设置以下字段：

GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyBusinessStatus
GMSPlacePropertyOpeningHours
GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours

如果地点对象中未提供这些字段，或者您传递了地点 ID，该方法将使用 GMSPlacesClient GMSFetchPlaceRequest: 提取这些字段。

`isOpenWithRequest` 响应

isOpenWithRequest 会返回一个 GMSPlaceIsOpenResponse 对象，其中包含一个名为 status 的布尔值，用于指示商家是开门营业、停业还是状态未知。

语言	处于打开状态时的值	关闭时的值	如果状态未知，则为此值
Swift	`.open`	`.closed`	`.unknown`
Objective-C	`GMSPlaceOpenStatusOpen`	`GMSPlaceOpenStatusClosed`	`GMSPlaceOpenStatusUnknown`
GooglePlacesSwift（预览版）	`true`	`false`	`nil`

“`isOpenWithRequest`”的结算卡片

系统会根据基本数据 SKU 对 GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 字段收费。其余营业时间将按地点详情（高级）SKU 的费率收费。
如果您的 GMSPlace 对象已经包含之前请求中的这些字段，则不会再次收费。
警告：如果您的 GMSPlace 对象不包含这些字段，系统会再次向您收取基本数据 SKU 的费用。其余营业时间将按地点详情（高级）SKU 的费率收费。如果您的项目将使用 isOpenWithRequest，我们建议您确保提取必要的地点详细信息。

示例：发出 `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 请求地点时，您可以确信自己始终会在响应中收到相同的地点（如果该地点仍然存在）。不过，请注意，响应中可能包含与您请求中地点 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];

Places Swift SDK for iOS（预览版）

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

可选参数

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

regionCode

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

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

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

sessionToken

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

在应用中显示提供方说明

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

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

如需了解详情，请参阅归因文档。

地点详情（新）

获取地点详情

发出“地点详情”请求

Swift

Objective-C

Places Swift SDK for iOS（预览版）

“地点详情”响应

获取开放状态

isOpenWithRequest 响应

“isOpenWithRequest”的结算卡片

示例：发出 GMSPlaceIsOpenWithRequest 请求

Swift

Objective-C

GooglePlacesSwift

必需参数

地点 ID

字段列表

Swift

Objective-C

Places Swift SDK for iOS（预览版）

可选参数

regionCode

sessionToken

在应用中显示提供方说明

`isOpenWithRequest` 响应

“`isOpenWithRequest`”的结算卡片

示例：发出 `GMSPlaceIsOpenWithRequest` 请求