Developer

Search

Request Access

Search

The SearchManager enables developers to search for locations, addresses, and points of interest (POIs). It supports free-text search, category-based filtering, and geographic filtering to help users find destinations.

Overview

SearchManager provides functionality for:

  • Free-text search for addresses and POIs
  • Category-based POI search (restaurants, gas stations, etc.)
  • Brand name filtering
  • Geographic filtering (around position, along route)
  • Result type filtering
  • Paginated results

Basic text search

Perform a simple search with a query string:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.Coordinate
3import com.tomtom.automotive.integration.client.api.model.search.SearchRequest
4import com.tomtom.automotive.integration.client.api.model.search.SearchResult
5import com.tomtom.automotive.integration.client.api.model.search.filters.GeoFilter
6import com.tomtom.automotive.integration.client.api.search.SearchCallback
7import com.tomtom.automotive.integration.client.api.search.SearchFailure
8import com.tomtom.automotive.integration.client.api.search.SearchManager
9import com.tomtom.automotive.integration.client.api.search.SearchParameters
10import com.tomtom.automotive.integration.client.api.search.SearchResponse
11import com.tomtom.automotive.integration.client.common.Callback
12import com.tomtom.automotive.integration.client.common.Result
13import com.tomtom.automotive.integration.client.common.SdkReleasable
14

15private val TAG = "Search"
16private var searchReleasable: SdkReleasable? = null
17

18fun search(searchManager: SearchManager, query: String, currentPosition: Coordinate) {
19    val geoFilter = GeoFilter.ByPositionBias(coordinate = currentPosition)
20    
21    val searchRequest = SearchRequest(
22        query = query,
23        resultLimit = 10,
24        geoFilter = geoFilter,
25        filters = emptySet(),
26        pageSize = 5
27    )
28    
29    searchReleasable = searchManager.search(
30        SearchParameters(searchRequest),
31        object : SearchCallback {
32            override fun onResult(response: Result<SearchResponse, SearchFailure>) {
33                when (response) {
34                    is Result.Success -> {
35                        val results = response.value.results
36                        Log.d(TAG, "Found ${results.size} results")
37                        
38                        results.forEach { result ->
39                            logSearchResult(result)
40                        }
41                    }
42                    is Result.Failure -> {
43                        Log.e(TAG, "Search failed: ${response.reason}")
44                    }
45                }
46            }
47            
48            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
49                Log.e(TAG, "Search unavailable: ${reason.devMessage}")
50            }
51        }
52    )
53}
54

55private fun logSearchResult(result: SearchResult) {
56    val coordinate = result.data?.coordinate
57    when (result) {
58        is SearchResult.Poi -> Log.d(TAG, "POI: ${result.poiName} at $coordinate")
59        is SearchResult.Street -> Log.d(TAG, "Street: ${result.address.formattedAddress} at $coordinate")
60        is SearchResult.Area -> Log.d(TAG, "Area at $coordinate")
61        else -> Log.d(TAG, "Result at $coordinate")
62    }
63}
64

65fun cancelSearch() {
66    searchReleasable?.release()
67    searchReleasable = null
68}

Search with location context

Provide current position for better, location-relevant results:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.Coordinate
3import com.tomtom.automotive.integration.client.api.model.quantity.Distance
4import com.tomtom.automotive.integration.client.api.model.search.SearchRequest
5import com.tomtom.automotive.integration.client.api.model.search.filters.GeoFilter
6import com.tomtom.automotive.integration.client.api.search.SearchCallback
7import com.tomtom.automotive.integration.client.api.search.SearchFailure
8import com.tomtom.automotive.integration.client.api.search.SearchManager
9import com.tomtom.automotive.integration.client.api.search.SearchParameters
10import com.tomtom.automotive.integration.client.api.search.SearchResponse
11import com.tomtom.automotive.integration.client.common.Callback
12import com.tomtom.automotive.integration.client.common.Result
13

14private val TAG = "Search"
15

