文本搜索（新）

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

文本搜索会返回一组地点的相关信息 字符串。例如，“北京烤鸭”、“附近的鞋店” 或“长安街 123 号”。该服务会返回一个与文本字符串和任何已设置的位置偏向相匹配的地点列表。

该服务特别适合用于使地址模糊不清的地址 查询。 和非地址部分可以匹配商家以及 地址。举例来说，格式不正确的地址或包含商家名称等非地址组件的请求可以使用地址模糊查询。与前两个示例类似的请求可能返回零结果，除非 位置（如区域、位置限制或位置偏向）设置。

“英国，高街 10 号”或“123 Main Street, US” 英国的多个“高街”；美国的多条“主街” 除非位置限制是 。
“纽约连锁餐馆” 多个“连锁餐厅”位于纽约的分店；无街道地址或 甚至街道名称。
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US” 仅一条“高街”英国埃舍尔市；只有一个“Main Street” 位于美国加利福尼亚州普莱森顿
“UniqueRestaurantName New York” 在纽约只有一个具有此名称的场所；无街道地址 进行区分
“北京烤鸭店” 此查询包含其位置限制以及“北京烤鸭店”为 明确定义的地点类型它会返回多个结果。
“+1 514-670-8700”

此查询包含电话号码。它会针对以下查询返回多个结果： 显示与该电话号码相关的地点

通过文本搜索获取地点列表

通过调用 GMSPlacesClient searchByTextWithRequest: 发出“文本搜索”请求。 通过一个 GMSPlaceSearchByTextRequest 对象，该对象定义了请求参数和回调方法，其类型为 GMSPlaceSearchByTextResultCallback, 处理响应。

GMSPlaceSearchByTextRequest 对象指定 必需参数和可选参数 。必需的参数包括：

  • GMSPlace 对象中要返回的字段列表， 称为字段掩码，如 GMSPlaceProperty。 您未在字段列表中指定至少一个字段，或者省略了 字段列表，则该调用会返回错误。
  • 文本查询。

此示例文本搜索请求指定响应 GMSPlace 对象 包含搜索中每个 GMSPlace 对象的地点名称和地点 ID 结果。它还会过滤响应，以仅返回以下类型的地点： “餐馆”。

Swift

// Create the GMSPlaceSearchByTextRequest object.
let myProperties = [GMSPlaceProperty.name, GMSPlaceProperty.placeID].map {$0.rawValue}
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York", placeProperties:myProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

// Array to hold the places in the response
var placeResults: [GMSPlace] = []

let callback: GMSPlaceSearchByTextResultCallback = { [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().searchByText(with: request, callback: callback)

Objective-C

// Create the GMSPlaceSearchByTextRequest object.
GMSPlaceSearchByTextRequest *request =
    [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyName, GMSPlacePropertyPlaceID]];
request.isOpenNow = YES;
request.includedType = @"restaurant";
request.maxResultCount = 5;
request.minRating = 3.5;
request.rankPreference = GMSPlaceSearchByTextRankPreferenceDistance;
request.isStrictTypeFiltering = YES;
request.priceLevels = @[ @(kGMSPlacesPriceLevelFree), @(kGMSPlacesPriceLevelCheap) ];
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0);

// Array to hold the places in the response
_placeResults = [NSArray array];

// Create the GMSPlaceSearchByTextRequest object.
[_placesClient searchByTextWithRequest:request
    callback:^(NSArray<GMSPlace *> *_Nullable placeResults, NSError * _Nullable error) {
      if (error != nil) {
        NSLog(@"An error occurred %@", [error localizedDescription]);
        return;
      } else {
        if (placeResults.count > 0) {
          // Get list of places.
          _placeResults = placeResults;
      }
    }
  }
];

Places Swift SDK for iOS（预览版）

let restriction = RectangularLocationRestriction(
      northEast: CLLocationCoordinate2D(latitude: 20, longitude: 30),
      southWest: CLLocationCoordinate2D(latitude: 40, longitude: 50)
)
let searchByTextRequest = SearchByTextRequest(
        textQuery: "pizza in New York",
        placeProperties: [ .name, .placeID ],
        locationRestriction: restriction,
        includedType: .restaurant,
        maxResultCount: 5,
        minRating: 3.5,
        priceLevels: [ .moderate, .inexpensive ],
        isStrictTypeFiltering: true
)
switch await placesClient.searchByText(with: searchByTextRequest) {
case .success(let places):
  // Handle places
case .failure(let placesError):
  // Handle error
}

文本搜索响应

Text Search API 在 形式 GMSPlace 对象，每个匹配地点对应一个 GMSPlace 对象。

获取营业状态

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

此方法接受 GMSPlaceIsOpenWithRequest 类型的单个参数，其中包含：

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

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

  • GMSPlacePropertyUTCOffsetMinutes
  • GMSPlacePropertyBusinessStatus
  • GMSPlacePropertyOpeningHours
  • GMSPlacePropertyCurrentOpeningHours
  • GMSPlacePropertySecondaryOpeningHours

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

isOpenWithRequest 响应

isOpenWithRequest 会返回一个包含名为 status 的布尔值的 GMSPlaceIsOpenResponse 对象，此值用于指明商家是处于营业状态、已停业还是未知。

语言 营业时的值 停业时的值 状态未知时的值
Swift .open .closed .unknown
Objective-C GMSPlaceOpenStatusOpen GMSPlaceOpenStatusClosed GMSPlaceOpenStatusUnknown
GooglePlacesSwift（预览版） true false nil

“isOpenWithRequest”的结算

  • GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 字段按基本数据 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
          }

