Skip to content

Search

The search package provides all of the classes for search. Search is the most powerful set of classes and provides much flexibility for the developer. Following are some of the search features provided by the classes.

  • Onebox search - Location based semantic search finds POIs (points of interest) and addresses using free text or tagged query syntax. Advanced semantic knowledge and underlying search technology provide highly relevant search results by simply entering a free text query in a single text field (one-box). This is the foundation of Telenav search and great search flexibility.
  • Category filter search - Enables POI search by specific category. Telenav supports over 100 POI categories.
  • Brand filter search - Enables POI search by specific business brand name or chain name.
  • Corridor search - Enables POIs to be found within a specific corridor; also called "Search Along Route" to constrain search results to places near driver's route.
  • Polygon search - Constrains search results to any polygon shape.
  • Bounding box search - Constrains search results to a rectangular bounding box.
  • Reverse geocoding (RGC) - RGC service returns an address based on a coordinate (latitude/longitude) value.
  • Voice Search - Enables support for free text and structured text queries for voice search use cases.
  • Electric vehicle charge station search - Specialized search services for electric charge stations.
  • Anchor search - To specify search location if the search location is different from the current vehicle position.

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

Use the one box search method when search input is provided in the form of free search text and location is around a single point. At a minimum developer needs to provide query and point. Telenav one box search is semantic based free text query search. Many different entity types can be searched by providing a text query in the .setquery method. Search supports fuzzy matching capabilities such that the query does not need to exactly match desired search entity. The onebox text parser can identify the following entity types from the free form query text:

  • Address (full or partial)
  • Point of interest (exact or inexact match)
  • Category name (including synonyms)
  • Street (with or without street type)
  • City In addition to these entity types, additional query patterns can be supported such as querying street intersection, POI name in city, etc.

Fuzzy one box: Note that query does not need to be exact as semantic search will consider approximate names and ‘fuzzy match’ entities which are similarly named.

Key methods

Method Details
location(location: TNEntityGeoPoint) A geopoint value of the user’s location using geographic coordinates of latitude and longitude. For example, TNEntityGeoPoint(lat: 0, lon: 0)
query(query: String) For one box search this value is free-text query. Query can support search for an address, point of interest (POI), street, or city. In addition, there are additional more complex search patterns which are supported. Query search patterns are localized so expected search patterns for supported locale are accepted.


