Skip to main content


Favorites is a predefined type of Data Provider that stores FavoriteRecords. This data provider is designed to store user's favorite places, addresses, POIs.

Working with Favorites

Favorites is available via FavoritesDataProvider which can be obtained from the ServiceProvider.favoritesDataProvider:

val favoritesDataProvider = ServiceProvider.INSTANCE.favoritesDataProvider()

As any other Data provider, FavoritesDataProvider gives the API to read or modify favorite entries.

SearchEngine with FavoritesDataProvider

SearchEngine with attached FavoritesDataProvider will suggest results from saved favorites that match the query. If a SearchEngine instance is created via SearchEngine.createSearchEngineWithBuiltInDataProviders(), the FavoritesDataProvider is already attached to the SearchEngine. Otherwise, FavoritesDataProvider can be attached later:

val searchEngine = SearchEngine.createSearchEngine(

val registerTask = searchEngine.registerDataProvider(
object : CompletionCallback<Unit> {
override fun onComplete(result: Unit) {
Log.i("SearchApiExample", "Favorites data provider has been attached")

override fun onError(e: Exception) {
Log.i("SearchApiExample", "Unable to attach favorites data provider", e)

Learn how to save a new favorite record, access all saved favorites, and receive notifications about changes to saved favorites.


Favorite records with custom names

You can save favorite records with custom names, for example, "Work" or "Home". In this case SearchEngine will suggest such records that match their names:

To add such a record to Favorites, provide needed name as property. For example, to add "Work" favorite record:

fun addWorkAddressToFavorites(searchResult: SearchResult, favoritesDataProvider: FavoritesDataProvider) {
if (!isWorkAddress(searchResult)) return

val record = FavoriteRecord(
id =,
name = "Work",
descriptionText = searchResult.descriptionText,
address = searchResult.address,
routablePoints = searchResult.routablePoints,
categories = searchResult.categories,
makiIcon = searchResult.makiIcon,
coordinate = searchResult.coordinate,
type = searchResult.types.first(),
metadata = searchResult.metadata,

val upsertTask = favoritesDataProvider.upsert(record, object : CompletionCallback<Unit> {
override fun onComplete(result: Unit) {
Log.i("SearchApiExample", "$record is saved to Favorites")

override fun onError(e: Exception) {
Log.i("SearchApiExample", "Unable to save $record to Favorites", e)

Favorites in UI

Similarly to the Search history, the SearchEngineUiAdapter will suggest favorite records that match the query, such search results a marked with a star icon.

Also, Search Place can be added to the Favorites from the Place Card.

Was this page helpful?