Beta
Search SDK for Android

Offline

Private beta

The Mapbox Offline Search SDK for Android is in a private beta. Contact sales team if you are interested in an early preview of the Offline Search SDK.

The Mapbox Offline Search SDK 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 SDK:

  • 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 SDK only uses the tile store for tile regions. Although the Offline Search SDK 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 is responsible for 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
Installation guide

Before you are able to use any of the Search products you need to do common installation steps. Please follow this guide, 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 {
    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. Currently, the Offline Search SDK 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 private 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 SDK 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.

  • Reverse geocoding is an opposite operation of forward geocoding: for the given geographic coordinates a user gets place names or addresses.
example
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.