SearchEngine

interface SearchEngine

Performs

forward geocoding (looking up a place by name to retrieve its geographic coordinates)
category search(search for places by category name)
reverse geocoding(search for places by geographic coordinate)

Unlike OfflineSearchEngine, SearchEngine API requires an online connection to execute the requests.

Instantiating

Call MapboxSearchSdk.getSearchEngine to get instance of a SearchEngine.

Forward geocoding algorithm

Forward geocoding consists of 2 steps:

Retrieve suggestions (search). For giving query we provide a list of suggestions, which contain only basic information (name of a place/category/query, its description, its type and etc.). Provided suggestions will be passed to SearchSuggestionsCallback.onSuggestions. Note, that such information as coordinates of place is not available at this step. To get this information, proceed to next step;
Get more details for suggestion (select). Depending on suggestion type, different logic might be applied:
- For SearchSuggestionType.SearchResultSuggestion additional network request will be executed and result will be passed to SearchSelectionCallback.onResult;
- For SearchSuggestionType.Category additional network request will be executed and list of results will be passed to SearchSelectionCallback.onCategoryResult;
- For SearchSuggestionType.Query additional network request will be executed and another list of suggestions will be passed to SearchSelectionCallback.onSuggestions. To get more information for provided suggestions you should use the same step (select);
- For SearchSuggestionType.IndexableRecordItem extra information will be retrieved locally and result will be passed to SearchSelectionCallback.onResult.
If you want to get coordinates of search suggestion (or more details about suggestion), you should use select method. You will receive more detailed information.

Error handling

If invalid parameters are provided, RuntimeException is thrown immediately. Any other error will be propagated to SearchSuggestionsCallback.onError.

See also

com.mapbox.search.OfflineSearchEngine

com.mapbox.search.MapboxSearchSdk

Functions

registerDataProvider

open fun <R : IndexableRecord> registerDataProvider(dataProvider: IndexableDataProvider<R>, callback: CompletionCallback<Unit>): AsyncOperationTask

Registers dataProvider in this SearchEngine.

abstract fun <R : IndexableRecord> registerDataProvider(dataProvider: IndexableDataProvider<R>, executor: Executor, callback: CompletionCallback<Unit>): AsyncOperationTask

Registers dataProvider in this SearchEngine.

search

open fun search(options: ReverseGeoOptions, callback: SearchCallback): SearchRequestTask

Performs reverse geocoding.

abstract fun search(options: ReverseGeoOptions, executor: Executor, callback: SearchCallback): SearchRequestTask

Performs reverse geocoding.

open fun search(categoryName: String, options: CategorySearchOptions, callback: SearchCallback): SearchRequestTask

Performs a search request for places based on a category.

open fun search(query: String, options: SearchOptions, callback: SearchSuggestionsCallback): SearchRequestTask

The first step of forward geocoding.

abstract fun search(categoryName: String, options: CategorySearchOptions, executor: Executor, callback: SearchCallback): SearchRequestTask

Performs a search request for places based on a category.

abstract fun search(query: String, options: SearchOptions, executor: Executor, callback: SearchSuggestionsCallback): SearchRequestTask

The first step of forward geocoding.

select

open fun select(suggestion: SearchSuggestion, callback: SearchSelectionCallback): SearchRequestTask

The second step of forward geocoding.

open fun select(suggestions: List<SearchSuggestion>, callback: SearchMultipleSelectionCallback): SearchRequestTask

Function to select multiple suggestions at once.

open fun select(suggestion: SearchSuggestion, options: SelectOptions, callback: SearchSelectionCallback): SearchRequestTask

The second step of forward geocoding.

abstract fun select(suggestions: List<SearchSuggestion>, executor: Executor, callback: SearchMultipleSelectionCallback): SearchRequestTask

Function to select multiple suggestions at once.

abstract fun select(suggestion: SearchSuggestion, options: SelectOptions, executor: Executor, callback: SearchSelectionCallback): SearchRequestTask

The second step of forward geocoding.

unregisterDataProvider

open fun <R : IndexableRecord> unregisterDataProvider(dataProvider: IndexableDataProvider<R>, callback: CompletionCallback<Unit>): AsyncOperationTask

Unregisters previously registered IndexableDataProvider.

abstract fun <R : IndexableRecord> unregisterDataProvider(dataProvider: IndexableDataProvider<R>, executor: Executor, callback: CompletionCallback<Unit>): AsyncOperationTask

Unregisters previously registered IndexableDataProvider.

Properties

apiType

abstract val apiType: ApiType

Experimental API, can be changed or removed in the next SDK releases.