文本搜索（新）

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

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

该服务在自动化系统中进行地址模糊查询时尤其有用，字符串的非地址组成部分可能与商家以及地址匹配。举例来说，格式不正确的地址或包含商家名称等非地址组件的请求可以使用地址模糊查询。除非设置了位置（例如地区、位置限制或位置偏向），否则前两个示例中的请求可能会返回零个结果。

“10 High Street, UK”或“123 Main Street, US” 英国有多个“High Street”；美国有多个“Main Street”。 除非设置了位置限制，否则查询不会返回理想结果。
“连锁餐厅 New York” 纽约多个“连锁餐厅”地点；没有街道地址，甚至没有街道名称。
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US” 英国埃舍尔市只有一条“High Street”；美国加利福尼亚州普莱森顿市只有一条“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 的字符串。如需详细了解如何使用必要字段创建地点对象，请参阅地点详情。
  • 可选的 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 的结算

  • 系统会根据基本数据 SKU 对 GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 字段收费。其余营业时间将按地点详情（高级）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 号”或“旧金山最佳旅游地”。

可选参数

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

  • includedType

    将结果限制为与表 A 中定义的指定类型匹配的地点。 只能指定一种类型。例如：

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

  • isOpenNow

    如果为 true，则仅返回发送查询时营业的地点。如果为 false，则返回所有商家，无论其营业状态如何。 如果您将此参数设置为 false，系统会返回未在 Google 地点数据库中指定营业时间的地点。

  • 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 度（包括这两个数值）之间：

      • 如果 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

    指定系统如何根据查询类型在响应中对结果进行排名：

    • 对于分类查询（例如“纽约市的餐厅”），默认值为 .relevance（按搜索相关性对结果进行排名）。您可以将 rankPreference 设置为 .relevance 或 .distance（按距离对结果进行排名）。
    • 对于非分类查询（例如“Mountain View, CA”），我们建议您不设置 rankPreference。

  • regionCode

    用于设置响应格式的地区代码，指定为 二字符 CLDR 代码值。此参数还可能会对搜索结果产生偏向影响。没有默认值。

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

    大多数 CLDR 代码与 ISO 3166-1 代码相同，但有一些明显的例外。例如，英国的国家代码顶级域名为“uk”(.co.uk)，而其 ISO 3166-1 代码却是“gb”（专指“大不列颠及北爱尔兰联合王国”这一实体）。 此参数可能会根据适用法律影响结果。

在应用中显示提供方说明

如果您的应用要显示通过 GMSPlacesClient 获取的信息（例如照片和评价），则该应用还必须显示必要的提供方说明。

例如，GMSPlacesClient 对象的 reviews 属性包含最多五个 GMSPlaceReview 对象的数组。每个 GMSPlaceReview 对象都可以包含归属声明和作者归属声明。如果您在应用中显示评价，则还必须显示所有提供方信息或作者信息。

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