必需参数

使用 GMSPlaceSearchByTextRequest 对象指定所需的 参数。

  • 字段列表

    指定要返回的地点数据属性。传递 GMSPlace 属性列表，指定要返回的数据字段。如果您省略字段 则请求将返回错误。

    字段列表是一种很好的设计做法，可确保您不会为 不必要的数据，这有助于避免不必要的处理时间和 结算费用。

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

    • 以下字段会触发文本搜索（仅 ID）SKU：

      GMSPlacePropertyPlaceID， GMSPlacePropertyName

    • 以下字段会触发文本搜索（基本）SKU：

      GMSPlacePropertyAddressComponents， GMSPlacePropertyBusinessStatus, GMSPlacePropertyFormattedAddress, GMSPlacePropertyIconBackgroundColor, GMSPlacePropertyIconImageURL, GMSPlacePropertyCoordinate, GMSPlacePropertyPhotos, 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

  • textQuery

    要搜索的文本字符串，例如：“餐馆”“123 Main” 或“旧金山最佳游览地点”。

可选参数

使用 GMSPlaceSearchByTextRequest 对象指定可选的 参数。

  • includedType

    将结果限制为与以下项定义的指定类型相匹配的地点： 表 A. 只能指定一个类型。例如：

    • request.includedType = "bar"
    • request.includedType = "pharmacy"
    。

  • isOpenNow

    如果为 true，则仅返回正常营业的地点 。如果为 false，则返回所有商家 而无论打开状态如何 未在 Google Places 数据库中指定营业时间的地点为 返回 false。

  • isStrictTypeFiltering

    与 includeType 参数搭配使用。设置为 true，则仅搜索与由 返回 includeType。 如果为 false（默认值），则响应中可以包含与指定类型不匹配的地点。

  • locationBias

    指定要搜索的区域。此位置用作偏向，这意味着系统可以返回指定位置周围的结果，包括指定区域之外的结果。

    您可以指定 locationRestriction 或 locationBias， 但不能同时设置这两者。可以将 locationRestriction 视为指定 结果所在的区域，以及 locationBias 指定结果必须靠近但可以不在的区域 数据。

    将区域指定为矩形视口或圆形。

    • 圆形由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（包括这两个数值）。默认半径为 0.0。 例如：

      request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(40.7, -74.0), 200.0)

    • 矩形是一种经纬度视口，表示为 低点和高点对角线。低点表示西南方 矩形的一角，高点表示东北 矩形的一角。

      视口被视为封闭区域，即包含其边界。纬度边界 必须介于 -90 度（含）到 90 度（含）之间，且经度范围必须为 必须介于 -180 度到 180 度之间（包括 -180 度和 180 度）：

      • 如果 low = high，视口包含以下元素： 这个单一点
      • 如果 low.longitude > high.longitude，则经度范围会反转（视口跨越 180 度经线）。
      • 如果 low.longitude = -180 度且 high.longitude = 180 度，视口包含所有 经度。
      • 如果 low.longitude = 180 度且 high.longitude = -180 度，则经度范围为空。
      • 如果 low.latitude >high.latitude、 纬度范围为空。

  • locationRestriction

    指定要搜索的区域。指定区域以外的搜索结果不予显示 返回。将区域指定为矩形视口。请参阅说明 共 locationBias 个 了解有关定义视口的信息。

    您可以指定 locationRestriction 或 locationBias，但不能同时指定这两者。可以将 locationRestriction 视为指定 结果所在的区域，以及 locationBias 指定结果必须靠近但可以不在的区域 数据。

  • maxResultCount

    指定要返回的地点结果的数量上限。必须介于 1 到 20（默认值）之间。

  • minRating

    将结果的范围限制为平均用户评分高于 或等于此上限。中的值必须介于 0.0 和 5.0（含）之间 以 0.5 为增量。例如：0、0.5、1.0、... 、5.0（包括这两个数值）。值为 向上舍入到最接近的 0.5。例如，值 0.6 会排除 评分低于 1.0 的结果。

  • priceLevels

    将搜索范围限制为标记在特定价位的地点。 默认设置是选择所有价位。

    指定由以下项定义的一个或多个值的数组： PriceLevel。

    例如：

    request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]

  • rankPreference

    指定如何根据 查询：

    • 对于像“Restaurants in New York City”这样的分类查询， 默认值为 .relevance（按搜索相关性对结果排名）。 您可以将 rankPreference 设置为 .relevance 或 .distance（按距离对结果排名）。
    • 对于非分类查询（例如“Mountain View, CA”），我们建议您不设置 rankPreference。

  • regionCode

    用于设置响应格式的地区代码，指定为 二字符 CLDR 代码值。此参数也可能具有偏差效应 。没有默认值。

    如果响应中地址字段的国家/地区名称与 区号，则地址中省略了国家/地区代码。

    大多数 CLDR 代码与 ISO 3166-1 代码相同， 但有一些值得注意的例外情况。例如，英国的 ccTLD 为 "uk"(.co.uk)，而其 ISO 3166-1 代码为“gb”（从技术层面来讲， “大不列颠及北爱尔兰联合王国”）。 根据适用法律，该参数可能会影响结果。

在应用中显示提供方说明

当应用显示从 GMSPlacesClient、 如照片和评价，则应用还必须显示必要的提供方说明。

例如，GMSPlacesClient 对象的 reviews 属性 包含一个数组，该数组最多包含五个 GMSPlaceReview 对象的操作。每个 GMSPlaceReview 对象都可以包含提供方说明和作者提供方说明。 如果您要在应用中显示评价，则还必须显示出处或作者 归因。

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