附近搜索(新)

请选择平台: 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
_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 对象。

获取开放状态

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

此方法接受一个类型为 GMSPlaceIsOpenWithRequest 的参数,其中包含:

  • GMSPlace 对象或用于指定地点 ID 的字符串。如需详细了解如何使用必要字段创建地点对象,请参阅地点详情
  • 一个可选的 NSDate (Obj-C) 或 Date (Swift) 对象,用于指定您要检查的时间。如果未指定时间,则默认为当前时间。
  • 用于处理响应的 GMSPlaceOpenStatusResponseCallback 方法。
  • >

GMSPlaceIsOpenWithRequest 方法要求在 GMSPlace 对象中设置以下字段:

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

如果地点对象中未提供这些字段,或者您传递了地点 ID,该方法会使用 GMSPlacesClient GMSFetchPlaceRequest: 提取这些字段。

isOpenWithRequest 响应

isOpenWithRequest 会返回一个 GMSPlaceIsOpenResponse 对象,其中包含一个名为 status 的布尔值,用于指示商家是开门营业、停业还是状态未知。

语言 处于打开状态时的值 关闭时的值 如果状态未知,则为此值
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift(预览版) true false nil

isOpenWithRequest”的结算卡片

  • GMSPlacePropertyUTCOffsetMinutesGMSPlacePropertyBusinessStatus 字段的费用将计入基本数据 SKU。其余营业时间将根据地点详情企业版 SKU 进行计费。
  • 如果您的 GMSPlace 对象已经包含之前请求中的这些字段,则系统不会再次向您收费。

示例:发出 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 对象。 使用字段遮盖是一种良好的设计做法,可确保您不会请求不必要的数据,这有助于避免产生不必要的处理时间和结算费用。

    指定以下一个或多个字段:

    • 以下字段会触发 Nearby Search Pro SKU

      GMSPlacePropertyAddressComponents
      GMSPlacePropertyBusinessStatus
      GMSPlacePropertyCoordinate
      GMSPlacePropertyFormattedAddress
      GMSPlacePropertyName
      GMSPlacePropertyIconBackgroundColor
      GMSPlacePropertyIconImageURL
      GMSPlacePropertyPhotos
      GMSPlacePropertyPlaceID
      GMSPlacePropertyPlusCode
      GMSPlacePropertyTypes
      GMSPlacePropertyUTCOffsetMinutes
      GMSPlacePropertyViewport
      GMSPlacePropertyWheelchairAccessibleEntrance

    • 以下字段会触发附近搜索企业版 SKU

      GMSPlacePropertyCurrentOpeningHours
      GMSPlacePropertySecondaryOpeningHours
      GMSPlacePropertyPhoneNumber
      GMSPlacePropertyPriceLevel
      GMSPlacePropertyRating
      GMSPlacePropertyOpeningHours
      GMSPlacePropertyUserRatingsTotal
      GMSPlacePropertyWebsite

    • 以下字段会触发附近搜索企业 Plus 版 SKU

      GMSPlacePropertyCurbsidePickup
      GMSPlacePropertyDelivery
      GMSPlacePropertyDineIn
      GMSPlacePropertyEditorialSummary
      GMSPlacePropertyReservable
      GMSPlacePropertyReviews
      GMSPlacePropertyServesBeer
      GMSPlacePropertyServesBreakfast
      GMSPlacePropertyServesBrunch
      GMSPlacePropertyServesDinner
      GMSPlacePropertyServesLunch
      GMSPlacePropertyServesVegetarianFood
      GMSPlacePropertyServesWine
      GMSPlacePropertyTakeout

    以下示例传递了两个字段值的列表,以指定请求返回的 GMSPlace 对象包含 nameplaceID 字段:

    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。您必须在请求中将其设置为大于 0.0 的值。

可选参数

使用 GMSPlaceSearchNearbyRequest 对象指定搜索的可选参数。

  • includedTypes/excludedTypes、includedPrimaryTypes/excludedPrimaryTypes

    让您可以指定要用于过滤搜索结果的类型(表格 A 中的类型)。每个类型限制类别中最多可以指定 50 种类型。

    地点只能有一个主要类型,该类型必须与表格 A 中与其关联的类型相同。例如,主要类型可能是 "mexican_restaurant""steak_house"。使用 includedPrimaryTypesexcludedPrimaryTypes 按地点的主要类型过滤结果。

    地点还可以具有与其关联的表 A中类型的多个类型值。例如,餐厅可能具有以下类型:"seafood_restaurant""restaurant""food""point_of_interest""establishment"。使用 includedTypesexcludedTypes 过滤与地点关联的类型列表中的结果。

    如果您指定了常规的主要类型(例如 "restaurant""hotel"),响应中可能会包含主要类型比指定类型更具体的地点。例如,您可以指定包含主类型 "restaurant"。然后,响应可以包含主类型为 "restaurant" 的地点,但也可以包含主类型更具体的地点,例如 "chinese_restaurant""seafood_restaurant"

    如果在指定搜索时使用了多个类型限制,系统只会返回满足所有限制的地点。例如,如果您指定 {"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]},则返回的地点提供 "restaurant" 相关服务,但主要不是以 "steak_house" 的身份运营。

    includedTypes

    要搜索的表格 A 中地点类型的列表。 如果省略此参数,系统将返回所有类型的地点。

    excludedTypes

    表 A 中要从搜索结果中排除的地点类型的列表。

    如果您在请求中同时指定了 includedTypes(例如 "school")和 excludedTypes(例如 "primary_school"),则响应中会包含被归类为 "school" 但不被归类为 "primary_school" 的地点。响应包含与 includedTypes 中的至少一个项匹配且与 excludedTypes 中的任何项都不匹配的地点。

    如果存在任何冲突的类型(例如同时出现在 includedTypesexcludedTypes 中的类型),系统会返回 INVALID_REQUEST 错误。

    includedPrimaryTypes

    表 A 中要包含在搜索中的主地点类型的列表。

    excludedPrimaryTypes

    表格 A 中要从搜索中排除的主要地点类型的列表。

    如果存在任何冲突的主要类型(例如同时出现在 includedPrimaryTypesexcludedPrimaryTypes 中的类型),系统会返回 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 对象都可以包含提供方说明和作者提供方说明。如果您在应用中显示评价,则还必须显示所有提供方或作者提供方信息。

如需了解详情,请参阅归因文档。