Offline Search | Search SDK | Android Docs

Enable offline search

The Mapbox Offline Search for Android is a premium feature. Contact our sales team to enable your Mapbox account for Offline Search.

The Mapbox Offline Search for Android gives you the tools you need to add an offline search experience to your application. It takes only a few steps to make your application work offline.

These are a few key terms and concepts you may need to reference when working with the Offline Search:

Offline Search Engine: The Offline Search Engine API provides an entrypoint for offline search functionality. It is used to make search requests in offline and to produce tileset descriptors that can be used with a tile store.
Tileset descriptor: A tileset descriptor contains metadata about the tilesets that cached tile packs should include. You can create tileset descriptors with the Offline Search Engine.
Tile Region: A tile region is a geographic area for which offline data is needed. Tile regions are used by tile stores to fetch and manage tile packs necessary to provide offline support in that area. To create a tile region, a developer must specify a geometry describing each region's boundaries, and source tileset(s).
Tile Store: The tile store manages retrieving and organizing tile regions. The Offline Search only uses the tile store for tile regions. Although the Offline Search handles creating tileset descriptors, it is the job of the tile store to manage tile regions. You should keep the TileStore instance by keeping a reference to it while using the SDK to avoid unnecessary re-initialization and possible loss of options you provided earlier. When a user creates a tile store instance, the user must handle initializing the TileStore with proper options(using TileStore#setOption() API), including an access token.

Integration guide

Using Offline Search requires three steps:

SDK installation
Downloading the offline tiles
Searching with the downloaded data

Installation

guide

Installation guide

Before you are able to use any of the Search products you need to do common installation steps. Follow this guide to install, then continue with the steps below.

chevron-right

Tile regions downloading

Initialize `OfflineSearchEngine` and `TileStore` instances

OfflineSearchEngine and TileStore are two main components required for the offline search functionality.

TileStore allows users to create and download offline regions ahead of time, enabling offline search functionality.

TileStore with the Navigation and Maps SDKs

TileStore handles offline regions data for the Search SDK, the Navigation SDK, and the Maps SDK. Find more details on how to use TileStore for map data in the Maps SDK documentation, and for navigation data in the Navigation SDK documentation.

val tileStore = TileStore.create().apply {
    setOption(
        TileStoreOptions.MAPBOX_ACCESS_TOKEN,
        TileDataDomain.SEARCH,
        Value("token")
    )
}

Once TileStore instance is initialized, you can create OfflineSearchEngine:

val searchEngine = OfflineSearchEngine.create(
    OfflineSearchEngineSettings(
        accessToken = "token",
        tileStore = tileStore
    )
)

Define a tileset descriptors and load tile regions

Use the tileset descriptor to define the tilesets that will be available for the offline search. The Offline Search supports the following data types:

Address: Individual residential or business addresses.
Place: Typically these are cities, villages, municipalities, etc.

Use OfflineSearchEngine.createTilesetDescriptor() to create descriptors describing addresses, and OfflineSearchEngine.createPlacesTilesetDescriptor() for places:

val descriptors = listOf(
    OfflineSearchEngine.createTilesetDescriptor(),
    OfflineSearchEngine.createPlacesTilesetDescriptor(),
)

Unstable dataset version names in beta

Dataset and version names required for tileset descriptor creation are unstable. It's recommended to use createTilesetDescriptor(), and createPlacesTilesetDescriptor() functions with default parameters while the Offline Search is in beta.

To start a tiles loading operation, provide descriptors and geometry defining a set of tiles to be loaded to the TileRegionLoadOptions:

val tileRegionId = "Washington DC"
val dcLocation = Point.fromLngLat(-77.0339911055176, 38.899920004207516)

val tileRegionLoadOptions = TileRegionLoadOptions.Builder()
    .descriptors(descriptors)
    .geometry(dcLocation)
    .build()

And then start tiles loading operation:

val tilesLoadingTask = tileStore.loadTileRegion(tileRegionId, tileRegionLoadOptions, onProgressCallback, onFinishedCallback)

Observe tile regions state

When tile regions downloading successfully finished, OfflineSearchEngine needs some time to index data, usually this takes less than a second, depending on downloaded data size. To observe tile regions state and data availability for the OfflineSearchEngine, add OnIndexChangeListener:

searchEngine.addOnIndexChangeListener(object : OfflineSearchEngine.OnIndexChangeListener {
    override fun onIndexChange(event: OfflineIndexChangeEvent) {
        if (event.regionId == tileRegionId && (event.type == EventType.ADD || event.type == EventType.UPDATE)) {
            // Regions with id `tileRegionId` is ready and available for search
        }
    }

    override fun onError(event: OfflineIndexErrorEvent) {
        // Process error
    }
})

Note that OnIndexChangeListener will not be called if it's added after tile region data is processed, so OnIndexChangeListener should be added before TileStore.loadTileRegion() call if you need to check whether tile region is available for the search.

Search in offline

Once the above steps are complete, you can start making search requests in offline mode. OfflineSearchEngine provides functionality for:

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.

example

Forward geocoding

Forward geocoding allows you to search for places by name.

chevron-right