地点详情（新）

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

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

获取地点详情

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

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<GMSPlaceProperty *> *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 == null) {
    NSLog(@"Place Found: %@", place.name);
    NSLog(@"The place URL: %@", place.website);
  }
}];

GooglePlacesSwift

// 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 对象除了包含数据字段之外，还包含以下成员函数：

  • isOpen 用于计算某个地点在给定时间是否营业。
  • isOpenAtDate 用于计算某个地点在指定日期是否营业。

必需参数

使用 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];

GooglePlacesSwift

// 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 对象可以包含提供方说明和作者提供方说明。如果您在应用中显示评价，则还必须显示提供方说明或作者出处。

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