发现

discover 包提供了一组类库，帮助开发者构建面向"类目（category）"和"品牌（brand）"的发现类能力。下面是当前可用的发现功能：

• Get Categories — 获取完整的类目层级。
• Discover Category — 探索指定位置周围存在哪些 POI 类目。
• Discover Brand — 探索指定位置周围存在哪些 POI 品牌。
• Discover Place — 按指定类目发现地点。

主要的 Discover 相关类请参见 API reference。

Get Categories

Get Categories 能力用于获取完整的类目层级。通过该方法可以拿到所有可用的类目，包括其 id 和在层级中的层级位置。该能力可以用来构建层级化的应用界面，也可以单纯作为工具拉取 Telenav 完整类目树。由于该方法不涉及任何位置上下文，调用时不需要设置位置或其他输入参数。开发者只需调用 getCategoriesRequest 方法，并处理返回的 EntityGetCategoriesResponse 即可。

关键方法

方法	说明
setLocale(Locale locale)	响应内容的语言偏好，例如 Locale.US。选填

示例代码

Java

entityClient.getCategoriesRequest()
    .asyncCall(new Callback<EntityGetCategoriesResponse>() {

        @Override
        public void onSuccess(EntityGetCategoriesResponse response) {
            // 以 JSON 格式打印响应
            LOG.info(EntityJsonConverter.toPrettyJson(response));

            List<Category> categories = response.getResults();
            for(Category category : categories) {
                // 遍历类目及其子类目
            }
        }

        @Override
        public void onFailure(Throwable t) {
            LOG.error("Get unsuccessful response or throwable happened when executing the request.", t);
        }
    });

Kotlin

entityClient.getCategoriesRequest()
    .asyncCall(object : Callback<EntityGetCategoriesResponse> {

        override fun onSuccess(response: EntityGetCategoriesResponse) {
            // 以 JSON 格式打印响应
            Log.i("sdk", EntityJsonConverter.toPrettyJson(response))

            val categories = response.results
            for (category in categories) {
                // 遍历类目及其子类目
            }
        }

        override fun onFailure(t: Throwable) {
            Log.e("sdk", "Get unsuccessful response or throwable happened when executing the request.", t)
        }
    })

Discover Category

说明

本 API 当前为 beta 版本。

Discover Category 能力用于探索指定位置周围指定Category下存在哪些子类目。例如，传入"restaurants"对应的父类目 id，即可发现该位置周围所有菜 系子类目。

关键方法

方法	说明
setLocation(double latitude, double longitude)	用户当前位置坐标。必填
setCategory(String categoryId)	父类目 id，用于将发现范围限定为该父类目下的子类目。由 Get Categories API 返回。必填
setLimit(Integer limit)	返回结果数量，默认值 10。选填
setLocale(Locale locale)	响应内容的语言偏好。选填
setFilters(DiscoverFilters filters)	地理过滤器，当前仅支持半径（radius）过滤。DiscoverFilters.builder().setRadiusGeoFilter(Integer radiusInMeter) 单位米，例如 2000选填

示例代码

Java

entityClient.discoverCategoryRequest()
        .setLocation(37.12419, -121.98828)
        .setLimit(5)
        .setCategory("2040")
        .asyncCall(new Callback<EntityDiscoverCategoryResponse>() {

            @Override
            public void onSuccess(EntityDiscoverCategoryResponse response) {

                // 以 JSON 格式打印响应
                LOG.info(EntityJsonConverter.toPrettyJson(response));

                List<Category> categories = response.getResults();
                for (Category category : categories) {
                    // 遍历类目
                }

            }

            @Override
            public void onFailure(Throwable t) {
                LOG.error("Get unsuccessful response or throwable happened when executing the request.", t);
            }
        });

Kotlin

entityClient.discoverCategoryRequest()
        .setLocation(37.12419, -121.98828)
        .setLimit(5)
        .setCategory("2040")
        .asyncCall(object : Callback<EntityDiscoverCategoryResponse> {
            override fun onSuccess(response: EntityDiscoverCategoryResponse) {

                // 以 JSON 格式打印响应
                Log.i("sdk", EntityJsonConverter.toPrettyJson(response))
                val categories = response.results
                for (category in categories) {
                    // 遍历类目
                }
            }

            override fun onFailure(t: Throwable) {
                Log.e("sdk", "Get unsuccessful response or throwable happened when executing the request.", t)
            }
        })

__

Discover Brand

说明

本 API 当前为 beta 版本。

