文本搜索

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

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

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

Places SDK for iOS（新）中的文本搜索请求采用以下格式：

func testPlaceSearchByTextRequestGMPSRequestCreationWithProperties() {
  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)
  )
}

- (void)testPlaceSearchByTextRequestGMPSRequestCreationWithProperties {
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);
}

必需参数

• 字段列表

  指定要返回的地点数据属性。传递 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、GMSPlacePropertyServesBeer、GMSPlacePropertyServesBreakfast、GMSPlacePropertyServesBrunch、GMSPlacePropertyServesDinner、GMSPlacePropertyServesLunch、GMSPlacePropertyServesVegetarianFood、GMSPlacePropertyServesWine、GMSPlacePropertyTakeout

• textQuery

  要搜索的文本字符串，例如：“餐馆”、“主街 123 号”或“旧金山最佳去处”。

可选参数

• 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 和 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 视为指定结果必须靠近但可以位于该区域之外的区域。

• 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 定义的一个或多个值。

  例如：

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

• rankPreference

  指定结果在响应中的排名方式。在适用的情况下，该 API 默认使用 RELEVANCE。例如，对于“纽约市餐厅”之类的查询，系统将使用默认值 RELEVANCE。对于地理位置查询（例如“加利福尼亚州山景城”）或其他类型的查询，系统不会应用任何默认值，并且结果会按照后端返回的顺序显示。

  相关的值包括：

  • .distance：按距离对结果排名。
  • .relevance：按相关性对结果排名。

• regionCode

  用于设置响应格式的地区代码，以 双字符 CLDR 代码值的形式指定。此参数也会对搜索结果产生偏差影响。没有默认值。

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

  除了某些明显的例外情况之外，大多数 CLDR 代码都与 ISO 3166-1 代码相同。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（专指“大不列颠及北爱尔兰联合王国”）。 该参数可能会影响根据适用法律的结果。

“文本搜索”响应

Text Search API 以 GMSPlace 对象的形式返回匹配项数组，每个匹配地点有一个 GMSPlace 对象。