此页面由 Cloud Translation API 翻译。

附近搜索（新）

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

“附近搜索（新）”请求将要搜索的区域指定为圆形，该区域由圆形中心点的纬度和经度坐标以及半径（以米为单位）定义。该请求会返回指定搜索区域内的匹配地点列表，其中每个地点都由一个 GMSPlace 对象表示。

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

“附近搜索（新）”请求

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

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

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

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

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
GMSPlace *_placeResults = [GMSPlace alloc];

// 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) {
      [weakSelf showErrorWithMessage:error.localizedDescription];
    } 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 对象的字段不能为空。例如，如果字段列表包含用于请求响应中的 photos 字段的 GMSPlacePropertyPhotos，而响应中的 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/excludedType、includedPrimaryTypes/excludedPrimaryTypes

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

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

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

一个地点还可以具有与之关联的表 A 类型的多个类型值。例如，餐馆可能具有以下类型："seafood_restaurant"、"restaurant"、"food"、"point_of_interest"、"establishment"。使用 includedTypes 和 excludedTypes 过滤与地点相关联的类型列表中的结果。

如果搜索指定了多种类型限制，系统仅返回满足所有限制的地点。例如，如果您指定 {"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/excludedType、includedPrimaryTypes/excludedPrimaryTypes

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

maxResultCount

rankPreference

regionCode

在应用中显示提供方说明