sdk/com.mapbox.search/SearchEngine

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)

SearchEngine API requires an online connection to execute the requests.

Instantiating

Call SearchEngine.createSearchEngine 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.onResults;
- For SearchSuggestionType.Brand additional network request will be executed and list of results will be passed to SearchSelectionCallback.onResults;
- 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.

Types

Companion

object Companion

Companion object.

Functions

forward

open fun forward(query: String, options: ForwardSearchOptions, callback: SearchCallback): AsyncOperationTask

abstract fun forward(query: String, options: ForwardSearchOptions, executor: Executor, callback: SearchCallback): AsyncOperationTask

One-off search request to get a list of search results with coordinates and metadata. In contrast to Interactive Search (search and select functions), the forward request will not provide type-ahead suggestions, e.g., brand and category suggestions, but will only provide relevant search results. See the Text Search documentation page for more details.

registerDataProvider

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

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

Registers dataProvider in this SearchEngine.

retrieve

open fun retrieve(mapboxId: String, callback: SearchResultCallback): AsyncOperationTask

Function to retrieve the details for a given mapboxId that dispatches events using the main executor. The callback will be invoked with a SearchResult on successful execution.

abstract fun retrieve(mapboxId: String, executor: Executor, callback: SearchResultCallback): AsyncOperationTask

Function to retrieve the details for a given mapboxId. The callback will be invoked with a SearchResult on successful execution. This method is only supported for a SearchEngine with ApiType.SEARCH_BOX or ApiType.SBS.

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

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

Performs reverse geocoding.

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

open fun search(categoryName: String, options: CategorySearchOptions, executor: Executor, callback: SearchCallback): AsyncOperationTask

Performs a search request for places based on a category.

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

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

The first step of forward geocoding. Returns a list of SearchSuggestion without coordinates.

open fun search(categoryNames: List<String>, options: CategorySearchOptions, callback: SearchCallback): AsyncOperationTask

abstract fun search(categoryNames: List<String>, options: CategorySearchOptions, executor: Executor, callback: SearchCallback): AsyncOperationTask

Performs a search request for places based on multiple categories.

select

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

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

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

The second step of forward geocoding. Call this function to get a SearchResult (with coordinates) from a SearchSuggestion.

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

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

Deprecated, consider making a selection of only one Search Suggestion.

unregisterDataProvider

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

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

Unregisters previously registered IndexableDataProvider.

Properties

analyticsService

abstract val analyticsService: AnalyticsService

AnalyticsService instance associated with this SearchEngine.

apiType

abstract val apiType: ApiType

The type of the API used by the Search Engine.

settings

abstract val settings: SearchEngineSettings

Settings used for SearchEngine initialization.