Search

Search engine help users find specific addresses, points of interest (POIs), and places. The Mapbox Search SDK for Android provides the SearchEngine class for:

• forward geocoding
• reverse geocoding
• category search

Forward geocoding is likely what comes to mind when you think about a typical search experience: for the given String query a user gets geographic coordinates of an address or place. For example, you can type in Lincoln Memorial and retrieve the geographic location of a place that matches that query (-77.050,38.889).

Reverse geocoding is an opposite operation of forward geocoding: for the given geographic coordinates a user gets place names or addresses. For example, turning -77.050, 38.889 into 2 Lincoln Memorial Circle NW address.

Category search allows you to select a category (for example, restaurants) and retrieve a list of POIs that belong to that category. For example, if you want to display many restaurants within walking distance of a theater on a map, you can use category search with the restaurants category.

The Mapbox Search SDK for Android provides a SearchEngine class for executing forward geocoding search requests, reverse geocoding search requests, and making category search requests. You can obtain an instance of the engine via the SearchEngine.createSearchEngine(SearchEngineSettings) method or via the createSearchEngineWithBuiltInDataProviders(SearchEngineSettings) method to obtain an instance of the engine with HistoryDataProvider and FavoritesDataProvider registered by default.

val searchEngine = SearchEngine.createSearchEngine(
    SearchEngineSettings(getString(R.string.mapbox_access_token))
)

or

val searchEngine = SearchEngine.createSearchEngineWithBuiltInDataProviders(
    SearchEngineSettings(getString(R.string.mapbox_access_token))
)

Forward geocoding

Forward geocoding in the Search SDK consists of two steps: suggestions search and suggestions selection.

Suggestions search

When you provide a String query and set of options, SearchOptions, to SearchEngine.search(), it returns a list of suggestions List<SearchSuggestion> that contain information about an address or a place (including name, categories, description, and type).

val task = searchEngine.search(
    "Paris Eiffel Tower",
    SearchOptions(limit = 5),
    searchCallback
)

Resulting suggestions will be passed to the SearchSuggestionsCallback.onSuggestions() callback:

val searchCallback = object : SearchSuggestionsCallback {
    override fun onSuggestions(suggestions: List<SearchSuggestion>, responseInfo: ResponseInfo) {
        val suggestion = suggestions.firstOrNull()
    }

    override fun onError(e: Exception) {
    }
}

Additional information, like geographic coordinates of a place, is not available at this step. To get more information about a suggestion you need to make a suggestion selection.

Suggestion selection

To retrieve more information for a specific suggestion, use the SearchEngine.select() method:

val selectRequestTask = searchEngine.select(suggestion, selectCallback)

The result of the select operation will be passed to one of the SearchSelectionCallback callback functions:

val selectCallback = object : SearchSelectionCallback {
    override fun onResult(
        suggestion: SearchSuggestion,
        result: SearchResult,
        responseInfo: ResponseInfo
    ) {
    }

    override fun onSuggestions(suggestions: List<SearchSuggestion>, responseInfo: ResponseInfo) {
    }

    override fun onCategoryResult(
        suggestion: SearchSuggestion,
        results: List<SearchResult>,
        responseInfo: ResponseInfo
    ) {
    }

    override fun onError(e: Exception) {
    }
}

Depending on the type of suggestion, SearchSuggestion.type, different selection logic is applied:

If the passed suggestion is of the type SearchResultSuggestion or IndexableRecordItem, then you receive information about coordinates in the SearchSelectionCallback.onResult() method:

val selectCallback = object : SearchSelectionCallback {
    override fun onResult(
        suggestion: SearchSuggestion,
        result: SearchResult,
        responseInfo: ResponseInfo
    ) {
        val coordinates = result.coordinate
    }

    override fun onSuggestions(suggestions: List<SearchSuggestion>, responseInfo: ResponseInfo) {
    }

    override fun onCategoryResult(
        suggestion: SearchSuggestion,
        results: List<SearchResult>,
        responseInfo: ResponseInfo
    ) {
    }

    override fun onError(e: Exception) {
    }
}

