文本搜索（新）

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

欧洲经济区 (EEA) 开发者

如果您的账单邮寄地址在欧洲经济区，自 2025 年 7 月 8 日起，您在使用服务时需遵守 Google Maps Platform EEA 服务条款。具体功能因地区而异。 了解详情。

此功能需要您启用新一代 Places API，即 Places API（新）。如需了解详情，请参阅启用 API。

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

此服务特别适合在自动化系统中进行模糊地址查询，并且字符串的非地址组成部分可能与商家以及地址相匹配。模糊不清的地址查询示例包括格式不正确的地址或包含非地址组成部分的请求（例如商家名称）。 除非设置了位置（例如区域、位置限制或位置偏差），否则前两个示例之类的请求可能会返回零个结果。

“10 High Street, UK”或“123 Main Street, US”	英国境内有多个“High Street”；美国境内有多个“Main Street”。 除非设置了位置限制，否则查询不会返回理想的结果。
“纽约连锁餐厅”	纽约有多家“连锁餐厅”；没有街道地址，甚至没有街道名称。
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US”	英国埃舍市只有一条“High Street”；美国加利福尼亚州普莱森顿市只有一条“Main Street”。
“UniqueRestaurantName New York”	纽约只有一家同名商家；无需提供街道地址即可区分。
“纽约的披萨餐厅”	此查询包含位置限制，“披萨店”是一种明确定义的位置类型。它会返回多个结果。
“[phone]”	此查询包含电话号码。它会针对与该电话号码关联的地点返回多个结果。 注意： 为获得最佳的电话号码搜索结果，请添加国家/地区代码，后跟一个空格，并将 regionCode 参数设置为与国家/地区代码相对应。 电话号码格式因国家/地区而异，API 会尝试返回这些不同格式的结果。

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

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

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

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

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

Places Swift SDK

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
}

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;
      }
    }
  }
];

“文本搜索”响应

文本搜索 API 会以 GMSPlace 对象的形式返回匹配结果数组，每个匹配的地点对应一个 GMSPlace 对象。

注意： 响应 GMSPlace 对象的字段不能为空。例如，如果字段列表包含 GMSPlacePropertyPhotos 以请求响应中的 photos 字段，并且响应中的 photos 字段为空，则会从响应 GMSPlace 对象中省略该字段。

获取营业状态

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

注意：已弃用的 GMSPlace isOpen: 和 GMSPlace isOpenAtDate: 函数可能不准确，不应与 Places API（新）搭配使用。

此方法接受一个类型为 GMSPlaceIsOpenWithRequest 的实参，其中包含：

• GMSPlace 对象或指定地点 ID 的字符串。如需详细了解如何创建包含必要字段的 Place 对象，请参阅地点详情。
  
  注意：Place 对象必须包含有效的地点 ID。
• 一个可选的 NSDate (Obj-C) 或 Date (Swift) 对象，用于指定您要检查的时间。如果未指定时间，则默认为当前时间。
• 用于处理响应的 GMSPlaceOpenStatusResponseCallback 方法。
>

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

• GMSPlacePropertyUTCOffsetMinutes
• GMSPlacePropertyBusinessStatus
• GMSPlacePropertyOpeningHours
• GMSPlacePropertyCurrentOpeningHours
• GMSPlacePropertySecondaryOpeningHours

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

isOpenWithRequest 响应

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

语言	打开时的值	关闭时的值	状态未知时的值
Places Swift	true	false	nil
Swift	.open	.closed	.unknown
Objective-C	GMSPlaceOpenStatusOpen	GMSPlaceOpenStatusClosed	GMSPlaceOpenStatusUnknown

“isOpenWithRequest”的结算卡片

• GMSPlacePropertyUTCOffsetMinutes 和 GMSPlacePropertyBusinessStatus 字段的费用计入基本数据 SKU。其余营业时间信息则按地点详情企业版 SKU 收费。
• 如果您的 GMSPlace 对象已经包含之前请求中的这些字段，则不会再次收费。
• 警告：如果您的 GMSPlace 对象不包含这些字段，您将需要再次为基本数据 SKU 付费。其余营业时间信息将按地点详情企业版 SKU 收费。如果您的项目将使用 isOpenWithRequest，我们建议您确保获取必要的地点详细信息。

