“附近搜索（新）”请求将以圆形指定的搜索区域作为输入，该区域由圆心点的纬度和经度坐标以及半径（以米为单位）定义。该请求会返回指定搜索区域内匹配地点的列表，每个地点都由 Place 对象表示。
默认情况下，响应包含搜索区域内所有类型的地点。您可以选择过滤响应，方法是指定要明确包含或排除在响应中的地点类型列表。例如，您可以指定仅在响应中包含类型为“餐厅”“面包店”和“咖啡馆”的场所，或排除所有类型为“学校”的场所。
“附近搜索（新）”请求
通过调用 PlacesClient.searchNearby 发出“附近搜索（新）”请求，并传递用于定义请求参数的 SearchNearbyRequest 对象。
SearchNearbyRequest 对象指定请求的所有必需参数和可选参数。必需参数包括：
- 要在
Place对象中返回的字段列表，也称为字段掩码。如果您未在字段列表中指定至少一个字段，或者您忽略了字段列表，则调用将返回错误。 - 搜索区域的位置限制，定义为纬度/经度对和半径值（以米为单位）。
以下附近搜索请求示例指定了响应 Place 对象包含搜索结果中每个 Place 对象的地点字段 Place.Field.ID 和 Place.Field.DISPLAY_NAME。它还会过滤响应，仅返回类型为“restaurant”和“cafe”的地点，但会排除类型为“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.DISPLAY_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.PRIMARY_TYPE、Place.Field.PRIMARY_TYPE_DISPLAY_NAME、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.CURRENT_SECONDARY_OPENING_HOURS、Place.Field.INTERNATIONAL_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.WEBSITE_URI、
以下字段会触发附近搜索（首选）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
如需设置字段列表参数，请在构建
SearchNearbyRequest对象时调用setPlaceFields()方法。以下示例定义了两个字段值的列表，以指定请求返回的
Place对象包含Place.Field.ID和Place.Field.DISPLAY_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.DISPLAY_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过滤与地点关联的类型列表中的结果。如果您指定了一般的主要类型（例如
"restaurant"或"hotel"），响应中可能会包含主要类型比指定类型更具体的地点。例如，您可以指定要包含主要类型"restaurant"。然后，响应可以包含主类型为"restaurant"的地点，但也可以包含主类型更具体的地点，例如"chinese_restaurant"或"seafood_restaurant"。如果在指定搜索时设置了多个类型限制，系统只会返回满足所有限制的地点。例如，如果您指定
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（默认值）之间。
如需设置结果数量上限参数，请在构建
SearchNearbyRequest对象时调用setMaxResultCount()方法。 -
排名偏好设置
要使用的排名类型。如果省略此参数，则结果会按热门程度排序。 可能是以下某种原因：
POPULARITY（默认）按热门程度对结果进行排序。DISTANCE按结果与指定地点之间的距离以升序对结果进行排序。
如需设置排名偏好参数，请在构建
SearchNearbyRequest对象时调用setRankPreference()方法。 -
区域代码
用于设置响应格式的地区代码，指定为 两个字符的 CLDR 代码值。没有默认值。
如果响应中
FORMATTED_ADDRESS字段的国家/地区名称与regionCode匹配，则FORMATTED_ADDRESS中会省略国家/地区代码。大多数 CLDR 代码与 ISO 3166-1 代码相同，但有一些明显的例外。例如，英国的国家代码顶级域名为“uk”(.co.uk)，而其 ISO 3166-1 代码却是“gb”（专指“大不列颠及北爱尔兰联合王国”这一实体）。 此参数可能会根据适用法律影响结果。
如需设置地区代码参数，请在构建
SearchNearbyRequest对象时调用setRegionCode()方法。
在应用中显示提供方说明
如果您的应用要显示通过 PlacesClient 获取的信息（例如照片和评价），则该应用还必须显示必要的提供方说明。
如需了解详情，请参阅 适用于 Places SDK for Android 的政策。