Discover Brand 能力用于探索指定位置周围存在哪些品牌。基于此可以构建强大的发现体验，帮助最终用户发现某个位置周围流行的品牌。可选的 setCategory 方法允许传入一个类目 id，将返回的品牌限定为属于该类目的品牌。例如，如果业务场景是探索餐厅品牌，则将类目设为 restaurants。

关键方法

方法	说明
setLocation(double latitude, double longitude)	用户当前位置坐标。必填
setCategory(String categoryId)	类目 id，用于将返回的品牌限定为属于该类目的品牌。由 Get Categories API 返回。选填
setLimit(Integer limit)	返回结果数量，默认值 10。选填
setLocale(Locale locale)	响应内容的语言偏好。选填
setFilters(DiscoverFilters filters)	地理过滤器，当前仅支持半径（radius）过滤。DiscoverFilters.builder().setRadiusGeoFilter(Integer radiusInMeter) 单位米，例如 2000选填

示例代码

Java

entityClient.discoverBrandRequest()
        .setLocation(37.12419, -121.98828)
        .setLimit(5)
        .setCategory("241")
        .asyncCall(new Callback<EntityDiscoverBrandResponse>() {

            @Override
            public void onSuccess(EntityDiscoverBrandResponse response) {

                // 以 JSON 格式打印响应
                LOG.info(EntityJsonConverter.toPrettyJson(response));

                List<Brand> brands = response.getResults();
                for (Brand brand : brands) {
                    // 遍历品牌

                }
            }

            @Override
            public void onFailure(Throwable t) {
                LOG.error("Get unsuccessful response or throwable happened when executing the request.", t);
            }
        });

Kotlin

entityClient.discoverBrandRequest()
        .setLocation(37.12419, -121.98828)
        .setLimit(5)
        .setCategory("241")
        .asyncCall(object : Callback<EntityDiscoverBrandResponse> {
            override fun onSuccess(response: EntityDiscoverBrandResponse) {

                // 以 JSON 格式打印响应
                Log.i("sdk", EntityJsonConverter.toPrettyJson(response))
                val brands = response.results
                for (brand in brands) {
                    // 遍历品牌
                }
            }

            override fun onFailure(t: Throwable) {
                Log.e("sdk", "Get unsuccessful response or throwable happened when executing the request.", t)
            }
        })

---

Discover Place

按指定类目发现地点。Discover Place 提供如下能力：

• Lite Result — 设为 true 时仅返回基础 POI 属性，最多支持返回 1000 条结果。

  - entity id
  - entity type
  - place
      - name
      - categories[]
      - address[]
          - geo_coordinates
  - facets
      - ev_connectors  // 响应中只会返回 ev_connector facet，且仅包含有限的 EV 属性
          - total_connector
          - connector_counts
          - connectors[]
              - connector_type
              - power_feed_level
              - charger_brand
              - connector_number
              - available
              - max_power
              - is_free
  

• Polygon filter — 将发现结果限定在任意多边形区域内。
• Bounding box filter — 将发现结果限定在一个矩形包围盒内。
• Radius filter — 将发现结果限定在一个指定半径的圆形区域内。
• Electric vehicle charge station search — 面向电动车充电站的专用搜索能力。

关键方法

方法	说明
setLocation(double latitude, double longitude)	用户当前位置坐标。必填
setCategories(List categories) / addCategory(String category)	要发现的类目 ID 列表，至少一个。必填
setLimit(Integer limit)	返回结果数量，默认值 10。选填
setLocale(Locale locale)	响应内容的语言偏好。选填
setDiscoverOptions(DiscoverPlaceOptions discoverOptions)	发现选项，用于自定义发现行为。选填
setFilters(DiscoverPlaceFilters filters)	地理过滤器或 EV 过滤器。选填

DiscoverPlaceOptions

通过 DiscoverPlaceOptions.builder() 构建后，经 setDiscoverOptions() 传入：

方法	说明
setLiteResult(Boolean liteResult)	设为 true 时仅返回基础 POI 属性，最多支持返回 1000 条结果
setSortType(SortType sortType)	结果排序方式。BEST_MATCH（默认，最佳匹配）或 DISTANCE（按距离排序）

示例代码

Java

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setDiscoverOptions(DiscoverPlaceOptions.builder()
            .setLiteResult(true)
            .build())
    .setLimit(10)
    .asyncCall(new Callback<EntityDiscoverPlaceResponse>() {

        @Override
        public void onSuccess(EntityDiscoverPlaceResponse response) {
            for (Entity entity : response.getResults()) {
                LOG.info("Found Place: " + entity.getPlace().getName());
            }
        }

        @Override
        public void onFailure(Throwable t) {

        }
    });