示例：发出 GMSPlaceIsOpenWithRequest 请求

以下示例展示了如何在现有 GMSPlace 对象中初始化 GMSPlaceIsOpenWithRequest。

Places Swift SDK

        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
        }
        

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
            }
          }];
          

必需参数

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

• 字段列表

  指定要返回哪些地点数据属性。传递一个 GMSPlace 属性列表，用于指定要返回的数据字段。如果您省略字段掩码，请求将返回错误。

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

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

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

    GMSPlacePropertyPlaceID

  • 以下字段会触发文本搜索专业版 SKU：

    GMSPlacePropertyAddressComponents
GMSPlacePropertyBusinessStatus
GMSPlacePropertyCoordinate
GMSPlacePropertyFormattedAddress
GMSPlacePropertyIconBackgroundColor
GMSPlacePropertyIconImageURL
GMSPlacePropertyName
GMSPlacePropertyPhotos
GMSPlacePropertyPlusCode
GMSPlacePropertyTypes
GMSPlacePropertyUTCOffsetMinutes
GMSPlacePropertyViewport
GMSPlacePropertyWheelchairAccessibleEntrance

  • 以下字段会触发文本搜索企业版 SKU：

    GMSPlacePropertyCurrentOpeningHours
GMSPlacePropertySecondaryOpeningHours
GMSPlacePropertyPhoneNumber
GMSPlacePropertyPriceLevel
GMSPlacePropertyRating
GMSPlacePropertyOpeningHours
GMSPlacePropertyUserRatingsTotal
GMSPlacePropertyWebsite

  • 以下字段会触发文本搜索企业 Plus 版 SKU：

    GMSPlacePropertyCurbsidePickup
GMSPlacePropertyDelivery
GMSPlacePropertyDineIn
GMSPlacePropertyEditorialSummary
GMSPlacePropertyReservable
GMSPlacePropertyReviews
GMSPlacePropertyServesBeer
GMSPlacePropertyServesBreakfast
GMSPlacePropertyServesBrunch
GMSPlacePropertyServesDinner
GMSPlacePropertyServesLunch
GMSPlacePropertyServesVegetarianFood
GMSPlacePropertyServesWine
GMSPlacePropertyTakeout

• textQuery

  要用作搜索条件的文本字符串，例如“餐馆”“长安街 123 号”或“旧金山最佳旅游景点”。

可选参数

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

• includedType

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

  • let request = SearchByTextRequest()
request.includedType = "bar"
  • let request = SearchByTextRequest()
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。 例如：

    let request = SearchByTextRequest()
    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 视为指定结果必须靠近的区域，但结果可以位于该区域之外。

  注意： 如果您同时省略 locationBias 和 locationRestriction，则 API 默认使用 IP 偏向。借助 IP 倾向性，API 会使用设备的 IP 地址来调整结果。

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

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

  例如：

      let request = SearchByTextRequest()
      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”（从技术上讲，是指“大不列颠及北爱尔兰联合王国”这一实体）。 此参数可能会根据适用法律影响结果。

• shouldIncludePureServiceAreaBusinesses

  如果为 true，则在搜索结果中返回纯服务区域商家。纯上门服务商家是指为客户送货上门或提供上门服务，但不在自己的商家地址为客户提供服务的商家。

  例如：

  Places Swift SDK

  let request = SearchByTextRequest()
  request.shouldIncludePureServiceAreaBusinesses = true

  Swift

  let request = SearchByTextRequest()
  request.shouldIncludePureServiceAreaBusinesses: true

  Objective-C

  GMSPlaceSearchByTextRequest *request =
      [[GMSPlaceSearchByTextRequest alloc] initWithTextQuery:@"pizza in New York" placeProperties:@[GMSPlacePropertyAll]];
  request.shouldIncludePureServiceAreaBusinesses = YES;

在应用中显示提供方说明

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

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

如需了解详情，请参阅有关提供方信息的文档。