此页面由 Cloud Translation API 翻译。

文本搜索（新）

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

该服务对于在自动化系统中进行模糊地址查询特别有用，并且字符串的非地址组成部分可以与商家以及地址匹配。模糊地址查询示例包括格式不佳的地址或包含非地址组成部分（如商家名称）的请求。除非设置了位置（例如地区、位置限制或位置偏向），否则前两个示例这样的请求可能不会返回任何结果。

“10 High Street, UK”或“123 Main Street, US”	英国有多个“High Street”；美国有多个“Main Street”。除非设置了位置限制，否则查询不会返回所需的结果。
“纽约连锁餐厅”	纽约有多个“连锁餐厅”营业地点；没有街道地址，甚至没有街道名称。
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US”	只有一条位于英国埃舍尔市的“高街”；在美国加利福尼亚州普莱森顿市只有一条“主街”。
“纽约 UniqueRestaurantName”	在纽约只有一家使用此名称的场所；无需使用街道地址进行区分。
“北京烤鸭店”	此查询包含其位置限制，“北京烤鸭”是一种定义明确的地点类型。它会返回多个结果。
“+1 514-670-8700”	此查询包含电话号码。它会返回与该电话号码关联的地点的多个结果。注意：为了在通过电话号码进行搜索时获得最佳效果，请在添加国家/地区代码后加上空格，并将 `regionCode` 参数设置为与国家/地区代码对应。

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

通过调用 GMSPlacesClient searchByTextWithRequest: 发出“文本搜索”请求，并传递用于定义请求参数的 GMSPlaceSearchByTextRequest 对象和 GMSPlaceSearchByTextResultCallback 类型的回调方法来处理响应。

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

GMSPlace 对象中要返回的字段列表，也称为“字段掩码”，由 GMSPlaceProperty 定义。如果您没有在字段列表中指定至少一个字段，或省略字段列表，则调用会返回错误。
文本查询。

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

Swift

// Create the GMSPlaceSearchByTextRequest object.
let placeProperties: [GMSPlaceProperty] = [GMSPlacePropertyName, GMSPlacePropertyPlaceID];
let request = GMSPlaceSearchByTextRequest(textQuery:"pizza in New York" placeProperties:placeProperties)
request.isOpenNow = true
request.includedType = "restaurant"
request.maxResultCount = 5
request.minRating = 3.5
request.rankPreference = .distance
request.isStrictTypeFiltering = true
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
request.locationRestriction = GMSPlaceRectangularLocationOption(
      CLLocationCoordinate2D(latitude: 20, longitude: 30),
      CLLocationCoordinate2D(latitude: 40, longitude: 50)
)

// Array to hold the places in the response
placeResults = [];

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
  }
  self.placeResults = results
}

GMSPlacesClient.shared().searchByTextWithRequest(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.locationRestriction = GMSPlaceRectangularLocationOption(
    CLLocationCoordinate2DMake(20, 30), CLLocationCoordinate2DMake(40, 50));
request.locationBias = GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(20, 30), 2.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 (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 对象的字段不能为空。例如，如果字段列表包含用于请求响应中的 photos 字段的 GMSPlacePropertyPhotos，而响应中的 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 号”或“旧金山最佳去处”。

可选参数

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

includedType

将结果限制为与表 A 定义的指定类型匹配的地点。只能指定一种类型。例如：
- request.includedType = "bar"
- request.includedType = "pharmacy"
注意：表 B 中的值仅在响应中返回。您不能使用表 B 中的值作为过滤条件。
isOpenNow

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

与 includeType 参数搭配使用。设置为 true 时，系统仅返回与 includeType 指定的指定类型相匹配的地点。默认情况下，如果为 false，响应可以包含与指定类型不匹配的地点。
locationBias

指定要搜索的区域。此位置充当偏差，这意味着可以返回指定位置周围的结果，包括指定区域以外的结果。

您可以指定 locationRestriction 或 locationBias，但不能同时指定这两者。您可以将 locationRestriction 视为指定结果必须在哪个区域，将 locationBias 视为指定结果必须靠近但可以位于该区域之外的区域。

注意：如果您同时省略 locationBias 和 locationRestriction，则 API 会默认使用 IP 自定义调整。通过 IP 自定义调整，API 使用设备的 IP 地址来自定义调整结果。

注意：如果 textQuery 包含明确的位置（例如 Market in Barcelona），则可以替换 locationBias 参数。在这种情况下，locationBias 会被忽略。

将区域指定为矩形视口或圆形。
- 圆形由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（含 0.0 和 50000.0）。默认半径为 0.0。例如：
```
request.locationBias =  GMSPlaceCircularLocationOption(CLLocationCoordinate2DMake(latitude: 20, longitude: 30), radius: 2.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 视为指定结果必须靠近但可以位于该区域之外的区域。

注意：如果您同时省略 locationBias 和 locationRestriction，则 API 会默认使用 IP 自定义调整。通过 IP 自定义调整，API 使用设备的 IP 地址来自定义调整结果。
maxResultCount

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

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

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

指定一个数组，其中包含由 PriceLevel 定义的一个或多个值。

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

例如：
```
request.priceLevels = [GMSPlacesPriceLevel.moderate.rawValue, GMSPlacesPriceLevel.cheap.rawValue]
```
rankPreference

指定如何根据查询类型对结果在响应中的排名：
- 对于分类查询（例如“纽约市餐厅”），系统会默认使用 .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 对象可以包含提供方说明和作者提供方说明。如果您在应用中显示评价，则还必须显示提供方说明或作者出处。

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