16fun searchNearby(searchManager: SearchManager, query: String, currentPosition: Coordinate) {
17    // Search within 5000 meters of current position
18    val geoFilter = GeoFilter.ByRadius(
19        center = currentPosition,
20        radius = Distance.meters(5000)
21    )
22    
23    val searchRequest = SearchRequest(
24        query = query,
25        resultLimit = 20,
26        geoFilter = geoFilter,
27        filters = emptySet(),
28        pageSize = 10
29    )
30    
31    searchManager.search(
32        SearchParameters(searchRequest),
33        object : SearchCallback {
34            override fun onResult(response: Result<SearchResponse, SearchFailure>) {
35                when (response) {
36                    is Result.Success -> {
37                        Log.d(TAG, "Found ${response.value.results.size} nearby results")
38                    }
39                    is Result.Failure -> {
40                        Log.e(TAG, "Nearby search failed: ${response.reason}")
41                    }
42                }
43            }
44            
45            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
46                Log.e(TAG, "Search unavailable: ${reason.devMessage}")
47            }
48        }
49    )
50}

Available geo filters

  • GeoFilter.ByPositionBias - Bias results toward a coordinate
  • GeoFilter.ByRadius - Search within a radius of a coordinate
  • GeoFilter.ByGeoBox - Search within a bounding box
  • GeoFilter.ByRoute - Search for POIs along the active route

Category-based search

Search for POIs by category (e.g., restaurants, gas stations):

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.Coordinate
3import com.tomtom.automotive.integration.client.api.model.quantity.Distance
4import com.tomtom.automotive.integration.client.api.model.search.SearchRequest
5import com.tomtom.automotive.integration.client.api.model.search.filters.GeoFilter
6import com.tomtom.automotive.integration.client.api.model.search.filters.SearchFilter
7import com.tomtom.automotive.integration.client.api.model.search.poi.PoiCategory
8import com.tomtom.automotive.integration.client.api.search.SearchCallback
9import com.tomtom.automotive.integration.client.api.search.SearchFailure
10import com.tomtom.automotive.integration.client.api.search.SearchManager
11import com.tomtom.automotive.integration.client.api.search.SearchParameters
12import com.tomtom.automotive.integration.client.api.search.SearchResponse
13import com.tomtom.automotive.integration.client.common.Callback
14import com.tomtom.automotive.integration.client.common.Result
15

16private val TAG = "Search"
17

18fun searchByCategory(searchManager: SearchManager, categories: Set<PoiCategory>, currentPosition: Coordinate) {
19    val geoFilter = GeoFilter.ByRadius(
20        center = currentPosition,
21        radius = Distance.meters(10000)
22    )
23    
24    val filters = setOf(
25        SearchFilter.ByPoiCategory(categories)
26    )
27    
28    val searchRequest = SearchRequest(
29        query = "",
30        resultLimit = 30,
31        geoFilter = geoFilter,
32        filters = filters,
33        pageSize = 10
34    )
35    
36    searchManager.search(
37        SearchParameters(searchRequest),
38        object : SearchCallback {
39            override fun onResult(response: Result<SearchResponse, SearchFailure>) {
40                when (response) {
41                    is Result.Success -> {
42                        Log.d(TAG, "Found ${response.value.results.size} category results")
43                    }
44                    is Result.Failure -> {
45                        Log.e(TAG, "Category search failed: ${response.reason}")
46                    }
47                }
48            }
49            
50            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
51                Log.e(TAG, "Search unavailable: ${reason.devMessage}")
52            }
53        }
54    )
55}
56

57// Example: Find petrol stations
58// searchByCategory(searchManager, setOf(PoiCategory.PETROL_STATION), currentPosition)

Filtering by brand name

Search for specific brands:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.Coordinate
3import com.tomtom.automotive.integration.client.api.model.quantity.Distance
4import com.tomtom.automotive.integration.client.api.model.search.SearchRequest
5import com.tomtom.automotive.integration.client.api.model.search.filters.GeoFilter
6import com.tomtom.automotive.integration.client.api.model.search.filters.SearchFilter
7import com.tomtom.automotive.integration.client.api.search.SearchCallback
8import com.tomtom.automotive.integration.client.api.search.SearchFailure
9import com.tomtom.automotive.integration.client.api.search.SearchManager
10import com.tomtom.automotive.integration.client.api.search.SearchParameters
11import com.tomtom.automotive.integration.client.api.search.SearchResponse
12import com.tomtom.automotive.integration.client.common.Callback
13import com.tomtom.automotive.integration.client.common.Result
14

