附近搜索（新）

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

欧洲经济区 (EEA) 开发者

如果您的账单邮寄地址在欧洲经济区，自 2025 年 7 月 8 日起，您在使用服务时需遵守 Google Maps Platform EEA 服务条款。具体功能因地区而异。 了解详情。

此功能需要您启用新一代 Places API，即 Places API（新）。如需了解详情，请参阅启用 API。

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

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

“附近搜索（新）”请求

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

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

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

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

Places Swift SDK

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
}

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;
    }
  }
];

“附近搜索”响应

附近搜索 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 会返回一个 GMSPlaceIsOpenResponse 对象，其中包含一个名为 status 的布尔值，用于指示商家是营业、停业还是状态未知。

语言	打开时的值	关闭时的值	状态未知时的值
Places Swift	true	false	nil
Swift	.open	.closed	.unknown
Objective-C	GMSPlaceOpenStatusOpen	GMSPlaceOpenStatusClosed	GMSPlaceOpenStatusUnknown

“isOpenWithRequest”的结算卡片

• GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 字段的费用计入基本数据 SKU。其余营业时间信息则按地点详情企业版 SKU 收费。
• 如果您的 GMSPlace 对象已经包含之前请求中的这些字段，则不会再次收费。
• 警告：如果您的 GMSPlace 对象不包含这些字段，您将需要再次为基本数据 SKU 付费。其余营业时间信息将按地点详情企业版 SKU 收费。如果您的项目将使用 isOpenWithRequest，我们建议您确保获取必要的地点详细信息。

示例：发出 GMSPlaceIsOpenWithRequest 请求

以下示例展示了如何在现有 GMSPlace 对象中初始化 GMSPlaceIsOpenWithRequest。

Places Swift SDK

        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
        }
        

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
            }
          }];
          

必需参数

使用 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

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

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

  以下示例传递了两个字段值的列表，以指定请求返回的 GMSPlace 对象包含 name 和 placeID 字段：

  Places Swift SDK

  // Specify the place data types to return.
  let fields: [PlaceProperty] = [.placeID, .displayName]
          

  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];
          

• locationRestriction

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

可选参数

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

• includedTypes/excludedTypes、includedPrimaryTypes/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（默认值）之间（含边界值）。

• 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 属性包含一个最多包含 5 个 GMSPlaceReview 对象的数组。每个 GMSPlaceReview 对象都可以包含提供方信息和作者提供方信息。 如果您在应用中显示评价，则还必须显示任何提供方信息或作者信息。

如需了解详情，请参阅有关提供方信息的文档。