val options = SelectOptions(addResultToHistory = false)
val selectRequestTask = searchEngine.select(suggestion, options, selectCallback)

Batch suggestions selection

You can also select multiple suggestions at once with the SearchEngine.select() method. The only requirements are:

• All suggestions must originate from the same search request
• All suggestions should be allowed for batch selection

Invoke SearchSuggestion.isBatchResolveSupported to check if a suggestion can be used for batch selection.

val batchSuggestions = suggestions.filter { it.isBatchResolveSupported }
val selectRequestTask = searchEngine.select(batchSuggestions, multipleSelectCallback)

Provided results will be passed to the SearchMultipleSelectionCallback.onResult() callback.

val multipleSelectCallback = object : SearchMultipleSelectionCallback {
    override fun onResult(
        suggestions: List<SearchSuggestion>,
        results: List<SearchResult>,
        responseInfo: ResponseInfo
    ) {
    }

    override fun onError(e: Exception) {
    }
}

Reverse geocoding

When you provide a Point location and set of options, ReverseGeoOptions, to ReverseGeocodingSearchEngine, it returns a list of places, addresses, and POIs List<SearchResult>.

val task = searchEngine.search(
    ReverseGeoOptions(
        center = Point.fromLngLat(2.294434, 48.858349)
    ),
    reverseSearchCallback
)

Resulting suggestions will be passed to the SearchCallback.onResults() callback:

val reverseSearchCallback = object : SearchCallback {
    override fun onResults(results: List<SearchResult>, responseInfo: ResponseInfo) {
    }

    override fun onError(e: Exception) {
    }
}

Category search

When you provide a String query and set of options, CategorySearchOptions, to CategorySearchEngine, it returns a list of POIs List<SearchResult>. You can find a list of common category names in the Mapbox Geocoding API documentation.

val task = searchEngine.search(
    "cafe",
    CategorySearchOptions(limit = 1),
    categorySearchCallback
)

Resulting suggestions will be passed to the SearchCallback.onResults() callback:

val categorySearchCallback = object : SearchCallback {
    override fun onResults(results: List<SearchResult>, responseInfo: ResponseInfo) {
    }

    override fun onError(e: Exception) {
    }
}

Add search to an app

This example will show you how to use pre-built UI component to quickly add search to an app.

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
 
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:label="@string/app_name"
android:roundIcon="@mipmap/ic_launcher_round"
android:theme="@style/AppTheme"
>
 
<activity
android:name=".MainActivity"
android:exported="true">
 
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
</application>

<?xml version="1.0" encoding="utf-8"?>
<FrameLayout
xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="match_parent"
>
 
<EditText
android:id="@+id/query_edit_text"
android:layout_width="match_parent"
android:layout_height="56dp"
android:hint="Where to?"
android:paddingHorizontal="16dp"
/>
 
<com.mapbox.search.ui.view.SearchResultsView
android:id="@+id/search_results_view"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:layout_marginTop="56dp"
android:paddingVertical="16dp"
/>
</FrameLayout>

import android.Manifest.permission
import android.content.Context
import android.content.pm.PackageManager
import android.os.Bundle
import android.text.Editable
import android.text.TextWatcher
import android.widget.EditText
import android.widget.Toast
import androidx.appcompat.app.AppCompatActivity
import androidx.core.app.ActivityCompat
import androidx.core.content.ContextCompat
import com.mapbox.search.ApiType
import com.mapbox.search.ResponseInfo
import com.mapbox.search.SearchEngine
import com.mapbox.search.SearchEngineSettings
import com.mapbox.search.ServiceProvider
import com.mapbox.search.offline.OfflineResponseInfo
import com.mapbox.search.offline.OfflineSearchEngine
import com.mapbox.search.offline.OfflineSearchEngineSettings
import com.mapbox.search.offline.OfflineSearchResult
import com.mapbox.search.record.HistoryRecord
import com.mapbox.search.result.SearchResult
import com.mapbox.search.result.SearchSuggestion
import com.mapbox.search.ui.view.CommonSearchViewConfiguration
import com.mapbox.search.ui.view.DistanceUnitType
import com.mapbox.search.ui.view.SearchResultsView
 
