Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

附近搜索（新）

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

欧洲经济区 (EEA) 的开发者

“附近搜索（新）”请求以要搜索的区域作为输入，该区域指定为一个圆形，由圆心的纬度和经度坐标以及半径（以米为单位）定义。该请求会在指定的搜索区域内返回匹配地点的列表，每个地点都由一个 Place 对象表示。

默认情况下，响应包含搜索区域内的所有类型的地点。您可以选择指定要明确包含在响应中或从响应中排除的地点类型列表，以过滤响应。例如，您可以指定仅在响应中包含类型为“餐厅”“面包店”和“咖啡馆”的地点，或排除所有类型为“学校”的地点。

“附近搜索（新）”请求

如需发出“附近搜索（新）”请求，请调用 PlacesClient.searchNearby, 并传递一个 SearchNearbyRequest 对象，该对象定义了请求参数。

SearchNearbyRequest 对象指定了请求的所有必需参数和可选参数。必需参数包括：

要在 Place 对象中返回的字段列表，也称为字段掩码。如果您未在字段列表中指定至少一个字段，或者省略了字段列表，则调用会返回错误。
搜索区域的位置限制，定义为纬度/经度对和半径值（以米为单位）。

此示例“附近搜索”请求指定，响应 Place 对象包含搜索结果中每个 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);

// 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 客户端。

“附近搜索（新）”响应

The 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 对象中数据的更多示例，请参阅 Access Place object data fields。

必需参数

使用 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
- 以下字段会触发“附近搜索企业 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
如需设置字段列表参数，请在构建 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" 的地点。响应包含与 至少一个 匹配且与任何 excludedTypes 都不匹配的地点。includedTypes

如果存在任何冲突的类型（例如，某个类型同时出现在 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 政策。

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

“附近搜索（新）”请求

“附近搜索（新）”响应

必需参数

字段列表

位置限制

可选参数

类型和主要类型

包含的类型

排除的类型

包含的主要类型

排除的主要类型

结果数量上限

排名偏好设置

区域代码

在应用中显示提供方说明

附近搜索（新）