文本搜索

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

该服务对于在自动化系统中进行模糊地址查询特别有用，并且字符串的非地址组成部分可以与商家以及地址匹配。模糊地址查询的示例包括格式错误的地址，或包含商家名称等非地址组成部分的请求。除非设置了位置（例如地区、位置限制或位置偏向），否则前两个示例等请求可能返回零结果。

“10 High Street, UK”或“123 Main Street, US” 英国有多个“High Street”；美国有多个“Main Street”。 除非设置了位置限制，否则查询不会返回所需的结果。
“纽约连锁餐厅” 纽约有多个“ChainRestaurant”分店；没有街道地址，甚至没有街道名称。
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US” 只有一条位于英国埃舍尔市的“高街”；在美国加利福尼亚州普莱森顿市只有一条“主街”。
“纽约 UniqueRestaurantName” 在纽约只有一家使用此名称的场所；无需使用街道地址进行区分。
“北京烤鸭店” 此查询包含其位置限制，“北京烤鸭”是一种定义明确的地点类型。它会返回多个结果。
“+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.ID 和 Place.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 对象中数据的更多示例，请参阅访问地点对象数据字段

必需参数

  • 字段列表

    指定要返回的地点数据字段。传递 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

  • 文本查询

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

可选参数

请使用 SearchByTextRequest.Builder 的方法设置这些参数。例如，如需设置结果数上限，请调用 SearchByTextRequest.Builder.setMaxResultCount()。

  • 包含的类型

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

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

  • 位置偏向

    指定要搜索的区域。此位置充当偏差，这意味着可以返回指定位置周围的结果，包括指定区域以外的结果。

    您可以指定位置限制或位置偏向，但不能同时指定这两者。您可以将位置限制视为指定结果必须在哪个区域，将位置偏向视为指定结果必须靠近但可以超出该区域的区域。

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

    • 圆形由中心点和半径（以米为单位）定义。半径必须介于 0.0 和 50000.0 之间（含 0.0 和 50000.0）。默认半径为 0.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，则纬度范围为空。

      必须填充“低”和“高”，并且表示的框不能为空。空视口会导致错误。

      例如，对于矩形视口，请参阅“文本搜索请求”。

  • 位置限制

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

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

  • 结果数上限

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

  • 最低评分

    将结果限制为平均用户评分大于或等于此上限的结果。值必须介于 0.0 和 5.0 之间（含 0.0 和 5.0），以 0.5 为增量。例如：0、0.5、1.0、...、5.0（含 0 和 5.0）。值会四舍五入到最接近的 0.5。例如，值为 0.6 会排除评分低于 1.0 的所有结果。

  • 营业中

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

  • 价位

    将搜索范围限制为特定价位的地点。 默认设置是选择所有价位。

    指定由以下一个或多个整数值组成的列表：

    • 1 - PRICE_LEVEL_INEXPENSIVE
    • 2 - PRICE_LEVEL_MODERATE
    • 3 - PRICE_LEVEL_EXPENSIVE
    • 4 - PRICE_LEVEL_VERY_EXPENSIVE

  • 排名期望

    指定结果在响应中的排名方式。在适用的情况下，该 API 默认使用 RELEVANCE。例如，对于“纽约市餐厅”之类的查询，系统将使用默认值 RELEVANCE。对于地理位置查询（例如“加利福尼亚州山景城”）或其他类型的查询，系统不会应用任何默认值，并且结果会按照后端返回的顺序显示。

    相关的值包括：

    • SearchByTextRequest.RankPreference.DISTANCE：按距离对结果排名。
    • SearchByTextRequest.RankPreference.RELEVANCE：按相关性对结果排名。

  • 区域代码

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

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

    除了某些明显的例外情况之外，大多数 CLDR 代码都与 ISO 3166-1 代码相同。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（专指“大不列颠及北爱尔兰联合王国”）。 该参数可能会影响根据适用法律的结果。

  • 严格类型过滤

    与包含类型参数一起使用。设置为 true 时，系统仅返回与包含类型指定的指定类型相匹配的地点。 默认情况下，如果为 false，响应可以包含与指定类型不匹配的地点。