Kotlin

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setDiscoverOptions(
        DiscoverPlaceOptions.builder()
            .setLiteResult(true)
            .build())
    .setLimit(10)
    .asyncCall(object : Callback<EntityDiscoverPlaceResponse> {

        override fun onSuccess(response: EntityDiscoverPlaceResponse) {
            for (entity in response.results) {
               Log.i("sdk", "Found Place: " + entity.place.name)
            }
        }

        override fun onFailure(t: Throwable) {}
    })

Polygon Filter

将发现结果限定在指定多边形区域内。多边形最少需要 3 个顶点，会自动连接首尾两点闭合。

关键方法

方法	说明
setFilters(DiscoverPlaceFilters filters)	包含 polygon geo filter 的过滤器对象
Polygon.builder().addPoint(double latitude, double longitude)	添加多边形顶点，至少 3 个点
PolygonGeoFilter.builder(Polygon polygon)	基于 Polygon 构建 polygon geo filter

示例代码

Java

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setFilters(DiscoverPlaceFilters.builder()
            .setGeoFilter(PolygonGeoFilter.builder(Polygon.builder()
                    .addPoint(37.90533, -122.31612)
                    .addPoint(37.91061, -122.29604)
                    .addPoint(37.92862, -122.29775)
                    .addPoint(37.93133, -122.32144)
                    .addPoint(37.91616, -122.32882)
                    .build())
                    .build())
            .build())
    .setLimit(10)
    .asyncCall(new Callback<EntityDiscoverPlaceResponse>() {

        @Override
        public void onSuccess(EntityDiscoverPlaceResponse response) {
            for (Entity entity : response.getResults()) {
                LOG.info("Found Place: " + entity.getPlace().getName());
            }
        }

        @Override
        public void onFailure(Throwable t) {

        }
    });

Kotlin

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setFilters(
        DiscoverPlaceFilters.builder()
            .setGeoFilter(
                PolygonGeoFilter.builder(
                    Polygon.builder()
                        .addPoint(37.90533, -122.31612)
                        .addPoint(37.91061, -122.29604)
                        .addPoint(37.92862, -122.29775)
                        .addPoint(37.93133, -122.32144)
                        .addPoint(37.91616, -122.32882)
                        .build())
                    .build())
            .build())
    .setLimit(10)
    .asyncCall(object : Callback<EntityDiscoverPlaceResponse> {

        override fun onSuccess(response: EntityDiscoverPlaceResponse) {
            for (entity in response.results) {
                Log.i("sdk", "Found Place: " + entity.place.name)
            }
        }

        override fun onFailure(t: Throwable) {}
    })

Bounding Box Filter

将发现结果限定在指定矩形包围盒内。

关键方法

方法	说明
setFilters(DiscoverPlaceFilters filters)	包含 bounding box geo filter 的过滤器对象
BBox.builder().setBottomLeft(double latitude, double longitude)	矩形左下角坐标
BBox.builder().setTopRight(double latitude, double longitude)	矩形右上角坐标
BBoxGeoFilter.builder(BBox bbox)	基于 BBox 构建 bounding box geo filter

示例代码

Java

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setFilters(DiscoverPlaceFilters.builder()
            .setGeoFilter(BBoxGeoFilter.builder(BBox.builder()
                    .setBottomLeft(37.70908, -122.50249)
                    .setTopRight(37.7897, -122.39108)
                    .build())
                    .build())
            .build())
    .setLimit(10)
    .asyncCall(new Callback<EntityDiscoverPlaceResponse>() {

        @Override
        public void onSuccess(EntityDiscoverPlaceResponse response) {
            for (Entity entity : response.getResults()) {
                LOG.info("Found Place: " + entity.getPlace().getName());
            }
        }

        @Override
        public void onFailure(Throwable t) {

        }
    });

Kotlin

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setFilters(
        DiscoverPlaceFilters.builder()
            .setGeoFilter(
                BBoxGeoFilter.builder(
                    BBox.builder()
                        .setBottomLeft(37.70908, -122.50249)
                        .setTopRight(37.7897, -122.39108)
                        .build())
                    .build())
            .build())
    .setLimit(10)
    .asyncCall(object : Callback<EntityDiscoverPlaceResponse> {
        override fun onSuccess(response: EntityDiscoverPlaceResponse) {

            for (entity in response.results) {
                Log.i("sdk", "Found Place: " + entity.place.name)
            }
        }

        override fun onFailure(t: Throwable) {}
    })

Radius Filter

将发现结果限定在指定半径的圆形区域内。

关键方法

