此页面由 Cloud Translation API 翻译。

附近搜索（新）

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

欧洲经济区 (EEA) 开发者

附近搜索（新）请求将要搜索的区域作为输入，该区域指定为一个圆，由圆心的纬度和经度坐标以及半径（以米为单位）定义。该请求会在指定的搜索区域内返回一个匹配地点的列表，每个地点都由一个 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();
    });

注意：如需详细了解如何初始化 PlacesClient，请参阅初始化 Places API 客户端。

“附近搜索（新）”响应

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 对象中访问数据的更多示例，请参阅访问 Place 对象数据字段。

必需参数

使用 SearchNearbyRequest 对象指定搜索所需的参数。

字段列表

请求地点详情时，您必须在 Place 对象中指定要返回的地点数据，作为字段掩码。如需定义字段掩码，请将 Place.Field 中的值数组传递给 SearchNearbyRequest 对象。使用字段遮盖是一种良好的设计做法，可确保您不会请求不必要的数据，这有助于避免产生不必要的处理时间和结算费用。

指定以下一个或多个字段：
- 以下字段会触发附近搜索专业版 SKU：
  Place.Field.ADDRESS_COMPONENTS
  Place.Field.BUSINESS_STATUS
  Place.Field.ADDRESS
  Place.Field.DISPLAY_NAME >*
  * 请使用此属性，而不是已弃用的 Place.Field.NAME。
  Place.Field.ICON_BACKGROUND_COLOR
  Place.Field.ICON_MASK_URL*
  * 请使用此属性，而不是已弃用的 Place.Field.ICON_URL。
  Place.Field.ID
  Place.Field.LAT_LNG
  Place.Field.PHOTO_METADATAS
  Place.Field.PLUS_CODE
  Place.Field.PRIMARY_TYPE
  Place.Field.PRIMARY_TYPE_DISPLAY_NAME
  Place.Field.RESOURCE_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.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.USER_RATINGS_TOTAL。
  Place.Field.WEBSITE_URI
- 以下字段会触发附近搜索 Enterprise Plus 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
注意：Places SDK for Android 的 4.0 版弃用了多个地点数据字段，并添加了新字段。如需了解详情，请参阅迁移到 Places SDK for Android 4.0 中的新地点数据字段。

如需设置字段列表参数，请在构建 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 种类型。

注意： 表 B 中的值仅在响应中返回。您无法使用表 B 中的值作为过滤条件。

一个地点只能有一个与它关联的主要类型（来自表 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、includedPrimaryTypes 和 excludedPrimaryTypes，搜索会返回位置限制范围内的所有类型地点。

如需查看如何使用 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 代码完全一致。例如，英国的 ccTLD 为“uk”(.co.uk)，而其 ISO 3166-1 代码为“gb”（从技术上讲，是指“大不列颠及北爱尔兰联合王国”这一实体）。此参数可能会根据适用法律影响结果。

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

在应用中显示提供方说明

如果应用显示从 PlacesClient 获取的信息（例如照片和评价），则还必须显示必要的提供方信息。

如需了解详情，请参阅 Places SDK for Android 的政策。

附近搜索（新） 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

“附近搜索（新）”请求

“附近搜索（新）”响应

必需参数

字段列表

位置限制

可选参数

类型和主要类型

包含的类型

排除的类型

包含的主要类型

排除的主要类型

结果数量上限

排名偏好设置

区域代码

在应用中显示提供方说明

附近搜索（新）