地点详情（新）

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

Places SDK for iOS（新）可为您的应用提供丰富的信息 包括地点的名称和地址、地理位置 以纬度/经度坐标形式指定的位置、地点类型（例如 例如夜总会、宠物店、博物馆）等等。要访问 则您可以使用地点 ID， 用于标识地点。

获取地点详情

通过 GMSPlace 类包含有关特定地点的信息，其中包括 地点数据字段（新）。获取 GMSPlace 对象（通过调用 GMSPlacesClient fetchPlaceWithRequest:, 传递一个 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 对象中。

获取营业状态

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

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

  • GMSPlace 对象，或用于指定地点 ID 的字符串。如需详细了解如何使用必填字段创建 Place 对象，请参阅地点详情。
  • 可选的 NSDate (Obj-C) 或 Date (Swift) 对象，用于指定您想要检查的时间。如果未指定时间，则默认值为现在。
  • 用于处理响应的 GMSPlaceOpenStatusResponseCallback 方法。
    • &gt;
。

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

isOpenWithRequest 响应

isOpenWithRequest 会返回一个包含名为 status 的布尔值的 GMSPlaceIsOpenResponse 对象，此值用于指明商家是处于营业状态、已停业还是未知。

语言 营业时的值 停业时的值 状态未知时的值
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift（预览版） true false nil

“isOpenWithRequest”的结算

  • GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 字段按基本数据 SKU 计费。其余营业时间在地点详情（高级）SKU 下计费。
  • 如果您的 GMSPlace 对象已包含上一个请求中的这些字段，系统将不会再向您收费。

示例：发出 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 请求地点时，您可以确信 您一定会在响应中收到相同的地点（如果该地点仍然 存在）。但请注意，响应可能包含 与您的要求中的代码不同。

字段列表

请求地点详情时，必须指定 在该地点的 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 对象都可以包含提供方说明和作者提供方说明。 如果您要在应用中显示评价，则还必须显示出处或作者 归因。

有关详情，请参阅 归因。