文本搜索(新)

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

文本搜索(新)可返回一组 基于字符串(例如“北京烤鸭”)的地点或“鞋店” Ottawa 附近”或“长安街 123 号”。该服务会返回地点列表 文本字符串和任何已设置的位置自定义调整值。

该服务特别适合用于使地址模糊不清的地址 查询。 和非地址部分可以匹配商家以及 地址。模糊地址查询示例是格式不正确的地址 或包含商家名称等非地址组成部分的请求。请求数 如前两个示例所示,可能返回零个结果,除非指定位置 - (如区域、位置限制或位置偏向)的值。

文本搜索(新)类似于附近搜索 (新)。主要 两者的区别在于文本搜索(新) 可让您指定任意搜索字符串,而“附近搜索(新)”要求使用 特定区域进行搜索。

“英国,高街 10 号”或“123 Main Street, US” 英国的多个“高街”;美国的多条“主街” 除非位置限制是 。
“纽约连锁餐馆” 多个“连锁餐厅”位于纽约的分店;无街道地址或 甚至街道名称。
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US” 仅一条“高街”英国埃舍尔市;只有一个“Main Street” 位于美国加利福尼亚州普莱森顿
“UniqueRestaurantName New York” 纽约只有一个具有此名称的场所;无街道地址 进行区分
“北京烤鸭店” 此查询包含其位置限制以及“北京烤鸭店”为 明确定义的地点类型该方法会返回多个结果。
“+1 514-670-8700”

此查询包含电话号码。它会针对以下查询返回多个结果: 显示与该电话号码相关的地点

“文本搜索”请求

“文本搜索”请求的格式如下:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.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.IDPlace.Field.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.NAME);

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

如需查看访问 Place 对象中数据的更多示例,请参阅访问地点 对象数据字段

必需参数

使用 SearchByTextRequest 分别是:

  • 字段列表

    指定要返回的地点数据字段。将 Place.Field 值。没有 返回的字段。

    字段列表是一种很好的设计做法,可确保您不会为 不必要的数据,这有助于避免不必要的处理时间和 结算费用。

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

    • 以下字段会触发文本搜索(仅 ID)SKU

      Place.Field.ID, Place.Field.NAME
    • 以下字段会触发文本搜索(基本)SKU

      Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE
    • 以下字段会触发文本搜索(高级)SKU

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI
    • 以下字段会触发文本搜索(首选)SKU

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, 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 之间(含 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 度之间(包括 -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(默认值),包括 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,则返回所有商家 而无论打开状态如何 未在 Google Places 数据库中指定营业时间的地点为 返回 false

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

  • 价位

    默认情况下,搜索结果会包含提供各种价位服务的地点。限制 结果以仅包含特定价位的场所,那么您可以传递 与要返回的地点的价位相对应的整数值:

    • 1 - 地点提供廉价服务。
    • 2 - 该地点提供的服务价格适中。
    • 3 - 地点提供昂贵的服务。
    • 4 - 地点提供的服务费用非常高昂。

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

  • 排名期望

    指定如何根据 查询:

    • 对于像“Restaurants in New York City”这样的分类查询, 默认值为 SearchByTextRequest.RankPreference.RELEVANCE(按搜索相关性对结果排名)。 您可以将排名期望设置为 SearchByTextRequest.RankPreference.RELEVANCESearchByTextRequest.RankPreference.DISTANCE(按距离对结果排名)。
    • 对于非分类查询(例如“Mountain View, CA”),我们建议 排名期望参数未设置。

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

  • 区域代码

    用于设置响应格式的地区代码,指定为 两个字符的 CLDR 代码值。此参数也可能具有偏差效应 。没有默认值。

    如果响应中地址字段的国家/地区名称与 区号,则地址中省略了国家/地区代码。

    大多数 CLDR 代码与 ISO 3166-1 代码相同, 但有一些值得注意的例外情况。例如,英国的 ccTLD 为 "uk"(.co.uk),而其 ISO 3166-1 代码为“gb”(从技术层面来讲, “大不列颠及北爱尔兰联合王国”)。 根据适用法律,该参数可能会影响结果。

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

  • 严格类型过滤

    与包含类型参数一起使用。设置为 true,则仅搜索与由 返回 include 类型。 如果值为 false(默认值),则响应可以包含 与指定的类型不匹配。

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