附近搜索（新）

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

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

“附近搜索（新）”请求

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

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

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

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

Swift

// Array to hold the places in the response
placeResults = [];

// 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
  }
  self.placeResults = results
}

GMSPlacesClient.shared().searchNearbyWithRequest(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) {
      [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 对象还包含以下成员函数：

  • 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、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 种类型。

    一个地点只能有一个关联的表 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

    表 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（默认值）之间（包括这两个数值）。

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

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