15private val TAG = "Search"
16

17fun searchByBrand(searchManager: SearchManager, brandNames: Set<String>, currentPosition: Coordinate) {
18    val geoFilter = GeoFilter.ByRadius(
19        center = currentPosition,
20        radius = Distance.meters(15000)
21    )
22    
23    val filters = setOf(
24        SearchFilter.ByBrandName(brandNames)
25    )
26    
27    val searchRequest = SearchRequest(
28        query = "coffee",
29        resultLimit = 20,
30        geoFilter = geoFilter,
31        filters = filters,
32        pageSize = 5
33    )
34    
35    searchManager.search(
36        SearchParameters(searchRequest),
37        object : SearchCallback {
38            override fun onResult(response: Result<SearchResponse, SearchFailure>) {
39                when (response) {
40                    is Result.Success -> {
41                        Log.d(TAG, "Found ${response.value.results.size} brand results")
42                    }
43                    is Result.Failure -> {
44                        Log.e(TAG, "Brand search failed: ${response.reason}")
45                    }
46                }
47            }
48            
49            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
50                Log.e(TAG, "Search unavailable: ${reason.devMessage}")
51            }
52        }
53    )
54}
55

56// Example: Find Starbucks locations
57// searchByBrand(searchManager, setOf("Starbucks"), currentPosition)

Result type filtering

Filter results by type (POI, street, coordinate, etc.):

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.Coordinate
3import com.tomtom.automotive.integration.client.api.model.quantity.Distance
4import com.tomtom.automotive.integration.client.api.model.search.SearchRequest
5import com.tomtom.automotive.integration.client.api.model.search.filters.GeoFilter
6import com.tomtom.automotive.integration.client.api.model.search.filters.SearchFilter
7import com.tomtom.automotive.integration.client.api.model.search.filters.SearchResultType
8import com.tomtom.automotive.integration.client.api.search.SearchCallback
9import com.tomtom.automotive.integration.client.api.search.SearchFailure
10import com.tomtom.automotive.integration.client.api.search.SearchManager
11import com.tomtom.automotive.integration.client.api.search.SearchParameters
12import com.tomtom.automotive.integration.client.api.search.SearchResponse
13import com.tomtom.automotive.integration.client.common.Callback
14import com.tomtom.automotive.integration.client.common.Result
15

16private val TAG = "Search"
17

18fun searchPOIsOnly(searchManager: SearchManager, query: String, currentPosition: Coordinate) {
19    val geoFilter = GeoFilter.ByRadius(
20        center = currentPosition,
21        radius = Distance.meters(5000)
22    )
23    
24    val filters = setOf(
25        SearchFilter.ByResultType(setOf(SearchResultType.POI))
26    )
27    
28    val searchRequest = SearchRequest(
29        query = query,
30        resultLimit = 15,
31        geoFilter = geoFilter,
32        filters = filters,
33        pageSize = 5
34    )
35    
36    searchManager.search(
37        SearchParameters(searchRequest),
38        object : SearchCallback {
39            override fun onResult(response: Result<SearchResponse, SearchFailure>) {
40                when (response) {
41                    is Result.Success -> {
42                        Log.d(TAG, "Found ${response.value.results.size} POI results")
43                    }
44                    is Result.Failure -> {
45                        Log.e(TAG, "POI search failed: ${response.reason}")
46                    }
47                }
48            }
49            
50            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
51                Log.e(TAG, "Search unavailable: ${reason.devMessage}")
52            }
53        }
54    )
55}

Available result types

  • SearchResultType.POI - Points of interest
  • SearchResultType.STREET - Street addresses
  • SearchResultType.COORDINATE - Geographic coordinates
  • SearchResultType.INTERSECTION - Street intersections
  • SearchResultType.AREA - An area on map which represents administrative division of a land i.e. country, state, city.

Parsing search results

Handle different types of search results:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.search.SearchResult
3

4private val TAG = "Search"
5

