此页面由 Cloud Translation API 翻译。

文本搜索（新）

请选择平台： 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”	此查询包含电话号码。它会针对以下查询返回多个结果：显示与该电话号码相关的地点注意：为了在搜索时获得最佳结果电话号码，包含国家/地区代码，后跟一个空格；设置`regionCode` 参数与国家/地区代码相对应。

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

通过调用 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;
      }
    }
  }
];

GooglePlacesSwift

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 对象。

注意：响应 GMSPlace 对象的字段不能为空。例如，如果字段列表包含 GMSPlacePropertyPhotos 到在响应中请求 photos 字段，在响应中请求 photos 字段为空，响应 GMSPlace 对象中会将其省略。

以及数据字段中的 GMSPlace 对象，响应包含以下成员函数：

isOpen 用于计算地点在给定时间是否营业。
isOpenAtDate 计算地点在给定日期是否营业。

。

必需参数

使用 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"
。
注意：表 B 仅会在响应中返回您不能在表 B 用作过滤条件。
isOpenNow

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

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

指定要搜索的区域。这个位置就是一种偏差，这意味着可返回指定位置周围的结果，包括结果在指定区域之外。

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

注意：如果您同时省略两者 locationBias 和 locationRestriction，以及 API 默认使用 IP 自定义调整通过 IP 自定义调整，该 API 会使用设备的以调整结果。

注意： locationBias 参数可以如果 textQuery 包含一个显式位置，例如 Market in Barcelona。在这种情况下，系统会忽略 locationBias。

将区域指定为矩形视口或圆形。
- 圆形由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（含 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 指定结果必须靠近但可以不在的区域数据。

注意：如果您同时省略两者 locationBias 和 locationRestriction，以及 API 默认使用 IP 自定义调整通过 IP 自定义调整，该 API 使用使结果自定义调整。
maxResultCount

指定要返回的地点结果的数量上限。必须介于 1 和 20（默认值），包括 1 和 20。
minRating

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

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

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

注意：PRICE_LEVEL_FREE 不允许出现在请求中。它仅用于填充响应。

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

有关详情，请参阅归因。