文本搜索（新）

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

欧洲经济区 (EEA) 开发者

文本搜索（新）可以根据一个字符串（例如，“北京烤鸭”“南京附近的鞋店”或“长安街 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 对象中获取匹配的地点。

“文本搜索”响应

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 对象数据字段

必需参数

SearchByTextRequest 的必需参数如下：

  • 字段列表

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

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

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

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

      Place.Field.DISPLAY_NAME*
          * 请使用此属性，而不是 Place.Field.NAME（在版本 4.0 中已弃用）。
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * 包含地点资源名称，格式为：places/PLACE_ID。
           使用 DISPLAY_NAME 访问地点的文本名称。

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

      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

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

    如需设置字段列表参数，请在构建 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（按距离对结果进行排名）。
    • 对于“Mountain View, CA”等非类别查询，我们建议您将排名偏好参数保持未设置状态。

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

  • 区域代码

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

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

    除了某些明显的例外情况之外，大多数 CLDR 代码都与 ISO 3166-1 代码完全一致。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（从技术上讲，是指“大不列颠及北爱尔兰联合王国”这一实体）。 此参数可能会根据适用法律影响结果。

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

  • 严格的类型过滤

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

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