6fun handleSearchResult(result: SearchResult) {
7    val coordinate = result.data?.coordinate
8    val areas = result.data?.areas ?: emptyList()
9    
10    when (result) {
11        is SearchResult.Poi -> {
12            val name = result.poiName
13            val address = result.address
14            val poiDetails = result.poiDetails
15            
16            Log.d(TAG, "POI: $name at $coordinate")
17            Log.d(TAG, "Address: ${address.formattedAddress}")
18            
19            poiDetails?.let {
20                val phone = it.phone
21                val website = it.website
22                val categories = it.category
23                
24                Log.d(TAG, "Phone: $phone, Website: $website")
25                Log.d(TAG, "Categories: $categories")
26            }
27        }
28        
29        is SearchResult.Street -> {
30            val address = result.address
31            Log.d(TAG, "Street: ${address.formattedAddress} at $coordinate")
32        }
33        
34        is SearchResult.Coordinate -> {
35            val address = result.address
36            Log.d(TAG, "Coordinate: $coordinate, Address: ${address.formattedAddress}")
37        }
38        
39        is SearchResult.Area -> {
40            Log.d(TAG, "Area at $coordinate, areas: $areas")
41        }
42        
43        is SearchResult.Intersection -> {
44            val address = result.address
45            Log.d(TAG, "Intersection: ${address.formattedAddress} at $coordinate")
46        }
47        
48        else -> {
49            Log.d(TAG, "Unhandled result type")
50        }
51    }
52}

Converting results to navigable locations

Use search results for trip planning:

1import com.tomtom.automotive.integration.client.api.model.Address
2import com.tomtom.automotive.integration.client.api.model.NavigableLocation
3import com.tomtom.automotive.integration.client.api.model.search.AddressData
4import com.tomtom.automotive.integration.client.api.model.search.SearchResult
5

6fun toNavigableLocation(result: SearchResult): NavigableLocation.Place? {
7    val coordinate = result.data?.coordinate ?: return null
8    
9    return when (result) {
10        is SearchResult.Poi -> {
11            NavigableLocation.Place(
12                coordinate = coordinate,
13                address = result.address.toAddress(),
14                name = result.poiName,
15                poiDetails = result.poiDetails
16            )
17        }
18        
19        is SearchResult.Street -> {
20            NavigableLocation.Place(
21                coordinate = coordinate,
22                address = result.address.toAddress(),
23                name = result.address.formattedAddress
24            )
25        }
26        
27        is SearchResult.Coordinate -> {
28            NavigableLocation.Place(
29                coordinate = coordinate,
30                address = result.address.toAddress()
31            )
32        }
33        
34        else -> {
35            NavigableLocation.Place(
36                coordinate = coordinate,
37                address = null
38            )
39        }
40    }
41}
42

43private fun AddressData.toAddress(): Address {
44    return Address(
45        houseNumber = houseNumber,
46        streetName = streetNames.firstOrNull(),
47        cityName = null,
48        postalCode = extendedPostalCode,
49        stateName = null,
50        stateCode = null,
51        cityDistrict = null,
52        countryName = null,
53        countryCode = null,
54        extendedPostalCode = extendedPostalCode,
55        formattedAddress = formattedAddress
56    )
57}

Reverse geocoding

The ReverseGeocoderManager converts geographic coordinates into human-readable addresses and place information.

Convert coordinate to address

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.model.Coordinate
3import com.tomtom.automotive.integration.client.api.model.NavigableLocation
4import com.tomtom.automotive.integration.client.api.reversegeocoder.ReverseGeocoderManager
5import com.tomtom.automotive.integration.client.api.reversegeocoder.getplacesforcoordinate.GetPlacesForCoordinateCallback
6import com.tomtom.automotive.integration.client.api.reversegeocoder.getplacesforcoordinate.GetPlacesForCoordinateFailure
7import com.tomtom.automotive.integration.client.api.reversegeocoder.getplacesforcoordinate.GetPlacesForCoordinateParameters
8import com.tomtom.automotive.integration.client.api.reversegeocoder.getplacesforcoordinate.GetPlacesForCoordinateResponse
9import com.tomtom.automotive.integration.client.common.Callback
10import com.tomtom.automotive.integration.client.common.Result
11import com.tomtom.automotive.integration.client.common.SdkReleasable
12

