附近搜索（新）

请选择平台： 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();
    });

“附近搜索（新）”响应

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 的完整列表，请参阅 地点数据字段（新）。

    • 以下字段会触发“附近搜索 企业版 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

      如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。

    • 以下字段会触发“附近搜索 企业 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

      如需查看字段及其关联 SKU 的完整列表，请参阅 地点数据字段（新）。

    如需设置字段列表参数，请在构建 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（默认值）之间（含 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 政策。