Search API sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
let params = TNEntitySearchParamsBuilder()
    .query("Pierce Rd")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {
            if entity.type == .place {
                print(entity.place?.name)
            } else {
                print(entity.address?.formattedAddress)
            }
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
TNEntitySearchParams *params = [[[[TNEntitySearchParamsBuilder new]
                                  query:@"Pierce Rd"]
                                 location:[TNEntityGeoPoint pointWithLat:-37.12419 lon:-121.98828]] build];

[TNEntityClient searchWithSearchParams:params completion:^(TNEntitySearchResult * _Nullable res, NSError * _Nullable err) {
    for (TNEntity *entity in res.results) {
        if (entity.type == TNEntityTypePlace) {
            NSLog(@"%@", entity.place.name);
        } else {
            NSLog(@"%@", entity.address.formattedAddress);
        }
    }
}];

Response example

 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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
{
  "status": {
    "status": 12200,
    "message": "Success"
  },
  "reference_id": "2e3f55e3-df3e-44d4-8b88-b120630274b9",
  "search_metadata": {
    "counts": [
      {
        "type": "ADDRESS",
        "count": 3
      }
    ],
    "query_resolution": {
      "query_tags": [
        {
          "where": "Street=Pierce Rd"
        }
      ],
      "search_location": {
        "latitude": 37.12419,
        "longitude": -121.98828
      }
    }
  },
  "has_more": false,
  "results": [
    {
      "id": "Yz1Mb3MgR2F0b3M7Y3k9U2FudGEgQ3J1ejtjbz1VUztzZm49UGllcmNlIFJkO3o9OTUwMzM7cz1DQTt0PVNUUkVFVDtpZD1IM19OVF9iQ2RoUnBxUEF1UmhVMGxySGJrMDRBO2x0PTM3LjEyNjAyO2xuPS0xMjEuOTkwMzY7cmdjPWZhbHNlO3R0PVNUUkVFVDtpX2NvPVVTO2lfc2ZuPVBpZXJjZSBSZDsV6",
      "type": "ADDRESS",
      "address": {
        "address_type": "STREET",
        "formatted_address": "Pierce Rd, Los Gatos CA 95033, USA",
        "street": {
          "body": "pierce",
          "type": "road",
          "formatted_name": "Pierce Rd"
        },
        "city": "Los Gatos",
        "county": "Santa Cruz",
        "state": "CA",
        "country": "USA",
        "postal_code": "95033",
        "geo_coordinates": {
          "latitude": 37.12602,
          "longitude": -121.99036
        },
        "nav_coordinates": {
          "latitude": 37.12602,
          "longitude": -121.99036
        }
      },
      "distance": 274.0
    },
    ...
  ],
  "response_time": 58
}

The category filter search enables search by specific category around a specific location. To use category search the developer needs to provide a list of category ids and a geopoint for location.

Category filter search is often used when HMI interface includes buttons or category hierarchical interface allowing user to select desired POI category such as restaurant, fuel, or parking.

Telenav POI categories support a hierarchical model with parents and child nodes. A child node will only return POIs which belong to the category of that node. If a parent category calls in the service then all children within that parent will be returned in the service. Consider below example: Parent (2041) Restaurant (226) Steakhouse (267) Pizza (263) Mexican (261) .... Coffee and Bakery (890) Bagels and Donuts (230) Bakeries (231) Coffee (241)

In above category example, add category id 2041 to category filter will produce a results list including POIs with categories of all restaurants and coffee/bakery POIs. If category 226 added to category filter then result entities include POIs of categories restaurants of various styles and cuisine types. If category id 263 is added to category filter then only pizza POIs will be in the result entities list.

The list of supported categories and their ids can be retrieved using TNEntityClient.getCategories()

To use the category filter search, the developer must invoke the .categoryFilter(ids) method of TNEntitySearchQueryBuilder with ids: Array<String> containing 1 or more identifiers of category.

Key methods

Method Details
location(location: TNEntityGeoPoint) A geopoint value of the user’s location using geographic coordinates of latitude and longitude.
categoryFilter(categoryIDs: [String]) The category IDs array

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
let params = TNEntitySearchParamsBuilder()
    .categoryFilter(["241"])
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .build()


TNEntityClient.search(params: params) { (telenavSearch, err) in
    if let res = telenavSearch?.results {
        for entity in res {
            if entity.type == .place {
                print(entity.place?.name)
            } else {
                print(entity.address?.formattedAddress)
            }
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
TNEntitySearchParams *params = [[[[TNEntitySearchParamsBuilder new]
                                  categoryFilter:@[@"241"]]
                                 location:[TNEntityGeoPoint pointWithLat:-37.12 lon:-121.98828]] build];

[TNEntityClient searchWithSearchParams:params completion:^(TNEntitySearchResult * _Nullable res, NSError * _Nullable err) {
    for (TNEntity *entity in res.results) {
        if (entity.type == TNEntityTypePlace) {
            NSLog(@"%@", entity.place.name);
        } else {
            NSLog(@"%@", entity.address.formattedAddress);
        }
    }
}];

Telenav brand filter search feature enables search for specific brands or chains. To use brand filter search the developer needs to build a list of brand ids and provide a geopoint for search anchor location. Using a brand search enables all POIs that belong to the brand to be part of entities results list even if the brand may have name variations. Telenav supports hundreds of popular consumer brands across categories such as food, coffee, hotels, restaurants, fuel, and other. Such brands include Starbucks, Chipotle, Subway, HIlton, Best Buy, Nordstrom, Chevron, and many others. Use brand search instead of onebox search when search intent is known to be for specific brand. As some brands have name variations using a brand filter search is recommended for this case.

To use the brand filter search the developer must invoke the .brandFilter(brandIDs) method of TNEntitySearchQueryBuilder with brandIDs: Array<String> containing 1 or more brand identifiers.

Key methods

Method Details
location(location: TNEntityGeoPoint) A geopoint value of the user’s location using geographic coordinates of latitude and longitude.
brandFilter(brandIDs: [String]) Array of brand ids

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
let params = TNEntitySearchParamsBuilder()
.brandFilter(["5e36d154adf911e299336e1e7d26b4cc"])
.location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
.build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

1
2
3
4
5
6
7
8
9
TNEntitySearchParams *params = [[[[TNEntitySearchParamsBuilder new]
                                  brandFilter:@[@"5e36d154adf911e299336e1e7d26b4cc"]]
                                 location:[TNEntityGeoPoint pointWithLat:-37.12 lon:-121.98828]] build];

[TNEntityClient searchWithSearchParams:params completion:^(TNEntitySearchResult * _Nullable res, NSError * _Nullable err) {
    for (TNEntity *entity in res.results) {

    }
}];

Response example

  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
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
{
  "status": {
      "status": 12200,
      "message": "Success"
  },
  "reference_id": "92c30a35-8096-435d-8de2-f0a1e5672d17",
  "search_metadata": {
    "counts": [
      {
        "type": "PLACE",
        "count": 10
      }
    ],
    "query_resolution": {
      "search_location": {
        "latitude": 37.12419,
        "longitude": -121.98828
      }
    }
  },
  "has_more": false,
  "results": [
    {
      "id": "P-YP-cfjuAoaXnJiqkqK5UmGCxw",
      "type": "PLACE",
      "place": {
        "name": "Starbucks",
        "phone_numbers": [
          "18314409801"
        ],
        "categories": [
          {
            "id": "241",
            "name": "Coffee Houses"
          }
        ],
        "address": {
          "formatted_address": "5600 Scotts Valley Dr, Scotts Valley CA 95066, USA",
          "house_number": "5600",
          "street": {
            "body": "Scotts Valley Dr",
            "formatted_name": "Scotts Valley Dr"
          },
          "city": "Scotts Valley",
          "state": "CA",
          "country": "USA",
          "postal_code": "95066",
          "geo_coordinates": {
            "latitude": 37.06147,
            "longitude": -122.00706
          },
          "nav_coordinates": {
            "latitude": 37.06147,
            "longitude": -122.00706
          },
          "address_lines": [
            "5600 Scotts Valley Dr, Scotts Valley CA 95066"
          ]
        },
        "websites": [
          "https://www.starbucks.com"
        ],
        "brands": [
          {
            "brand_id": "5e36d154adf911e299336e1e7d26b4cc"
          }
        ]
      },
      "distance": 7164.0,
      "facets": {
        "open_hours": {
          "regular_open_hours": [
            {
              "day": 7,
              "open_time": [
                {
                  "from": "06:00",
                  "to": "18:00"
                }
              ]
            },
            {
              "day": 1,
              "open_time": [
                {
                  "from": "05:00",
                  "to": "18:00"
                }
              ]
            },
            {
              "day": 2,
              "open_time": [
                {
                  "from": "05:00",
                  "to": "18:00"
                }
              ]
            },
            {
              "day": 3,
              "open_time": [
                {
                  "from": "05:00",
                  "to": "18:00"
                }
              ]
            },
            {
              "day": 4,
              "open_time": [
                {
                  "from": "05:00",
                  "to": "18:00"
                }
              ]
            },
            {
              "day": 5,
              "open_time": [
                {
                  "from": "05:00",
                  "to": "18:00"
                }
              ]
            },
            {
              "day": 6,
              "open_time": [
                {
                  "from": "06:00",
                  "to": "18:00"
                }
              ]
            }
          ]
        },
        "price_info": {
          "price_level": 1
        },
        "rating": [
          {
            "source": "YELP",
            "average_rating": 3.5,
            "total_count": 50,
            "rating_type": "star",
            "url": "https://www.yelp.com/biz/starbucks-scotts-valley-2"
          }
        ]
      }
    },
    ...
  ],
  "response_time": 102
}

The corridor search features enables developer to apply a search buffer which is limited to an area which is within a buffer range of driver’s current route. This feature is also referred to as "Search Along Route". Either a place keyword query, category filter, or brand filter must also be supplied to indicate the search intent within the corridor. A prerequisite of building this filter is acquiring a route. The route is acquired from a separate service from search and is typically represented in the form of a polyline (list of coordinates). The developer needs to apply a buffer width (in meters) to the route.

A corridor filter search is a form of a geo-filter. A geo-filter limits search to the bounds of the provided geometry. In the case of corridor search the constraining geometry is the route (represented as a coordinate list) with a buffer applied to each side of the route. To build a corridor filter, the developer uses the .corridorGeoFilter(_route, routeWidth) method of TNEntitySearchQueryBuilder. The parameters to be passed in are _route: Array<TNEntityGeoPoint> containing an array of geopoints representing the route and routeWidth: Double containing a double value representing the buffer width.

Key methods

Method Details
query(query: String) Free form search text indicating search intent
Note: category or brand filter can be used in place of query text
corridorGeoFilter(route: [TNEntityGeoPoint], routeWidth: Double) The corridor geofilter created above, and route width.

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
let params = TNEntitySearchParamsBuilder()
    .limit(10)
    .query("food")
    .location(TNEntityGeoPoint(lat: 37.763662, lon: -121.47700))
    .corridorGeoFilter(route: [
            TNEntityGeoPoint(lat: 37.763628, lon: -122.47707),
            TNEntityGeoPoint(lat: 37.761720, lon: -122.476960),
            TNEntityGeoPoint(lat: 37.761711, lon: -122.475670),
            TNEntityGeoPoint(lat: 37.761796, lon: -122.473792),
            TNEntityGeoPoint(lat: 37.761908, lon: -122.471555),
            TNEntityGeoPoint(lat: 37.762061, lon: -122.467285)],
           routeWidth: 5)
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
TNEntitySearchParams *params = [[[[[[TNEntitySearchParamsBuilder new]
                                    corridorGeoFilterWithRoute:@[
                                        [TNEntityGeoPoint pointWithLat:37.763628 lon:-122.47707],
                                        [TNEntityGeoPoint pointWithLat:37.761720 lon:-122.476960],
                                        [TNEntityGeoPoint pointWithLat:37.761711 lon:-122.475670],
                                        [TNEntityGeoPoint pointWithLat:37.761796 lon:-122.473792],
                                        [TNEntityGeoPoint pointWithLat:37.761908 lon:-122.471555],
                                        [TNEntityGeoPoint pointWithLat:37.762061 lon:-122.467285]
                                    ] routeWidth:5]
                                   limit:10]
                                  query:@"food"]
                                 location:[TNEntityGeoPoint pointWithLat:-37.12 lon:-121.98828]] build];

[TNEntityClient searchWithSearchParams:params completion:^(TNEntitySearchResult * _Nullable res, NSError * _Nullable err) {
    for (TNEntity *entity in res.results) {

    }
}];

The polygon search feature enables search results to be constrained to within the spatial boundaries of the respective polygon. Either a query, category filter, or brand filter must also be supplied to indicate the search intent within the polygon. The polygon can represent any area although it is recommended that the polygon size is kept to a plausible search extent to reasonable fill the polygon area with entity search results. Although the polygon can represent any geographic area, a common usage for polygon search is limited results to the boundaries of a city or other administrative area.

A polygon filter search is a form of a geo-filter. A geo-filter limits search to the bounds of the provided geometry. In the case of polygon search the constraining geometry is the polygon geometry. To build a polygon filter the developer uses TNEntitySearchQueryBuilder and passes array of TNEntityGeoPoint . A minimum of 3 points are required and the polygon object automatically closes itself by connecting the first and last point objects.

Key methods

Method Details
query(query: String) Free form search text indicating search intent
Note: category or brand filter can be used in place of query text
polygonGeoFilter(polygon: [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 = TNEntitySearchParamsBuilder()
    .limit(10)
    .query("food")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .polygonGeoFilter(polygon: [
            TNEntityGeoPoint(lat: 37.12419, lon: -121.98828),
            TNEntityGeoPoint(lat: 37.06723, lon: -122.11108),
            TNEntityGeoPoint(lat: 36.95373, lon: -122.07400),
            TNEntityGeoPoint(lat: 36.98445, lon: -121.82475),
            TNEntityGeoPoint(lat: 37.11050, lon: -121.85427)])
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
TNEntitySearchParams *params = [[[[[[TNEntitySearchParamsBuilder new]
                                    polygonGeoFilterWithPolygon:@[
                                        [TNEntityGeoPoint pointWithLat:37.12419 lon:-121.98828],
                                        [TNEntityGeoPoint pointWithLat:37.06723 lon:-122.11108],
                                        [TNEntityGeoPoint pointWithLat:36.95373 lon:-122.07400],
                                        [TNEntityGeoPoint pointWithLat:36.98445 lon:-121.82475],
                                        [TNEntityGeoPoint pointWithLat:37.11050 lon:-121.85427]
                                    ]]
                                   limit:10]
                                  query:@"food"]
                                 location:[TNEntityGeoPoint pointWithLat:-37.12419 lon:-121.98828]] build];

[TNEntityClient searchWithSearchParams:params completion:^(TNEntitySearchResult * _Nullable res, NSError * _Nullable err) {
    for (TNEntity *entity in res.results) {

    }
}];

The bounding box search feature enables search results to be constrained within the spatial boundaries of the respective rectangle. Either a query, category filter, or brand filter must also be supplied to indicate the search intent within the rectangle. The rectangle can represent any area although it is recommended that the rectange size is kept to a plausible search extent so the search results can reasonably fill the rectangle area with entity search results. Although the rectangle can represent any geographic area, a common usage for rectangle search may be a user drawn search area or limiting results to a given map zoom level or map extent.

A bounding box search is a form of a geo-filter. A geo-filter limits search to the bounds of the provided geometry. In the case of bounding box search the constraining geometry is the rectangle geometry. To build a bounding box filter the developer uses the bboxGeoFilter() method with two coordinates (bottomLeft, topRight).

Key methods

Method Details
query(query: String) Free form search text indicating search intent
Note: category or brand filter can be used in place of query text
bboxGeoFilter(bottomLeft: TNEntityGeoPoint, topRight: TNEntityGeoPoint) The rectangle geofilter created above

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
let params = TNEntitySearchParamsBuilder()
    .limit(10)
    .query("food")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .bboxGeoFilter(bottomLeft: TNEntityGeoPoint(lat: 37.373974, lon: -122.057767),
                   topRight: TNEntityGeoPoint(lat: 37.394161, lon: -122.026524))
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
TNEntitySearchParams *params = [[[[[[TNEntitySearchParamsBuilder new]
                                    bboxGeoFilterWithBottomLeft:[TNEntityGeoPoint pointWithLat:37.373974 lon:-122.057767]
                                    topRight:[TNEntityGeoPoint pointWithLat:37.394161 lon:-122.026524]]
                                   limit:10]
                                  query:@"food"]
                                 location:[TNEntityGeoPoint pointWithLat:-37.12419 lon:-121.98828]] build];

[TNEntityClient searchWithSearchParams:params completion:^(TNEntitySearchResult * _Nullable res, NSError * _Nullable err) {
    for (TNEntity *entity in res.results) {

    }
}];

The radius search constraints search to the radius around specified point.

Key methods

Method Details
query(query: String) Free form search text indicating search intent
Note: category or brand filter can be used in place of query text
location(location: TNEntityGeoPoint) A geopoint value of the user’s location using geographic coordinates of latitude and longitude. For example, TNEntityGeoPoint(lat: 0, lon: 0)
radiusGeoFilter(radiusInMeter: Double) Radius in meters around location

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
let params = TNEntitySearchQueryBuilder()
    .limit(10)
    .query("food")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .radiusGeoFilter(2000)
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
TNEntitySearchParams *params = [[[[[[TNEntitySearchParamsBuilder new]
                                    radiusGeoFilter:2000]
                                   limit:10]
                                  query:@"food"]
                                 location:[TNEntityGeoPoint pointWithLat:-37.12419 lon:-121.98828]] build];

[TNEntityClient searchWithSearchParams:params completion:^(TNEntitySearchResult * _Nullable res, NSError * _Nullable err) {
    for (TNEntity *entity in res.results) {

    }
}];

Reverse Geocoding

Reverse geocoding (rgc) provides methods to convert a geographic coordinate into a real world address. When using rgc the only entity type returned is an address. RGC is useful when application needs to display an address (or city) from a given location.

To instruct the search request to utilize reverse geocoding the search intent must be set for rgc and the location as a geopoint must be provided.

Key methods

Method Details
location(location: TNEntityGeoPoint) The coordinate used to RGC to equivalent address
searchOptions(searchOptions: TNEntitySearchOptions) The coordinate used to RGC to equivalent address

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
let params = TNEntitySearchParamsBuilder()
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .searchOptions(TNEntitySearchOptions(intent: TNEntitySearchOptionIntent.reverseGeocoding, showAddressLines: true))
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
TNEntitySearchParams *params = [[[[[[TNEntitySearchParamsBuilder new]
                                    searchOptions:[[TNEntitySearchOptions alloc]
                                                   initWithIntent:TNEntitySearchOptionIntentReverseGeocoding
                                                   showAddressLines:YES]]
                                   limit:10]
                                  query:@"food"]
                                 location:[TNEntityGeoPoint pointWithLat:-37.12419 lon:-121.98828]] build];

[TNEntityClient searchWithSearchParams:params completion:^(TNEntitySearchResult * _Nullable res, NSError * _Nullable err) {
    for (TNEntity *entity in res.results) {

    }
}];

RGC also support returning both Address and Place, it's triggered by setting latitude,longitude as query parameter.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
let params = TNEntitySearchParamsBuilder()
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .query("37.06147,-122.00706")
    .searchOptions(TNEntitySearchOptions(intent: TNEntitySearchOptionIntent.reverseGeocoding, showAddressLines: true))
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

Search supports both free text and structured text queries for voice search use cases. Typically, a speech to text engine will accept voice input and convert into text; the converted text can be ‘parsed’ with tags assigned and sent as a query to search as structured (tagged) text or ‘unparsed’ and sent as a free text query. The Search API supports such structured text with tags and a speech to text engine can use these tags to build a structured query.

Query Tags

Tag Description
WHAT Tag used for POI name, chain name or category label.
WHERE Tag that indicates a full address or partial address including street and/or city.
CATEGORYID Id of the identified category.
ALT_WHAT Alternate homophonic WHAT
ALT_WHERE Alternate homophonic WHERE
;(semi colon) Tag separator
|| (double pipe) Homophonic group separator

("Alternate homophonic" words are alternate words for the same sound)

Query Syntax

query=tag1=v1;tag2=v2||tag3=v3;tag4=v4;...

  • Query Example
Voice Input Search Query
Find McDonald's WHAT=McDonald's
Find Restaurant CATEGORYID=226
Find Great America Parkway WHERE=Great America Parkway
Find Restaurant near Great America Parkway CATEGORYID=226;WHERE=Great America Parkway
Find McDonald's near Great America Parkway WHAT=McDonald’s;WHERE=Great America Parkway
Find McDonald's restaurant near Great America Parkway CATEGORYID=226;WHAT=McDonald's;WHERE=Great America Parkway
  • Query Examples (with homophones)
Voice Input NLU Candidates Search Query
Find McDonald's POI: McDonald's | Mac Donalds | MacDonald's WHAT=McDonald's||ALT_WHAT=Mac Donalds||ALT_WHAT= MacDonald's
Find Fischer Street Street: Fisher Street | Fischer Street | Ficher Street WHERE=Fisher Street||ALT_WHERE=Fischer Street||ALT_WHERE=Ficher Street
Find McDonald's near Fischer Street POI: McDonald's | Mac Donalds | MacDonald's
Street: Fischer Street		 WHAT=McDonald's;WHERE=Fisher Street||ALT_WHAT=Mac Donalds;ALT_WHERE=Fisher Street||ALT_WHAT= MacDonald's;ALT_WHERE=Fisher Street
Find McDonalds near Fischer Street POI: McDonald's | Mac Donalds | MacDonald's
Street: Fisher Street | Fischer Street | Ficher Street

Note: if there are various combinations, preferably use only top 3 alternatives		 WHAT=McDonald’s;WHERE=Fisher Street||ALT_WHAT= McDonald’s;ALT_WHERE= Fischer Street||ALT_WHAT= MacDonald’s;ALT_WHERE=Fisher Street

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
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
let searchOptions = TNEntitySearchOptions()
searchOptions.trigger = TNEntitySearchOptionTrigger.voice

// Simple tag query
var params = TNEntitySearchParamsBuilder()
    .query("WHAT=McDonald's")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .searchOptions(searchOptions)
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

// Using TNEntityMultiboxQuery to build tag query
params = TNEntitySearchParamsBuilder()
    .query(TNEntityMultiboxQuery()
            .addTag(TNEntityTag.what, "McDonald's")
            .build()
    )
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .searchOptions(searchOptions)
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

// Using TNEntityMultiboxQuery to build homophonic group tag query
params = TNEntitySearchParamsBuilder()
    .query(TNEntityMultiboxQuery()
            .addTag(TNEntityTag.what, "McDonald's")
            .addTag(TNEntityTag.categoryId, "226")
            .newGroup()
            .addTag(TNEntityTag.what, "Mac Donalds")
            .newGroup()
            .addTag(TNEntityTag.what, "MacDonald's")
            .build()
    )
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .searchOptions(searchOptions)
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

There are specialized classes available specifically for electric charge station category. These classes enable filtering search by important characteristics for the electric vehicle driver. In addition there are classes which are associated with entity details of a charge station such as connector types, connector counts, power feed type, and charge network (brand).

To build these features the developer will use the EVFilter class.

Filter by Charge Network

This feature enables a driver to find EV charge stations for a specific charging network such as Chargepoint or EVgo. To filter charge station search by network use the .evFilterChargerBrands method within TNEntitySearchParamsBuilder.The following table shows some common charge networks and their respective ids:

ID Charge Network
99100001 ChargePoint
99100002 Blink
99100003 eVgo
99100010 ElectrifyAmerica

Filter by Connector Type

This feature enables a driver to find EV charge stations by specific connector type such as J1772, CCS, etc. To filter charge stations by connector type use the .evFilterConnectorTypes method within TNEntitySearchParamsBuilder. The below table contains examples of commonly used connector types:

ID Connector Type
30001 J1772
30002 SAE Combo
30003 CHAdeMO

Filter by Charge Level

This feature enables a drive to find EV charge stations by specific power (charge) level such as Level 2 or DC Fast. To filter stations by charge level use the .evFilterPowerFeedLevels method within TNEntitySearchParamsBuilder. Currently supported power levels are:

ID Power Level
1 Level 1
2 Level 2
5 DC Fast
6 Ultra Fast

Filter for free chargers

This feature allows users to find EV charge stations that are free to use. When this filter is set to true only free connectors are returned, when set to false only paid connectors are returned, and when set to null all connectors are returned.

Filter by power

This feature enables a drive to find EV charge stations by specific power range in KW. To filter charge stations by power use the .evFilterMinPower & .evFilterMaxPower method within TNEntitySearchParamsBuilder.

Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
let params = TNEntitySearchParamsBuilder()
    .query("ev station")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .evFilterConnectorTypes(["30001", "30002"])
    .evFilterPowerFeedLevels([1, 2])
    .evFilterChargerBrands(["99100001"])
    .evFilterFreeCharge(true)
    .evFilterMinPower(32.0)
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

EV feature also supports two special search:

Exclusion filter: Specify the EV network to be excluded.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
let params = TNEntitySearchParamsBuilder()
    .query("ev station")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .evFilterChargerBrands(["99100001", "99100003"], TNEntityFilterType.exclude)
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

Searching by OCPI location ID:

 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
let params = TNEntitySearchParamsBuilder()
    .query("OCPI_LOCATION_ID=USCPIL9813")
    .location(TNEntityGeoPoint(lat: 37.78509, lon: -122.41988))
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

// or
params = TNEntitySearchParamsBuilder()
    .query(TNEntityMultiboxQuery()
            .addTag(TNEntityTag.ocpiLocatioinId, "USCPIL9813")
            .build())
    .location(TNEntityGeoPoint(lat: 37.78509, lon: -122.41988))
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {

        }
    }
}

Usually the location used for current vehicle position (CVP) and search point is the same. When the vehicle position and the desired search location are not the same, the search location can be specified by setting parameter anchor.

  • If both location and anchor exist:
    • location will be used as current vehicle position to calculate driving distance and driving time.
    • anchor will be used as search location.
  • if only location exist:
    • location will be used as the current vehicle position and search position.

Key methods

Method Details
query(query: String) Free form search text indicating search intent
Note: category or brand filter can be used in place of query text
location(location: TNEntityGeoPoint) A geopoint value of the user’s location using geographic coordinates of latitude and longitude. For example, TNEntityGeoPoint(lat: 0, lon: 0)
anchor(location: TNEntityGeoPoint) A geopoint value of the search location using geographic coordinates of latitude and longitude. For example, TNEntityGeoPoint(lat: 0, lon: 0)


Sample code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
let params = TNEntitySearchParamsBuilder()
    .query("Fast Food")
    .location(TNEntityGeoPoint(lat: 37.12419, lon: -121.98828))
    .anchor(TNEntityGeoPoint(lat: 37.32587, lon: -121.86442))
    .build()

TNEntityClient.search(params: params) { (telenavSearchResult, err) in
    if let entities = telenavSearchResult?.results {
        for entity in entities {
            if entity.type == .place {
                print(entity.place?.name)
            } else {
                print(entity.address?.formattedAddress)
            }
        }
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
TNEntitySearchParams *params = [[[[[TNEntitySearchParamsBuilder new]
                                  query:@"Fast Food"]
                                 location:[TNEntityGeoPoint pointWithLat:-37.12419 lon:-121.98828]]
                                 anchor:[TNEntityGeoPoint pointWithLat:37.32587 lon:-121.86442]] build];

[TNEntityClient searchWithSearchParams:params completion:^(TNEntitySearchResult * _Nullable res, NSError * _Nullable err) {
    for (TNEntity *entity in res.results) {
        if (entity.type == TNEntityTypePlace) {
            NSLog(@"%@", entity.place.name);
        } else {
            NSLog(@"%@", entity.address.formattedAddress);
        }
    }
}];