13private val TAG = "ReverseGeocoder"
14private var reverseGeocoderReleasable: SdkReleasable? = null
15

16fun reverseGeocode(reverseGeocoderManager: ReverseGeocoderManager, coordinate: Coordinate) {
17    val parameters = GetPlacesForCoordinateParameters(coordinate = coordinate)
18    
19    reverseGeocoderReleasable = reverseGeocoderManager.getPlacesForCoordinate(
20        parameters,
21        object : GetPlacesForCoordinateCallback {
22            override fun onGeocoderResult(
23                result: Result<GetPlacesForCoordinateResponse, GetPlacesForCoordinateFailure>
24            ) {
25                when (result) {
26                    is Result.Success -> {
27                        val places = result.value.places
28                        
29                        when {
30                            places.isEmpty() -> {
31                                Log.d(TAG, "No places found for coordinate")
32                            }
33                            places.size == 1 -> {
34                                Log.d(TAG, "Found place: ${places.first().name}")
35                                logPlace(places.first())
36                            }
37                            else -> {
38                                Log.d(TAG, "Found ${places.size} places")
39                                places.forEach { place -> logPlace(place) }
40                            }
41                        }
42                    }
43                    is Result.Failure -> {
44                        when (result.reason) {
45                            GetPlacesForCoordinateFailure.INTERNAL_ERROR -> {
46                                Log.e(TAG, "Reverse geocoding failed: Internal error")
47                            }
48                            GetPlacesForCoordinateFailure.UNHANDLED -> {
49                                Log.e(TAG, "Reverse geocoding failed: Unhandled error")
50                            }
51                        }
52                    }
53                }
54            }
55            
56            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
57                Log.e(TAG, "Reverse geocoding unavailable: ${reason.devMessage}")
58            }
59        }
60    )
61}
62

63private fun logPlace(place: NavigableLocation.Place) {
64    Log.d(TAG, "Name: ${place.name}")
65    Log.d(TAG, "Coordinate: ${place.coordinate}")
66    
67    place.address?.let {
68        Log.d(TAG, "Address: ${it.formattedAddress}")
69        Log.d(TAG, "Street: ${it.streetName} ${it.houseNumber ?: ""}")
70        Log.d(TAG, "City: ${it.cityName}, ${it.postalCode}")
71    }
72}
73

74fun cancelReverseGeocode() {
75    reverseGeocoderReleasable?.release()
76    reverseGeocoderReleasable = null
77}

The response contains a list of NavigableLocation.Place objects which may be empty (no data available), contain a single place (typical case), or contain multiple places.

Paginated results

Fetch additional results using pagination:

1import android.util.Log
2import com.tomtom.automotive.integration.client.api.search.SearchCallback
3import com.tomtom.automotive.integration.client.api.search.SearchFailure
4import com.tomtom.automotive.integration.client.api.search.SearchManager
5import com.tomtom.automotive.integration.client.api.search.SearchResponse
6import com.tomtom.automotive.integration.client.api.search.nextpage.GetNextPageParameters
7import com.tomtom.automotive.integration.client.common.Callback
8import com.tomtom.automotive.integration.client.common.Result
9

10private val TAG = "Search"
11

12fun getNextPage(searchManager: SearchManager, searchSessionId: String) {
13    searchManager.getNextPage(
14        GetNextPageParameters(searchSessionId),
15        object : SearchCallback {
16            override fun onResult(response: Result<SearchResponse, SearchFailure>) {
17                when (response) {
18                    is Result.Success -> {
19                        val additionalResults = response.value.results
20                        val hasMore = response.value.hasMoreData
21                        Log.d(TAG, "Fetched ${additionalResults.size} more results, hasMore: $hasMore")
22                    }
23                    is Result.Failure -> {
24                        Log.e(TAG, "Failed to fetch next page: ${response.reason}")
25                    }
26                }
27            }
28            
29            override fun onFunctionalityUnavailable(reason: Callback.Reason) {
30                Log.e(TAG, "Search unavailable: ${reason.devMessage}")
31            }
32        }
33    )
34}
35

36// Example usage with searchSessionId from initial search response:
37// if (searchResponse.hasMoreData) {
38//     getNextPage(searchManager, searchResponse.searchSessionId)
39// }