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.

Key methods

Method Details
getCategories() Returns categories.

Sample code

1
2
3
4
5
6
TNEntityClient.getCategories { (categories, err) in
    guard let categories = categories else {
        return
    }
    print(categories.results)
}

1
2
3
[TNEntityClient getCategoriesWithCompletion:^(TNEntityCategoryResult * _Nullable response, NSError * _Nullable err) {
    NSLog(@"%@", response.results);
}];

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
categoryId(categoryId: String) A string value of category id returned by Get Categories API, optional.
location(location: TNEntityGeoPoint) A geopoint value of the user’s location using geographic coordinates of latitude and longitude.

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
let discoverCategoryParams = TNEntityDiscoverCategoryParamsBuilder()
    .categoryId("2040")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .limit(5)
    .build()

TNEntityClient.getDiscoverCategories(params: discoverCategoryParams) { (response, err) in
    if let category = response?.results?.first {
        print(category.id)
        print(category.name)
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
TNEntityDiscoverCategoryParams *params = [[[[[TNEntityDiscoverCategoryParamsBuilder new]
                                             categoryId:@"2040"]
                                            location:[TNEntityGeoPoint pointWithLat:37.12419 lon:-121.98828]]
                                           limit:5] build];

[TNEntityClient getDiscoverCategoriesWithParams:params completion:^(TNEntityCategoryResult * _Nullable response, NSError * _Nullable err) {
    for (TNEntityCategory *cat in response.results) {
        NSLog(@"%@", cat.name);
    }
}];

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 categoryId 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
categoryId(categoryId: String) A string value of category id returned by Get Categories API, optional.
location(location: TNEntityGeoPoint) A geopoint value of the user’s location using geographic coordinates of latitude and longitude.

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
let discoverBrandParams = TNEntityDiscoverBrandParamsBuilder()
    .categoryId("241")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .limit(5)
    .build()

TNEntityClient.getDiscoverBrands(params: discoverBrandParams) { (response, err) in
    if let brand = response?.results?.first {
        print(brand.brandId)
        print(brand.brandName)
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
TNEntityDiscoverBrandParams *params = [[[[[TNEntityDiscoverBrandParamsBuilder new]
                                             categoryId:@"241"]
                                            location:[TNEntityGeoPoint pointWithLat:37.12419 lon:-121.98828]]
                                           limit:5] build];

[TNEntityClient getDiscoverBrandsWithParams:params completion:^(TNEntityBrandResult * _Nullable response, NSError * _Nullable err) {
    for (TNEntityBrand *brand in response.results) {
        NSLog(@"%@", brand.brandName);
    }
}];

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
location(_ lat: Double, _ lon: Double) 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.
categories(_ categoryes: [String]) Set discover category IDs
liteResult(_ liteResult: Bool) 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
let params = TNEntityDiscoverPlaceParamsBuilder()
    .addCategory("771")
    .location(37.92021, -122.31476)
    .liteResult(true)
    .build()

TNEntityClient.discoverPlace(params: params) { (result, error) in
    if let entities = result?.results {
       for entity in entities {

       }
    }
}

Polygon Filter

Key methods

Method Details
polygonGeoFilter(_ polygonPoints: [TNEntityGeoPoint]) 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
let params = TNEntityDiscoverPlaceParamsBuilder()
.addCategory("771")
.location(37.92021, -122.31476)
.polygonGeoFilter([
        TNEntityGeoPoint(lat: 37.90533, lon: -122.31612),
        TNEntityGeoPoint(lat: 37.91061, lon: -122.29604),
        TNEntityGeoPoint(lat: 37.92862, lon: -122.29775),
        TNEntityGeoPoint(lat: 37.93133, lon: -122.32144),
        TNEntityGeoPoint(lat: 37.91616, lon: -122.32882)
    ])
.build()

TNEntityClient.discoverPlace(params: params) { (result, error) in
    if let entities = result?.results {
       for entity in entities {

       }
    }
}

Bounding Box Filter

Key methods

Method Details
bboxGeoFilter(bottomLeft: TNEntityGeoPoint, topRight: TNEntityGeoPoint) The bbox geofilter created above

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
let params = TNEntityDiscoverPlaceParamsBuilder()
    .addCategory("771")
    .location(37.92021, -122.31476)
    .bboxGeoFilter(bottomLeft: TNEntityGeoPoint(lat: 37.70908, lon: -122.50249), topRight: TNEntityGeoPoint(lat: 37.7897, lon: -122.39108))
    .build()

TNEntityClient.discoverPlace(params: params) { (result, error) in
    if let entities = result?.results {
       for entity in entities {

       }
    }
}

Radius Filter

Key methods

Method Details
radiusGeoFilter(_ radiusInMeter: Double) The radius geofilter created above

Sample Code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
let params = TNEntityDiscoverPlaceParamsBuilder()
    .addCategory("771")
    .location(37.92021, -122.31476)
    .radiusGeoFilter(20000)
    .build()

TNEntityClient.discoverPlace(params: params) { (result, error) in
    if let entities = result?.results {
       for entity in entities {

       }
    }
}

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
let params = TNEntityDiscoverPlaceParamsBuilder()
    .addCategory("771")
    .location(37.92021, -122.31476)
    .evFilterConnectorTypes(["30001", "30002"])
    .evFilterPowerFeedLevels([1, 2])
    .evFilterChargerBrands(["99100001"])
    .build()

TNEntityClient.discoverPlace(params: params) { (result, error) in
    if let entities = result?.results {
       for entity in entities {

       }
    }
}