文本搜索(新)可以根据一个字符串(例如,“北京烤鸭”“南京附近的鞋店”或“长安街 8 号”)返回一组地点的相关信息。该服务会返回与文本字符串和任何位置偏向设置相匹配的地点列表。
该服务特别适合在自动化系统中进行地址模糊查询,字符串的非地址组成部分可能与商家以及地址匹配。模糊地址查询的示例包括格式不正确的地址,或包含商家名称等非地址组成部分的请求。除非设置了位置(例如区域、位置限制或位置偏向),否则与前两个示例相关的请求可能不会返回任何结果。
文本搜索(新)与附近搜索(新)类似。两者之间的主要区别在于,文本搜索(新)可让您指定任意搜索字符串,而附近搜索(新)需要特定区域进行搜索。
“10 High Street, UK”或“123 Main Street, US” | 英国有多个“高街”;美国有多条“主街”。 除非设置了位置限制,否则查询不会返回所需的结果。 |
“纽约连锁餐馆” | 纽约的多个“ChainRestaurant”营业地点;没有街道地址,甚至没有街道名称。 |
“10 High Street, Escher UK”或“123 Main Street, Pleasanton US” | 英国埃舍尔市只有一条“高街”;在美国加利福尼亚州普莱森顿市只有一条“主街”。 |
“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.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
对象中数据的更多示例,请参阅访问地点对象数据字段
必需参数
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 度(含)之间:
- 如果
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()
方法。严格类型过滤
与包含类型参数一起使用。设置为
true
时,系统仅返回与 include 类型指定的指定类型相匹配的地点。 如果为false
(默认值),响应可以包含与指定类型不匹配的地点。如需设置严格类型过滤参数,请在构建
SearchByTextRequest
对象时调用setStrictTypeFiltering()
方法。