Skip to main content

Offline Search

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:

  1. SDK installation
  2. Downloading the offline tiles
  3. Searching with the downloaded data


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.


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 {

Once TileStore instance is initialized, you can create OfflineSearchEngine:

val searchEngine = OfflineSearchEngine.create(
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(
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()

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.
Forward geocoding

Forward geocoding allows you to search for places by name.

  • Reverse geocoding is an opposite operation of forward geocoding: for the given geographic coordinates a user gets place names or addresses.
Reverse geocoding

Reverse geocoding allows you to enter a geographic coordinate and receive the name of one or more places that exist at that location.

  • Search along the street works like forward geocoding but accepts a street name and returns addresses nearby the specified street.
Was this page helpful?