此页面由 Cloud Translation API 翻译。

附近搜索（新）

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

“附近搜索（新）”请求会将要搜索的区域作为输入以圆形表示，该圆形由圆和半径（以米为单位）。该请求会返回匹配地点列表，其中每个地点都由 GMSPlace 对象。

默认情况下，响应包含搜索区域内所有类型的地点。您可以选择性地通过指定要明确包含或排除在响应。例如，您可以指定在响应中仅包含类型为 “餐馆”“面包店”和“咖啡馆”，或排除所有“学校”类型的地点。

“附近搜索（新）”请求

通过调用来发出“附近搜索”请求 GMSPlacesClient searchNearbyWithRequest:、通过一个 GMSPlaceSearchNearbyRequest 对象，该对象定义了请求参数和回调方法，其类型为 GMSPlaceSearchNearbyResultCallback，处理响应。

GMSPlaceSearchNearbyRequest 对象指定必需和可选参数。必需的参数包括：

GMSPlace 对象中要返回的字段列表，也称为 字段掩码，由 GMSPlaceProperty。您未在字段列表中指定至少一个字段，或者省略了字段列表，则该调用会返回错误。
地理位置限制，表示用来定义搜索区域的圆圈。

此示例附近搜索请求指定响应 GMSPlace 对象包含地点名称 (GMSPlacePropertyName) 和地点坐标为搜索中的每个 GMSPlace 对象指定 (GMSPlacePropertyCoordinate) 结果。它还过滤响应，仅返回“餐馆”类型的地点和“cafe”

Swift

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
let circularLocationRestriction = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500)

// Specify the fields to return in the GMSPlace object for each place in the response.
let placeProperties = [GMSPlaceProperty.name, GMSPlaceProperty.coordinate].map {$0.rawValue}

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
var request = GMSPlaceSearchNearbyRequest(locationRestriction: circularLocationRestriction, placeProperties: placeProperties)
let includedTypes = ["restaurant", "cafe"]
request.includedTypes = includedTypes

let callback: GMSPlaceSearchNearbyResultCallback = { [weak self] results, error in
  guard let self, error == nil else {
    if let error {
      print(error.localizedDescription)
    }
    return
  }
  guard let results = results as? [GMSPlace] else {
    return
  }
  placeResults = results
}

GMSPlacesClient.shared().searchNearby(with: request, callback: callback)

Objective-C

// Array to hold the places in the response
_placeResults = [NSArray array];

// Define the search area as a 500 meter diameter circle in San Francisco, CA.
id<GMSPlaceLocationRestriction> circularLocation = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(37.7937, -122.3965), 500);

// Create the GMSPlaceSearchNearbyRequest, specifying the search area and GMSPlace fields to return.
GMSPlaceSearchNearbyRequest *request = [[GMSPlaceSearchNearbyRequest alloc]
  initWithLocationRestriction:circularLocation
              placeProperties:@[ GMSPlacePropertyName, GMSPlacePropertyCoordinate ]];

// Set the place types to filter on.
NSArray<NSString *> *includedTypes = @[ @"restaurant", @"cafe" ];
request.includedTypes = [[NSMutableArray alloc] initWithArray:includedTypes];

[_placesClient searchNearbyWithRequest:request
  callback:^(NSArray<GMSPlace *> *_Nullable places, NSError *_Nullable error) {
    if (error != nil) {
      NSLog(@"An error occurred %@", [error localizedDescription]);
      return;
    } else {
        // Get list of places.
        _placeResults = places;
    }
  }
];

Places Swift SDK for iOS（预览版）

let restriction = CircularCoordinateRegion(center: CLLocationCoordinate2DMake(37.7937, -122.3965), radius: 500)
let searchNearbyRequest = SearchNearbyRequest(
  locationRestriction: restriction,
  placeProperties: [ .name, .coordinate],
  includedTypes: [ .restaurant, .cafe ],
)
switch await placesClient.searchNearby(with: searchNearbyRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

“附近搜索”响应

Nearby Search API 以 GMSPlace 对象，每个匹配地点对应一个 GMSPlace 对象。

注意：响应 GMSPlace 对象的字段不能为空。例如，如果字段列表包含 GMSPlacePropertyPhotos 到在响应中请求 photos 字段，在响应中请求 photos 字段为空，响应 GMSPlace 对象中会将其省略。

获取营业状态

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

注意：已废弃的 GMSPlace isOpen: 和 GMSPlace isOpenAtDate: 函数可能不准确，因此不应与 Places API（新）搭配使用。

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

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

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

。

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 对象已包含上一个请求中的这些字段，系统将不会再向您收费。
警告：如果您的 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
          }

必需参数

使用 GMSPlaceSearchNearbyRequest 对象指定。

字段列表

请求地点详情时，必须指定在该地点的 GMSPlace 对象中返回，作为字段掩码。要定义字段掩码，则从 GMSPlaceProperty 添加到 GMSPlaceSearchNearbyRequest 对象中。字段遮盖是一种很好的设计做法，可确保您不会请求不必要的数据，这有助于避免不必要的处理时间和结算费用。

指定以下一个或多个字段：
- 以下字段会触发附近搜索（基本）SKU：
  
  GMSPlacePropertyAddressComponents, GMSPlacePropertyBusinessStatus, GMSPlacePropertyCoordinate, GMSPlacePropertyFormattedAddress， GMSPlacePropertyName, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyPhotos, GMSPlacePropertyPlaceID, GMSPlacePropertyPlusCode, GMSPlacePropertyTypes, GMSPlacePropertyUTCOffsetMinutes, GMSPlacePropertyViewport, 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]
        
