附近搜索(新)

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

“附近搜索(新)”请求会将区域作为输入 要以圆形表示的搜索, 圆心点的坐标和半径(以米为单位)。通过 请求会返回匹配地点列表,每个地点都由 Place 对象。

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

“附近搜索(新)”请求

通过调用以下方法来发出“附近搜索(新)”请求 PlacesClient.searchNearby、 通过一个 SearchNearbyRequest 该对象定义了请求参数。

SearchNearbyRequest 对象指定所有必需和可选 参数。必需的参数包括:

  • Place 对象中要返回的字段列表,也称为 字段掩码。如果您没有在字段列表中指定至少一个字段,或者如果 则调用将返回错误。
  • 搜索区域的位置限制,定义为 纬度/经度对和半径值(以米为单位)。

此示例附近搜索请求指定响应 Place 对象 包含地点字段 Place.Field.IDPlace.Field.NAME,每个 Place 对象。它还会过滤响应 返回“餐馆”类型的地点和“咖啡馆”,但排除以下类型的地点 “北京烤鸭”和“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

    要设置字段列表参数,请调用 setPlaceFields() 方法。SearchNearbyRequest

    以下示例定义了两个字段值的列表,以指定 请求返回的 Place 对象包含 Place.Field.IDPlace.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 作为响应。

    要设置位置限制参数,请调用 setLocationRestriction() 方法。SearchNearbyRequest

可选参数

使用 SearchNearbyRequest 对象来指定搜索的可选参数。

  • 类型和主要类型

    允许您从类型中指定类型列表 表 A 用于过滤 搜索结果。每个类型限制类别中最多可以指定 50 种类型。

    一个地点只能有一个主要类型 表 A 中关联的 。例如,主要类型可能是 "mexican_restaurant""steak_house"。使用 按 includedPrimaryTypesexcludedPrimaryTypes 过滤结果 地点的主要类型。

    地点还可以具有来自类型的多个类型值 表 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" 的形式指定。

    如需查看有关如何使用 includedTypesexcludedTypes 的示例,请参阅 “附近搜索(新)”请求

    包含的类型

    来自以下来源的地点类型列表: 要搜索的表 A。 如果省略此参数,则返回所有类型的地点。

    如需设置包含的类型参数,请在构建 SearchNearbyRequest 对象时调用 setIncludedTypes() 方法。

    排除的类型

    来自以下来源的地点类型列表: 表 A:要从 搜索。

    如果您同时指定 includedTypes(例如 "school")和 excludedTypes(例如 "primary_school"),则将 响应包含归类为"school"但不属于 "primary_school"。响应包含与以下至少一个匹配的地点: includedTypes没有 excludedTypes

    如果存在任何冲突的类型(例如某个类型同时出现在两个 includedTypes 中) 和 excludedTypes,则会返回 INVALID_REQUEST 错误。

    如需设置排除的类型参数,请在构建 SearchNearbyRequest 对象时调用 setExcludedTypes() 方法。

    包含的主要类型

    来自以下来源的主要地点类型列表: 表 A 包含的内容 。

    如需设置包含的主要类型参数,请在构建 SearchNearbyRequest 对象时调用 setIncludedPrimaryTypes() 方法。

    排除的主要类型

    来自以下来源的主要地点类型列表: 表 A:要排除的项目 。

    如果存在任何存在冲突的主要类型,例如某个类型同时出现在 includedPrimaryTypesexcludedPrimaryTypes 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 政策 Android 设备