此页面由 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;
    }
  }
];

GooglePlacesSwift

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 对象中会将其省略。

以及数据字段中的 GMSPlace 对象，响应包含以下成员函数：

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

必需参数

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

用于设置响应格式的地区代码，指定为两个字符的 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

GooglePlacesSwift

“附近搜索”响应

必需参数

字段列表

Swift

Objective-C

GooglePlacesSwift

locationRestriction

可选参数

includeTypes/excludedTypes，containsPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

maxResultCount

rankPreference

regionCode

在应用中显示提供方说明