```
locationRestriction

GMSPlaceLocationRestriction 对象，该对象以圆形的形式定义了要搜索的区域，以圆形的中心点和半径（以米为单位）。半径必须介于 0.0 和 50000.0 之间（含 0.0 和 50000.0）。默认半径为 0.0。您必须在请求中将其设置为大于 0.0 的值。

可选参数

使用 GMSPlaceSearchNearbyRequest 对象为。

includeTypes/excludedTypes，containsPrimaryTypes/excludedPrimaryTypes

允许您从类型中指定类型列表表 A 用于过滤搜索结果。每个类型限制类别中最多可以指定 50 种类型。

注意：表 B 仅会在响应中返回您不能在表 B 作为过滤条件。

一个地点只能有一个主要类型表 A 中关联的。例如，主要类型可能是 "mexican_restaurant" 或 "steak_house"。使用按 includedPrimaryTypes 和 excludedPrimaryTypes 过滤结果地点的主要类型。

地点还可以具有来自类型的多个类型值 表 A 及其关联。例如，一家餐馆可能具有以下类型： "seafood_restaurant"、"restaurant"、"food"、 "point_of_interest"、"establishment"。使用includedTypes 使用 excludedTypes 过滤与位置。

当您指定常规主要类型（例如 "restaurant" 或 "hotel"，则响应可以包含具有更具体的主要类型（而非指定的对象。例如，您指定的主要类型是 "restaurant"。然后，响应可以包含主要类型为 "restaurant"，但响应也可能会包含地点主要类型，例如 "chinese_restaurant" 或 "seafood_restaurant"。

如果指定了多个类型限制的搜索，则只有地点返回满足所有限制条件的应用例如，如果您指定 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}，即返回的地点提供"restaurant"相关服务，但服务并不主要以 "steak_house" 的形式指定。

如果您省略 includedTypes、excludedTypes，请求的includedPrimaryTypes和excludedPrimaryTypes 搜索会返回位置限制边界内所有类型的地点。

includedTypes

来自以下来源的地点类型列表：要搜索的表 A。如果省略此参数，则返回所有类型的地点。

excludedTypes

来自以下来源的地点类型列表：表 A：要从搜索。

如果您同时指定 includedTypes（例如 "school"）和 excludedTypes（例如 "primary_school"），则将响应包含归类为"school"但不属于 "primary_school"。响应包含与以下至少一个匹配的地点： includedTypes 且没有 excludedTypes。

如果存在任何冲突的类型（例如某个类型同时出现在两个 includedTypes 中）和 excludedTypes，则会返回 INVALID_REQUEST 错误。

includedPrimaryTypes

来自以下来源的主要地点类型列表：表 A 包含的内容。

excludedPrimaryTypes

来自以下来源的主要地点类型列表：表 A：要排除的项目。

如果存在任何存在冲突的主要类型，例如某个类型同时出现在 includedPrimaryTypes和excludedPrimaryTypes INVALID_ARGUMENT 错误。
maxResultCount

指定要返回的地点结果的数量上限。必须介于 1 和 20（默认值），包括 1 和 20。
rankPreference

要使用的排名类型。如果省略此参数，则结果将按热门程度排名。可以是以下其中一项：
- .popularity（默认）：根据热门程度对结果进行排序。
- .distance，根据结果与指定位置。
regionCode

用于设置响应格式的地区代码，指定为 <ph type="x-smartling-placeholder"></ph> 两个字符的 CLDR 代码值。没有默认值。

如果响应中 formattedAddress 字段的国家/地区名称与 regionCode，则 formattedAddress 中省略了国家/地区代码。此参数对 adrFormatAddress（始终包含国家/地区）没有影响或 shortFormattedAddress（从不包含该属性值）。

大多数 CLDR 代码都与 ISO 3166-1 代码但有一些值得注意的例外情况。例如，英国的 ccTLD 为 "uk"(.co.uk)，而其 ISO 3166-1 代码为“gb”（从技术层面来讲， “大不列颠及北爱尔兰联合王国”）。根据适用法律，该参数可能会影响结果。

在应用中显示提供方说明

当应用显示从 GMSPlacesClient、如照片和评价，则应用还必须显示必要的提供方说明。

例如，GMSPlacesClient 对象的 reviews 属性包含一个数组，该数组最多包含五个 GMSPlaceReview 对象的操作。每个 GMSPlaceReview 对象都可以包含提供方说明和作者提供方说明。如果您要在应用中显示评价，则还必须显示出处或作者归因。

有关详情，请参阅归因。

附近搜索（新）

“附近搜索（新）”请求

Swift

Objective-C

Places Swift SDK for iOS（预览版）

“附近搜索”响应

获取营业状态

isOpenWithRequest 响应

“isOpenWithRequest”的结算

示例：发出 GMSPlaceIsOpenWithRequest 请求

Swift

Objective-C

GooglePlacesSwift

必需参数

字段列表

Swift

Objective-C

Places Swift SDK for iOS（预览版）

locationRestriction

可选参数

includeTypes/excludedTypes，containsPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

maxResultCount

rankPreference

regionCode

在应用中显示提供方说明

`isOpenWithRequest` 响应

“`isOpenWithRequest`”的结算

示例：发出 `GMSPlaceIsOpenWithRequest` 请求