Documentation

Initialization

There are two ways to perform a search:

1. Create a SearchAPI (android-sdk-search) object
2. Start and bind to a SearchService (android-sdk-search-extensions)

You should use the first option if you want to handle multithreading / orientation changing and caching by yourself. The second option is dedicated to you if you want to have an easy, out of the box Android Service which will handle most of the mentioned problems by itself. Both options are described in the following section. They all use the same public API. In both cases you will need the appropriate Search API Key. For more information on obtaining and configuring TomTom API Keys and their configuration, go to the "Getting started" subpage.

A SearchApi object is created in the following manner:

SearchApi searchApi = OnlineSearchApi.create(context, BuildConfig.SEARCH_API_KEY)

private val searchApi = OnlineSearchApi.create(context, BuildConfig.SEARCH_API_KEY)

The alternative to using a SearchAPI object is to create the SearchService. To do so, first use SearchServiceManager to create a ServiceConnection object and set SearchServiceConnectionCallback to react on bind to the service event:

searchServiceConnection = SearchServiceManager.createAndBind(getContext(),
        searchServiceConnectionCallback());

val searchServiceConnection = SearchServiceManager.createAndBind(context,
    searchServiceConnectionCallback)

To unbind from SearchService use the following:

SearchServiceManager.unbind(getContext(), searchServiceConnection);

SearchServiceManager.unbind(context, searchServiceConnection)

In the preceding example, the SearchFragmentPresenter was chosen to play the role of a listener on a source callback. An example implementation can be as follows:

1@Override
2public void onBindSearchService(SearchService service) {
3    searchService = service;
4}

1override fun onBindSearchService(service: SearchService) {
2    val searchService = service
3}

The Android Search API provides simple yet very handy search functionality. An application developer can implement his own search component using either a classic callback-based approach or use a reactive search.

the first approach involves using the void search() method, taking the SearchQuery and FuzzySearchResultListener implementation as parameters. Implementation of FuzzySearchResultListener should cover the following two methods:

void onSearchResult(FuzzySearchResponse results);

void onSearchError(final SearchError error);

The methods are calling back a list of SearchResult objects with corresponding content. All poles of SearchResult have associated getters, so its information is easily accessible.

Another way to subscribe a search response is to use a reactive search method. It returns a RxJavas Observable<List<SearchResult>>. To take advantage of this implementation, one has to subscribe for it (for instance with a Disposable<List<SearchResult>> or a Consumer<List<SearchResult>>.

An example implementation can look like the following code:

searchService.search(specification, fuzzyOutcomeCallback);

1searchService.search(query)
2    .subscribeOn(workingScheduler)
3    .observeOn(resultScheduler)
4    .subscribe(observer)

Example implementation of subscriber:

1private FuzzyOutcomeCallback fuzzyOutcomeCallback = new FuzzyOutcomeCallback() {
2    @Override
3    public void onSuccess(@NonNull FuzzyOutcome fuzzyOutcome) {
4        lastSearchResult = ImmutableList.copyOf(fuzzyOutcome.getFuzzyDetailsList());
5        searchView.updateSearchResults(ImmutableList.copyOf(fuzzyOutcome.getFuzzyDetailsList()));
6        searchFinished();
7    }
8
9    @Override
10    public void onError(@NonNull SearchException error) {
11        searchView.showSearchFailedMessage(error.getMessage());
12        searchView.updateSearchResults(ImmutableList.of());
13        searchFinished();
14    }
15};

1val observer = object : DisposableSingleObserver<FuzzySearchResponse>() {
2    override fun onSuccess(fuzzySearchResponse: FuzzySearchResponse) {
3        Resource.success(fuzzySearchResponse.results)
4    }
5
6    override fun onError(throwable: Throwable) {
7        Resource.error(null, Error(throwable.message))
8    }
9}

Please note, a consecutive search request cannot be made before its successor’s callback (either onSearchResult or onSearchError) is received.

Concurrent search requests are not handled in the current version of the Maps SDK for Android, and an internal error is reported.