Skip to content

Discover

The discover package provides class libraries which enable developers to build discovery orientated features for categories and brands. The following discover features are available.

  • Get Categories - Provides access to category hierarchy.
  • Discover Category - Discover which POI categories exist around a provided location.
  • Discover Brand - Discover which POI brands exist around a provided location.
  • Discover Place - Discover places for the specified category.

Please see the API reference for the main classes related to Discover.

Get Categories

The get categories feature provides the developer access to the full category hierarchy. Use this method to retrieve available categories including their ids and level in hierarchy. This feature can be used to build a hierarchical interface for the application or just as a tool to acquire the full Telenav hierarchy. Since this method does not have any spatial context the developer does not need to set a location nor provide other input parameters. Developers will call the getCategoriesRequest method and process the EntityGetCategoriesResponse.

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
entityClient.getCategoriesRequest()
    .asyncCall(new Callback<EntityGetCategoriesResponse>() {

        @Override
        public void onSuccess(EntityGetCategoriesResponse response) {
            // log response in JSON format
            LOG.info(EntityJsonConverter.toPrettyJson(response));

            List<Category> categories = response.getResults();
            for(Category category : categories) {
                // iterate through categories and its child categories.
            }
        }

        @Override
        public void onFailure(Throwable t) {
            LOG.error("Get unsuccessful response or throwable happened when executing the request.", t);
        }
    });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
entityClient.getCategoriesRequest()
    .asyncCall(object : Callback<EntityGetCategoriesResponse> {

        override fun onSuccess(response: EntityGetCategoriesResponse) {
            // log response in JSON format
            Log.i("sdk", EntityJsonConverter.toPrettyJson(response))

            val categories = response.results
            for (category in categories) {
                // iterate through categories and its child categories.
            }
        }

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

Discover Category

Note

This is a beta version of the API.

The discover category feature enables discovery of categories around a specific location. Developers can build powerful discovery experiences which enable the end user to explore and determine if desired POI categories such as coffee shops, restaurants, shopping, etc. are around a provided location. Use the optional setCategory method with a parent category id to limit the discovery to child categories of that parent. For example; providing the parent id for ‘restaurants’ will enable discovery of all cuisine type categories.

Key methods

Method Details
setLocation(double latitude, double longitude) A geopoint value of the user’s location using geographic coordinates of latitude and longitude separated by comma). For example, location=37.1245,-122.45678.
setCategory(String categoryId) A string value of category id returned by Get Categories API, optional.

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
entityClient.discoverCategoryRequest()
        .setLocation(37.12419, -121.98828)
        .setLimit(5)
        .setCategory("2040")
        .asyncCall(new Callback<EntityDiscoverCategoryResponse>() {

            @Override
            public void onSuccess(EntityDiscoverCategoryResponse response) {

                // log response in JSON format
                LOG.info(EntityJsonConverter.toPrettyJson(response));

                List<Category> categories = response.getResults();
                for (Category category : categories) {
                    // iterate through categories
                }

            }

            @Override
            public void onFailure(Throwable t) {
                LOG.error("Get unsuccessful response or throwable happened when executing the request.", t);
            }
        });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
entityClient.discoverCategoryRequest()
        .setLocation(37.12419, -121.98828)
        .setLimit(5)
        .setCategory("2040")
        .asyncCall(object : Callback<EntityDiscoverCategoryResponse> {
            override fun onSuccess(response: EntityDiscoverCategoryResponse) {

                // log response in JSON format
                Log.i("sdk", EntityJsonConverter.toPrettyJson(response))
                val categories = response.results
                for (category in categories) {
                    // iterate through categories
                }
            }

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

__

Discover Brand

Note

This is a beta version of the API.

The discover brand feature enables discovery of brands around a specific location. Powerful discovery experiences can be built enabling the end user to discover popular brands around a provided location. Use optional setCategory with an applicable category id to limit the brands returned to brands belonging to the specific category. For example, if the use case is for restaurant brands then set the category to restaurants.

Key methods

Method Details
setLocation(double latitude, double longitude) A geopoint value of the user’s location using geographic coordinates of latitude and longitude separated by comma). For example, location=37.1245,-122.45678.
setCategory(String categoryId) A string value of category id returned by Get Categories API, optional.

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
entityClient.discoverBrandRequest()
        .setLocation(37.12419, -121.98828)
        .setLimit(5)
        .setCategory("241")
        .asyncCall(new Callback<EntityDiscoverBrandResponse>() {

            @Override
            public void onSuccess(EntityDiscoverBrandResponse response) {

                // log response in JSON format
                LOG.info(EntityJsonConverter.toPrettyJson(response));

                List<Brand> brands = response.getResults();
                for (Brand brand : brands) {
                    // iterate through brands

                }
            }

            @Override
            public void onFailure(Throwable t) {
                LOG.error("Get unsuccessful response or throwable happened when executing the request.", t);
            }
        });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
entityClient.discoverBrandRequest()
        .setLocation(37.12419, -121.98828)
        .setLimit(5)
        .setCategory("241")
        .asyncCall(object : Callback<EntityDiscoverBrandResponse> {
            override fun onSuccess(response: EntityDiscoverBrandResponse) {

                // log response in JSON format
                Log.i("sdk", EntityJsonConverter.toPrettyJson(response))
                val brands = response.results
                for (brand in brands) {
                    // iterate through brands
                }
            }

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

Discover Place

Discover places for the specified category. Following are the Discover Place features.

  • Lite Result - When set to true, only basic POI attributes are returned with support for returning up to 1000 results.
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    - entity id
    - entity type
    - place
        - name
        - categories[]
        - address[]
            - geo_coordinates
    - facets
        - ev_connectors  // only ev_connector facet will be returned in response with limited EV attributes
            - total_connector
            - connector_counts
            - connectors[]
                - connector_type
                - power_feed_level
                - charger_brand
                - connector_number
                - available
                - max_power
                - is_free
    
  • Polygon filter - Constrains the discover results to any polygon shape.
  • Bounding box filter - Constrains the discover results to a rectangular bounding box.
  • Radius filter - Constrains the discover results to a circle of a specified radius.
  • Electric vehicle charge station search - Specialized search service for electric vehicle charge stations.

Key methods

Method Details
setLocation(double latitude, double longitude) A geopoint value of the user’s location using geographic coordinates of latitude and longitude separated by comma. For example, location=37.1245,-122.45678.
setCategories(List categories) Set discover category IDs
setDiscoverOptions(DiscoverPlaceOptions discoverOptions) Set discover options to customize discover behavior
setLiteResult(Boolean liteResult) When set to true only basic poi attributes will be returned with support for returning up to 1000 results. The default value is True

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
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) {

        }
    });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
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

Key methods

Method Details
setGeoFilter(PolygonGeoFilter geoFilter) The polygon geofilter created above

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
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) {

        }
    });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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

Key methods

Method Details
setGeoFilter(BBoxGeoFilter geoFilter) The bbox geofilter created above

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
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) {

        }
    });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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

Key methods

Method Details
setGeoFilter(RadiusGeoFilter geoFilter) The radius geofilter created above

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
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) {

        }
    });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
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

Similar to the EvFilter in the Search API, refer Search Doc

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
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) {

        }
    });
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
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) {}
    })