“附近搜索(新)”请求将指定为圆形的搜索区域作为输入,由圆形中心点的纬度和经度坐标以及半径(以米为单位)定义。该请求会返回指定搜索区域内的匹配地点列表,其中每个地点都由一个 Place
对象表示。
默认情况下,响应包含搜索区域内所有类型的地点。您可以选择性地过滤响应,方法是指定要在响应中明确包含或排除的地点类型列表。例如,您可以指定在响应中仅包含“餐馆”“面包店”和“咖啡馆”类型的地点,或者排除“学校”类型的所有地点。
“附近搜索(新)”请求
通过调用 PlacesClient.searchNearby
并传递用于定义请求参数的 SearchNearbyRequest
对象,发出“附近搜索(新)”请求。
SearchNearbyRequest
对象指定了请求的所有必需参数和可选参数。必需参数包括:
Place
对象中要返回的字段列表,也称为字段掩码。如果您没有在字段列表中指定至少一个字段,或省略字段列表,则调用会返回错误。- 搜索区域的位置限制,定义为纬度/经度对和半径值(以米为单位)。
此示例附近搜索请求指定响应 Place
对象包含搜索结果中每个 Place
对象的地点字段 Place.Field.ID
和 Place.Field.NAME
。它还会过滤响应,以便仅返回“餐馆”和“咖啡馆”类型的地点,但排除“pizza_restaurant”和“american_restaurant”类型的地点。
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME); // Define the search area as a 1000 meter diameter circle in New York, NY. LatLng center = new LatLng(40.7580, -73.9855); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000); // Define a list of types to include. final List<String> includedTypes = Arrays.asList("restaurant", "cafe"); // Define a list of types to exclude. final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant"); // Use the builder to create a SearchNearbyRequest object. final SearchNearbyRequest searchNearbyRequest = SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields) .setIncludedTypes(includedTypes) .setExcludedTypes(excludedTypes) .setMaxResultCount(10) .build()); // Call placesClient.searchNearby() to perform the search. // Define a response handler to process the returned List of Place objects. placesClient.searchNearby(searchNearbyRequest) .addOnSuccessListener(response -> { List<Place> places = response.getPlaces(); });
附近搜索(新)响应
SearchNearbyResponse
类表示来自搜索请求的响应。SearchNearbyResponse
对象包含:
- 代表所有匹配地点的
Place
对象列表,每个匹配地点都有一个Place
对象。 - 每个
Place
对象仅包含由请求中传递的字段列表定义的字段。
例如,您在请求中定义了一个字段列表,如下所示:
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
此字段列表意味着响应中的每个 Place
对象仅包含每个匹配地点的地点 ID 和名称。然后,您可以使用 Place.getId()
和 Place.getName()
方法访问每个 Place
对象中的这些字段。
如需查看访问 Place
对象中数据的更多示例,请参阅访问地点对象数据字段。
必需参数
使用 SearchNearbyRequest
对象指定搜索所需的参数。
字段列表
请求地点详情时,您必须在地点的
Place
对象中以字段掩码的形式指定要返回的数据。如需定义字段掩码,请将Place.Field
中的值数组传递给SearchNearbyRequest
对象。字段遮盖是一种很好的设计做法,可确保您不会请求不必要的数据,这有助于避免不必要的处理时间和结算费用。指定以下一个或多个字段:
以下字段会触发附近搜索(基本)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.ID
、Place.Field.NAME
、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
如需设置字段列表参数,请在构建
SearchNearbyRequest
对象时调用setPlaceFields()
方法。以下示例定义了包含两个字段值的列表,用于指定请求返回的
Place
对象包含Place.Field.ID
和Place.Field.NAME
字段:
// Define a list of fields to include in the response for each returned place. final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);
位置限制
LocationRestriction
对象,用于定义以圆形表示的搜索区域,由中心点和半径(以米为单位)定义。半径必须介于 0.0 到 50000.0 之间,请注意,如果指定太小的半径,系统会返回ZERO_RESULTS
作为响应。如需设置位置限制参数,请在构建
SearchNearbyRequest
对象时调用setLocationRestriction()
方法。
可选参数
使用 SearchNearbyRequest
对象指定用于搜索的可选参数。
-
类型和主要类型
允许您指定表 A 中用于过滤搜索结果的类型的列表。在每个类型限制类别中,最多可以指定 50 种类型。
一个地点只能具有与其关联的表 A 类型中的一个主要类型。例如,主要类型可能是
"mexican_restaurant"
或"steak_house"
。使用includedPrimaryTypes
和excludedPrimaryTypes
按地点主要类型过滤结果。一个地点还可以具有与之关联的表 A 类型的多个类型值。例如,餐馆可能具有以下类型:
"seafood_restaurant"
、"restaurant"
、"food"
、"point_of_interest"
、"establishment"
。使用includedTypes
和excludedTypes
过滤与地点相关联的类型列表中的结果。如果搜索指定了多种类型限制,系统仅返回满足所有限制的地点。例如,如果您指定
includedTypes = Arrays.asList("restaurant")
和excludedPrimaryTypes = Arrays.asList("steak_house")
,返回的地点会提供与"restaurant"
相关的服务,但并不主要作为"steak_house"
运行。如需查看如何使用
includedTypes
和excludedTypes
的示例,请参阅“附近搜索(新)”请求。包含的类型
表 A 中要搜索的地点类型列表。如果省略此参数,则返回所有类型的地点。
如需设置包含的类型参数,请在构建
SearchNearbyRequest
对象时调用setIncludedTypes()
方法。排除的类型
表 A 中要从搜索中排除的地点类型列表。
如果您在请求中同时指定了
includedTypes
(例如"school"
)和excludedTypes
(例如"primary_school"
),响应会包含归类为"school"
而非"primary_school"
的地点。响应包含与includedTypes
中至少一个匹配但与excludedTypes
都不匹配的地点。如果存在任何冲突的类型(例如
includedTypes
和excludedTypes
中出现的某个类型),则会返回INVALID_REQUEST
错误。如需设置排除的类型参数,请在构建
SearchNearbyRequest
对象时调用setExcludedTypes()
方法。包含的主要类型
表 A 中要添加到搜索中的主要地点类型列表。
如需设置包含的主要类型参数,请在构建
SearchNearbyRequest
对象时调用setIncludedPrimaryTypes()
方法。排除的主要类型
表 A 中要从搜索中排除的主要地点类型列表。
如果主要类型(例如
includedPrimaryTypes
和excludedPrimaryTypes
都存在某个类型)存在任何冲突,系统会返回INVALID_ARGUMENT
错误。如需设置排除的主要类型参数,请在构建
SearchNearbyRequest
对象时调用setExcludedPrimaryTypes()
方法。 -
结果数上限
指定要返回的地点结果的数量上限。必须介于 1 和 20(默认值)之间,包括 1 和 20。
如需设置结果数量上限参数,请在构建
SearchNearbyRequest
对象时调用setMaxResultCount()
方法。 -
排名期望
要使用的排名类型。如果省略此参数,则结果会按热门程度排名。可能为以下其中一项:
POPULARITY
(默认)根据结果的热门程度对结果进行排序。DISTANCE
:按结果与指定位置的距离以升序对结果进行排序。
如需设置排名偏好设置参数,请在构建
SearchNearbyRequest
对象时调用setRankPreference()
方法。 -
区域代码
用于设置响应格式的地区代码,以 双字符 CLDR 代码值的形式指定。没有默认值。
如果响应中
formattedAddress
字段的国家/地区名称与regionCode
匹配,则formattedAddress
中省略国家/地区代码。除了某些明显的例外情况之外,大多数 CLDR 代码都与 ISO 3166-1 代码相同。例如,英国的 ccTLD 为“uk”(.co.uk),而其 ISO 3166-1 代码为“gb”(专指“大不列颠及北爱尔兰联合王国”)。 该参数可能会影响根据适用法律的结果。
如需设置地区代码参数,请在构建
SearchNearbyRequest
对象时调用setRegionCode()
方法。
在应用中显示提供方说明
如果您的应用要显示通过 PlacesClient
获取的信息(例如照片和评价),还必须显示必要的提供方说明。
如需了解详情,请参阅 Places SDK for Android 政策。