方法	说明
setFilters(DiscoverPlaceFilters filters)	包含 radius geo filter 的过滤器对象
RadiusGeoFilter.builder(Integer radiusInMeter)	设置搜索半径（米），例如 RadiusGeoFilter.builder(20000).build()

示例代码

Java

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setFilters(DiscoverPlaceFilters.builder()
            .setGeoFilter(RadiusGeoFilter.builder(20000)
                    .build())
            .build())
    .setLimit(10)
    .asyncCall(new Callback<EntityDiscoverPlaceResponse>() {

        @Override
        public void onSuccess(EntityDiscoverPlaceResponse response) {
            for (Entity entity : response.getResults()) {
                LOG.info("Found Place: " + entity.getPlace().getName());
            }
        }

        @Override
        public void onFailure(Throwable t) {

        }
    });

Kotlin

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setFilters(DiscoverPlaceFilters.builder()
            .setGeoFilter(RadiusGeoFilter.builder(20000)
                    .build())
            .build())
    .setLimit(10)
    .asyncCall(object : Callback<EntityDiscoverPlaceResponse> {

        override fun onSuccess(response: EntityDiscoverPlaceResponse) {
            for (entity in response.results) {
                Log.i("sdk", "Found Place: " + entity.place.name)
            }
        }

        override fun onFailure(t: Throwable) {}
    })

EV Filter

面向电动车充电站的专用过滤能力，类似于 Search API 中的 EvFilter，详见 Search 文档。

关键方法

方法	说明
setFilters(DiscoverPlaceFilters filters)	包含 EV filter 的过滤器对象
EvFilter.builder().setChargerBrands(List brands)	按充电网络（品牌）过滤
EvFilter.builder().setConnectorTypes(List types)	按接口类型过滤
EvFilter.builder().setPowerFeedLevels(List levels)	按功率等级过滤
EvFilter.builder().setFreeCharge(Boolean freeCharge)	true 仅返回免费接口，false 仅返回付费接口

示例代码

Java

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setLimit(10)
    .setFilters(DiscoverPlaceFilters.builder()
            .setEvFilter(EvFilter.builder()
                    .setConnectorTypes(Arrays.asList("30001", "30002"))
                    .setPowerFeedLevels(Arrays.asList(1, 2))
                    .setChargerBrands(Arrays.asList("99100001"))
                    .setFreeCharge(true)
                    .build())
            .build())
    .asyncCall(new Callback<EntityDiscoverPlaceResponse>() {

        @Override
        public void onSuccess(EntityDiscoverPlaceResponse response) {
            for (Entity entity : response.getResults()) {
                LOG.info("Found Place: " + entity.getPlace().getName());
            }
        }

        @Override
        public void onFailure(Throwable t) {

        }
    });

Kotlin

entityClient.discoverPlaceRequest()
    .setLocation(37.92021, -122.31476)
    .addCategory("771")
    .setLimit(10)
    .setFilters(DiscoverPlaceFilters.builder()
            .setEvFilter(EvFilter.builder()
                    .setConnectorTypes(Arrays.asList("30001", "30002"))
                    .setPowerFeedLevels(Arrays.asList(1, 2))
                    .setChargerBrands(Arrays.asList("99100001"))
                    .setFreeCharge(true)
                    .build())
            .build())
    .asyncCall(object : Callback<EntityDiscoverPlaceResponse> {

        override fun onSuccess(response: EntityDiscoverPlaceResponse) {
            for (entity in response.results) {
                Log.i("sdk", "Found Place: " + entity.place.name)
            }
        }

        override fun onFailure(t: Throwable) {}
    })

响应参数

各 Discover API 的响应对象均包含以下通用字段：

方法 / 字段	说明
getStatus() / getCode()	请求状态
getResponseTime()	响应时间（毫秒）
getReferenceId()	响应关联的 reference id
getResults()	匹配查询条件的结果列表

各 API 的 getResults() 返回类型如下：

API	响应类型	结果类型
Get Categories	EntityGetCategoriesResponse	List<Category>，包含类目 id、名称及子节点层级
Discover Category	EntityDiscoverCategoryResponse	List<Category>，包含类目 id 和名称
Discover Brand	EntityDiscoverBrandResponse	List<Brand>，包含 brand_id 和 brand_name
Discover Place	EntityDiscoverPlaceResponse	List<Entity>，包含 POI 详情

状态码

状态码	消息	说明
12200	SUCCESS	请求成功，未发生错误
12400	INVALID_REQUEST	缺少必填参数，或参数值无法解析
12500	INTERNAL_SERVER_ERROR	API 服务端内部错误