文本搜索（新）

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

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

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

文本搜索（新）与附近搜索（新）类似。这两者之间的主要区别在于，文本搜索（新版）允许您指定任意搜索字符串，而附近地点搜索（新版）则要求您指定要搜索的特定区域。

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

注意 ：文本搜索（新）适用于 Places SDK for Android 3.3.0 及更高版本。如需了解详情，请参阅选择 SDK 版本。如需详细了解如何使用版本 4.0.0 中添加的 Kotlin API，请参阅参考概览。

“文本搜索”请求

注意： 文本搜索是 Places SDK for Android（新版）的一部分，不适用于 Places SDK for Android。

文本搜索请求的格式如下：

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchByText(searchByTextRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

在此示例中，您需要：

• 将字段列表设置为仅包含 Place.Field.ID 和 Place.Field.DISPLAY_NAME。这意味着，响应中表示每个匹配地点的 Place 对象仅包含这两个字段。

• 使用 SearchByTextRequest.Builder 创建用于定义搜索的 SearchByTextRequest 对象。

  • 将文本查询字符串设置为“Spicy Vegetarian Food”。

  • 将结果地点数量上限设置为 10。默认值和最大值均为 20。

  • 将搜索区域限制为由纬度和经度坐标定义的矩形。系统不会返回此区域之外的匹配项。

• 添加 OnSuccessListener，然后从 SearchByTextResponse 对象获取匹配的地点。

注意：如需详细了解如何初始化 PlacesClient，请参阅初始化 Places API 客户端。

您可以使用 CancellationToken 尝试取消对任何请求类（例如 FetchPlaceRequest）的请求。取消操作会尽力完成。发出取消请求后，系统不会返回任何响应。 发出取消令牌并不能保证系统会取消特定请求，即使系统未返回任何响应，您可能仍需为该请求付费。

文本搜索响应

SearchByTextResponse 类表示搜索请求的响应。SearchByTextResponse 对象包含以下内容：

• 一个 Place 对象列表，表示所有匹配的地点，每个匹配地点对应一个 Place 对象。

• 每个 Place 对象仅包含请求中传递的字段列表定义的字段。

例如，在请求中，您可以将字段列表定义为：

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

此字段列表表示响应中的每个 Place 对象仅包含每个匹配地点的地点 ID 和名称。然后，您可以使用 Place.getId() 和 Place.getName() 方法访问每个 Place 对象中的这些字段。

如需有关访问 Place 对象中数据的更多示例，请参阅访问地点对象数据字段

必需参数

SearchByTextRequest 的必需参数如下：

• 字段列表

  指定要返回的地点数据字段。传递 Place.Field 值列表，指定要返回的数据字段。响应中没有返回字段的默认列表。

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

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

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

    Place.Field.DISPLAY_NAME、Place.Field.ID、Place.Field.RESOURCE_NAME、
    
    注意：

    • Place.Field.NAME 字段已在 Places SDK for Android 4.0 版本中废弃。请改用 Place.Field.DISPLAY_NAME。
    • RESOURCE_NAME 字段包含地点资源名称，格式为：places/PLACE_ID。使用 DISPLAY_NAME 访问地点的文本名称。

  • 以下字段会触发文本搜索（基本）SKU：

    Place.Field.ACCESSIBILITY_OPTIONS、Place.Field.ADDRESS_COMPONENTS、Place.Field.ADR_FORMAT_ADDRESS、Place.Field.BUSINESS_STATUS、Place.Field.FORMATTED_ADDRESS、Place.Field.GOOGLE_MAPS_URI、Place.Field.ICON_BACKGROUND_COLOR、Place.Field.ICON_MASK_URL、Place.Field.LOCATION、Place.Field.PHOTO_METADATAS、Place.Field.PLUS_CODE、Place.Field.PRIMARY_TYPE、Place.Field.PRIMARY_TYPE_DISPLAY_NAME、Place.Field.SHORT_FORMATTED_ADDRESS、Place.Field.SUB_DESTINATIONS、Place.Field.TYPES、Place.Field.UTC_OFFSET、Place.Field.VIEWPORT、
    
    注意：Place.Field.ADDRESS、Place.Field.ICON_URL、Place.Field.LAT_LNG 和 Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE 字段已在 Places SDK for Android 4.0 版中废弃。请改用 Place.Field.FORMATTED_ADDRESS、Place.Field.ICON_MASK_URL、Place.Field.LOCATION 和 Place.ACCESSIBILITY_OPTIONS。Place.Field.ACCESSIBILITY_OPTIONS 仅适用于“地点详情（新）”。

  • 以下字段会触发文本搜索（高级）SKU：

    Place.Field.CURRENT_OPENING_HOURS、Place.Field.CURRENT_SECONDARY_OPENING_HOURS、Place.Field.INTERNATIONAL_PHONE_NUMBER、Place.Field.NATIONAL_PHONE_NUMBER、Place.Field.OPENING_HOURS、Place.Field.PRICE_LEVEL、Place.Field.RATING、Place.Field.SECONDARY_OPENING_HOURS、Place.Field.USER_RATING_COUNT、Place.Field.WEBSITE_URI、
    
    注意：Place.Field.PHONE_NUMBER 和 Place.Field.USER_RATINGS_TOTAL 字段已在 Places SDK for Android 4.0 版中废弃。改用 Place.Field.INTERNATIONAL_PHONE_NUMBER 和 Place.USER_RATING_COUNT。

  • 以下字段会触发文本搜索（首选）SKU：

    Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT
  注意：Places SDK for Android 4.0 版本废弃了多个地点数据字段，并添加了新字段。如需了解详情，请参阅迁移到 Places SDK for Android 4.0 中的新地点数据字段 。

  如需设置字段列表参数，请在构建 SearchByTextRequest 对象时调用 setPlaceFields() 方法。

• 文本查询

  要搜索的文本字符串，例如“餐厅”“长安街 123 号”或“旧金山最佳旅游地”。该 API 会根据此字符串返回候选匹配项，并按照其判断的相关程度对结果排序。

  如需设置文本查询参数，请在构建 SearchByTextRequest 对象时调用 setTextQuery() 方法。

可选参数

使用 SearchByTextRequest 对象为请求指定可选参数。

• 包含的内容类型

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

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  注意 ：表 B 中的值仅在响应中返回。您不能将表 B 中的值用作过滤条件。

  如需设置包含的类型参数，请在构建 SearchByTextRequest 对象时调用 setIncludedType() 方法。

• 位置偏差

  指定要搜索的区域。此位置用作偏向，这意味着系统可以返回指定位置周围的结果，包括指定区域之外的结果。

  您可以指定地理位置限制或地理位置偏向，但不能同时指定这两者。您可以将位置限制视为指定结果必须位于的区域，将位置自定义调整视为指定结果可能位于或靠近的区域。请注意，使用位置自定义调整时，结果可能仍会位于指定区域之外。

  注意： 如果您同时忽略了位置偏向和位置限制，则该 API 默认会使用 IP 偏向。使用 IP 偏向时，API 会使用设备的 IP 地址来偏向结果。
  注意： 如果 textQuery 包含显式位置（例如 Market in Barcelona），则可以替换 locationBias 参数。 在这种情况下，系统会忽略 locationBias。

  将区域指定为矩形视口或圆形。

  • 圆形由中心点和半径（以米为单位）定义。半径必须介于 0.0 到 50000.0 之间（包括这两个数值）。 例如：

    // Define latitude and longitude coordinates of the center of the search area.
    LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);
    
    // Use the builder to create a SearchByTextRequest object.
    // Set the radius of the search area to 500.0 meters.
    final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
      .setMaxResultCount(10)
      .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();
    

  • 矩形是纬度-经度视口，表示为两个对角线对应的低点和高点。最低点标记矩形的西南角，最高点代表矩形的东北角。

    视口被视为封闭区域，即包含其边界。纬度边界必须介于 -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，则纬度范围为空。

    必须填充下限和上限，并且表示相应值的框不能为空。空视口会导致错误。

    例如，如需了解矩形视口，请参阅文本搜索请求。

    如需设置位置偏差参数，请在构建 SearchByTextRequest 对象时调用 setLocationBias() 方法。

• 地理位置限制

  指定要搜索的区域。系统不会返回指定区域以外的结果。将区域指定为矩形视口。如需了解如何定义视口，请参阅位置偏差的说明。

  您可以指定地理位置限制或地理位置偏向，但不能同时指定这两者。您可以将位置限制视为指定结果必须位于其中的区域，将位置偏向视为指定结果必须位于附近但可以位于该区域之外的区域。

  注意： 如果您同时忽略了位置偏向和位置限制，则该 API 默认会使用 IP 偏向。使用 IP 偏向时，API 会使用设备的 IP 地址来偏向结果。

  如需设置位置限制参数，请在构建 SearchByTextRequest 对象时调用 setLocationRestriction() 方法。

• 结果数上限

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

  如需设置结果数量上限参数，请在构建 SearchByTextRequest 对象时调用 setMaxResultCount() 方法。

• 最低评分

  仅限于平均用户评分高于或等于此上限的结果。值必须介于 0.0 到 5.0 之间（包括这两个数值），增量为 0.5。例如：0、0.5、1.0、...、5.0（包括这两个数值）。值会向上舍入到最接近的 0.5。例如，如果值为 0.6，则会移除所有评分低于 1.0 的结果。

  如需设置最低分级参数，请在构建 SearchByTextRequest 对象时调用 setMinRating() 方法。

• 营业中

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

  如需设置“立即打开”参数，请在构建 SearchByTextRequest 对象时调用 setOpenNow() 方法。

• 价位

  默认情况下，搜索结果会包含提供不同价位服务的地点。如需将结果限制为仅包含特定价位的地点，您可以传递一个整数值列表，该列表与您要返回的地点的价位相对应：

  • 1 - 地点提供价格实惠的服务。
  • 2 - 地点提供价格适中的服务。
  • 3 - 地点提供价格昂贵的服务。
  • 4 - 地点提供的服务价格非常高。
  注意： 0 的整数值（表示相应地点提供免费服务）可能会包含在响应中，但不能用作请求中的过滤条件值。

  如需设置价格层级参数，请在构建 SearchByTextRequest 对象时调用 setPriceLevels() 方法。

• 排名偏好设置

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

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

  如需设置排名偏好参数，请在构建 SearchByTextRequest 对象时调用 setRankPreference() 方法。

• 区域代码

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

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

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

  如需设置地区代码参数，请在构建 SearchByTextRequest 对象时调用 setRegionCode() 方法。

• 严格类型过滤

  与 include 类型参数搭配使用。设置为 true 时，系统仅返回与“include type”指定的指定类型匹配的地点。 如果为 false（默认值），响应中可能会包含与指定类型不匹配的地点。

  如需设置严格类型过滤参数，请在构建 SearchByTextRequest 对象时调用 setStrictTypeFiltering() 方法。