class MainActivity : AppCompatActivity() {
 
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
 
val accessToken = getString(R.string.mapbox_access_token)
 
val queryEditText = findViewById<EditText>(R.id.query_edit_text)
val searchResultsView = findViewById<SearchResultsView>(R.id.search_results_view)
searchResultsView.initialize(
SearchResultsView.Configuration(
commonConfiguration = CommonSearchViewConfiguration(DistanceUnitType.IMPERIAL)
)
)
 
val searchEngine = SearchEngine.createSearchEngineWithBuiltInDataProviders(
apiType = ApiType.GEOCODING,
settings = SearchEngineSettings(accessToken)
)
 
val offlineSearchEngine = OfflineSearchEngine.create(
OfflineSearchEngineSettings(accessToken)
)
 
val searchEngineUiAdapter = SearchEngineUiAdapter(
view = searchResultsView,
searchEngine = searchEngine,
offlineSearchEngine = offlineSearchEngine,
)
 
searchEngineUiAdapter.addSearchListener(object : SearchEngineUiAdapter.SearchListener {
 
private fun showToast(message: String) {
Toast.makeText(applicationContext, message, Toast.LENGTH_SHORT).show()
}
 
override fun onSuggestionsShown(suggestions: List<SearchSuggestion>, responseInfo: ResponseInfo) {
// not implemented
}
 
override fun onCategoryResultsShown(
suggestion: SearchSuggestion,
results: List<SearchResult>,
responseInfo: ResponseInfo
) {
// not implemented
}
 
override fun onOfflineSearchResultsShown(results: List<OfflineSearchResult>, responseInfo: OfflineResponseInfo) {
// not implemented
}
 
override fun onSuggestionSelected(searchSuggestion: SearchSuggestion): Boolean {
return false
}
 
override fun onSearchResultSelected(searchResult: SearchResult, responseInfo: ResponseInfo) {
showToast("SearchResult clicked: ${searchResult.name}")
}
 
override fun onOfflineSearchResultSelected(searchResult: OfflineSearchResult, responseInfo: OfflineResponseInfo) {
showToast("OfflineSearchResult clicked: ${searchResult.name}")
}
 
override fun onError(e: Exception) {
showToast("Error happened: $e")
}
 
override fun onHistoryItemClick(historyRecord: HistoryRecord) {
showToast("HistoryRecord clicked: ${historyRecord.name}")
}
 
override fun onPopulateQueryClick(suggestion: SearchSuggestion, responseInfo: ResponseInfo) {
queryEditText.setText(suggestion.name)
}
 
override fun onFeedbackItemClick(responseInfo: ResponseInfo) {
// not implemented
}
})
 
queryEditText.addTextChangedListener(object : TextWatcher {
 
override fun onTextChanged(s: CharSequence, start: Int, before: Int, after: Int) {
searchResultsView.search(s.toString())
}
 
override fun beforeTextChanged(s: CharSequence, start: Int, count: Int, after: Int) {
// not implemented
}
 
override fun afterTextChanged(e: Editable) { /* not implemented */ }
})
 
if (!isPermissionGranted(permission.ACCESS_FINE_LOCATION)) {
ActivityCompat.requestPermissions(
this,
arrayOf(permission.ACCESS_FINE_LOCATION, permission.ACCESS_COARSE_LOCATION),
PERMISSIONS_REQUEST_LOCATION
)
}
}
 
private companion object {
 
private const val PERMISSIONS_REQUEST_LOCATION = 0
 
fun Context.isPermissionGranted(permission: String): Boolean {
return ContextCompat.checkSelfPermission(
this, permission
) == PackageManager.PERMISSION_GRANTED
}
}
}

Run your application and you will see a functional search UI. Begin typing in the search bar to see results: