文本搜索（新）

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

除了必需参数之外， 文本搜索（新）还支持使用可选 参数优化查询，以获得更好的结果。

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

文本搜索请求

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

// 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 对象获取匹配的地点。

文本搜索响应

The 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 对象中数据的示例，请参阅 访问 Place 对象数据字段

分页

文本搜索的 SearchByTextResponse 类通过其 getPagination() 方法提供对文本搜索结果分页的访问权限，该方法会返回 Pagination 对象。

使用 Pagination 对象的 hasNextPage() 方法确定是否有其他结果页可用。此方法会返回布尔值（true 或 false）。

当 hasNextPage() 返回 true 时，调用 fetchNextPage() 方法来检索下一页结果。

以下示例展示了如何检查是否有下一页，然后加载该页面。

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

必需参数

的必需参数包括：SearchByTextRequest

• 字段列表

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

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

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

  • 以下字段会触发文本搜索 Essentials ID Only SKU：

    Place.Field.DISPLAY_NAME*
        * 请改用 Place.Field.NAME（已在 4.0 版中废弃）。
    Place.Field.ID
Place.Field.RESOURCE_NAME*
        * 包含格式为 places/PLACE_ID 的地点资源名称。
    使用 DISPLAY_NAME 访问地点的文本名称。

    如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。

  • 以下字段会触发文本搜索 Pro SKU：

    Place.Field.ACCESSIBILITY_OPTIONS*
        请改用 Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE（已废弃）。
    Place.Field.ADDRESS_COMPONENTS
Place.Field.ADR_FORMAT_ADDRESS
Place.Field.BUSINESS_STATUS
Place.Field.FORMATTED_ADDRESS*
        请改用 Place.Field.ADDRESS（已废弃）。
    Place.Field.GOOGLE_MAPS_URI
Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL *
        请改用 Place.Field.ICON_URL（已废弃）。
    Place.Field.LOCATION*
       请改用 Place.Field.LAT_LNG（已废弃）。
    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

    如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。

  • 以下字段会触发文本搜索 Enterprise SKU：

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
        * 请改用 Place.Field.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.USER_RATINGS_TOTAL（已 废弃）。
    Place.Field.WEBSITE_URI

    如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。

  • 以下字段会触发文本搜索企业 Plus 版 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

    如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。

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

• 文本查询

  要用作搜索条件的文本字符串，例如“餐馆” “长安街 123 号”或“旧金山最佳旅游景点”。API 会根据此字符串返回候选匹配结果，并按照其判断的相关性对结果进行排序。

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

可选参数

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

• 包含的内容类型

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

  • setIncludedType("bar")
  • setIncludedType("pharmacy")

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

• 位置偏向

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

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

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

  • 圆形由中心点和半径（以米为单位）定义。半径 必须介于 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() 方法。

• 位置限制

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

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

  如需设置位置限制参数，请在构建 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 - 地点提供价格非常昂贵的服务。

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

• 排名偏好

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

  • 对于分类查询（例如“纽约市的餐馆”）， SearchByTextRequest.RankPreference.RELEVANCE（按搜索相关性对结果进行排名）是默认值。 您可以将排名偏好设置为 SearchByTextRequest.RankPreference.RELEVANCE 或 SearchByTextRequest.RankPreference.DISTANCE（按距离对结果进行排名）。
  • 对于非分类查询（例如“加利福尼亚州山景城”），我们建议您将排名偏好参数保留为未设置状态。

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

• 区域代码

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

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

  大多数 CLDR 代码都与 ISO 3166-1 代码相同， 但也有一些需要注意的例外情况。例如，英国的 ccTLD 为 “uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（代表“大不列颠及北爱尔兰联合王国”）。 此参数可能会根据适用法律影响结果。

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

• 严格类型过滤

  与包含的内容类型参数搭配使用。如果设置为 true，则仅返回与包含的内容类型指定的类型相匹配的地点。 如果为 false（默认值），则响应可能包含与指定类型不匹配的地点。

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