> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/search/llms.txt)

# Favorites

**Favorites** is a predefined type of [Data Provider](https://docs.mapbox.com/android/search/guides/search-engine/data-providers/) that stores [`FavoriteRecords`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.record/-favorite-record/). This data provider is designed to store user's favorite places, addresses, POIs.

## Working with Favorites

`Favorites` is available via [`FavoritesDataProvider`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.record/-favorites-data-provider/) which can be obtained from the [`ServiceProvider.favoritesDataProvider`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-service-provider/favorites-data-provider.html):

```kotlin
val favoritesDataProvider = ServiceProvider.INSTANCE.favoritesDataProvider()
```

As any other [Data provider](https://docs.mapbox.com/android/search/guides/search-engine/data-providers/), `FavoritesDataProvider` gives the API to read or change favorite entries.

### `SearchEngine` with `FavoritesDataProvider`

[`SearchEngine`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-engine/) with attached `FavoritesDataProvider` will suggest results from saved favorites that match the query. If a `SearchEngine` instance is created via [`SearchEngine.createSearchEngineWithBuiltInDataProviders()`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search/-search-engine/-companion/create-search-engine-with-built-in-data-providers.html), the `FavoritesDataProvider` is already attached to the `SearchEngine`. Otherwise, `FavoritesDataProvider` can be attached later:

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

val registerTask = searchEngine.registerDataProvider(
    ServiceProvider.INSTANCE.favoritesDataProvider(),
    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)
        }
    }
)
```

> **Related content (example): [Favorites](https://docs.mapbox.com/android/search/examples/favorites/)**
> 
> 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:

![Mobile device displaying Work favorite record](https://docs.mapbox.com/android/assets/ideal-img/search-favorite-work.a68974c.480.png)

To add such a record to `Favorites`, provide needed name as [`FavoriteRecord.name`](https://docs.mapbox.com/android/search/api/core/2.28.2/sdk/com.mapbox.search.record/-favorite-record/name.html) property. For example, to add `"Work"` favorite record:

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

    val record = FavoriteRecord(
        id = searchResult.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`](https://docs.mapbox.com/android/search/guides/search-engine/search-history/#search-history-in-ui), the [`SearchEngineUiAdapter`](https://docs.mapbox.com/android/search/guides/search-ui/results-view/) will suggest favorite records that match the query, such search results a marked with a `star` icon.

Also, [`Search Place`](https://docs.mapbox.com/android/search/api/ui/2.28.2/ui/com.mapbox.search.ui.view.place/-search-place/) can be added to the Favorites from the [`Place Card`](https://docs.mapbox.com/android/search/guides/search-ui/place-card/).

Your browser doesn't support HTML5 video. Open [link to the video](https://docs.mapbox.com/android/android/assets/medias/search-favorites-demo-626110b460ece14ac7b4c726aa09aa08.mp4).