Offline Search

Connect via MCP

Add to CursorAdd to VS Code

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.

Integration guide

Using Offline Search requires three steps:

1. SDK installation
2. Getting the offline data: either a preinstalled tile pack or a download
3. Searching with the 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.

Offline data

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.

Once TileStore instance is initialized, you can create OfflineSearchEngine:

val searchEngine = OfflineSearchEngine.create(
    OfflineSearchEngineSettings(tileStore)
)

Get the offline data

Offline search reads its data from the TileStore. The data reaches the device in one of two ways:

• Preinstalled tile pack: the device comes with the offline data already installed. Contact our sales team to get a preinstalled tile pack for your devices.
• Download: the app downloads the data for the areas it needs with TileStore.loadTileRegion().

Describe the data

The offline data is described with TilesetParameters. A tileset contains two kinds of data:

• Detailed data: Individual addresses, streets, POIs (Points of Interest) such as cafes or charging stations, etc.
• Overview data: Countries, regions, cities, villages, municipalities, etc.

The exact split of data between the two kinds is subject to change.

Configure TilesetParameters with the following options:

• Dataset: use the default dataset with TilesetParameters.Builder(). If Mapbox has provided a dataset for your account, pass its name with TilesetParameters.Builder(dataset = "<dataset name>"). Dataset names may change while the Offline Search is in beta. Dataset versions are deprecated: the latest data is always used, so there is no need to pass a version.
• Language (optional): for example language(IsoLanguageCode.FRENCH). Without a language, results use the dataset's default names.
• Worldview (optional): worldview(language, worldview).
• Overview only (optional): overviewOnly(true) downloads only overview data. Searches then return no addresses, streets or POIs.

Experimental API

TilesetParameters and the functions that use it are experimental. Opt in with @OptIn(MapboxExperimental::class).

Create a tileset descriptor

A tileset descriptor tells the TileStore which data to download. It is also what other SDKs, such as the Navigation SDK's Predictive Cache, need to cache search data. Pass the TilesetParameters to OfflineSearchEngine.createTilesetDescriptor():

val tilesetParameters = TilesetParameters.Builder()
    .language(IsoLanguageCode.FRENCH) // optional
    .build()

val descriptor = OfflineSearchEngine.createTilesetDescriptor(
    tilesets = listOf(tilesetParameters),
)

To cover several languages, add one TilesetParameters per language to tilesets. The detailed data is downloaded once and shared by all languages.

Some languages need additional resources. For example, to search in Japanese, add the Japanese dictionary:

val descriptor = OfflineSearchEngine.createTilesetDescriptor(
    tilesets = listOf(
        TilesetParameters.Builder(dataset = "<dataset name>")
            .language(IsoLanguageCode.JAPANESE)
            .build()
    ),
    additionalResources = listOf(OfflineSearchResource.JAPANESE_DICTIONARY),
)

Japanese dictionary

The Japanese dictionary is not available to every account. Confirm with Mapbox before using it. Contact our sales team to get access.

Download the data

If the device has a preinstalled tile pack and you don't want to add areas that the preinstalled tile pack doesn't cover, you can skip this step.

Load a tile region with the descriptor:

val descriptor = OfflineSearchEngine.createTilesetDescriptor(
    tilesets = listOf(
        TilesetParameters.Builder().language(IsoLanguageCode.ENGLISH).build(),
        TilesetParameters.Builder().language(IsoLanguageCode.FRENCH).overviewOnly(true).build(),
    ),
)

val tileRegionLoadOptions = TileRegionLoadOptions.Builder()
    .descriptors(listOf(descriptor))
    .geometry(Point.fromLngLat(-77.0339911055176, 38.899920004207516))
    .build()

val tilesLoadingTask = tileStore.loadTileRegion(
    "Washington DC",
    tileRegionLoadOptions,
    onProgressCallback,
    onFinishedCallback,
)

Select the data to search

To search in a specific tileset, for example in a specific language, call OfflineSearchEngine.selectTileset() before searching, with the same TilesetParameters that describe the data:

searchEngine.selectTileset(tilesetParameters)

To change the language of the results, call selectTileset() again with another available language.

Start searching

You can search as soon as the data is available:

• with a preinstalled tile pack, when OfflineSearchEngine.EngineReadyCallback.onEngineReady() is called (register it with addEngineReadyCallback());
• with a download, when TileStore.loadTileRegion() reports success in its onFinished callback.

Deprecated

OnIndexChangeListener and the related OfflineIndexChangeEvent and OfflineIndexErrorEvent are deprecated and not guaranteed to work. Use the TileStore callbacks to find out when a 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

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.

You can search for addresses, POIs, or places offline using the OfflineSearchEngine.search() function. Provide the feature you’re looking for (e.g., POI name, address, city name) as a query parameter, along with OfflineSearchOptions, to start the search.

searchEngine.search(
    "1133 15th St NW, Washington, DC 20005, United States",
    OfflineSearchOptions(),
    searchCallback
)

By default, if location services are available, the OfflineSearchEngine uses the device's geolocation to bias the response, favoring results that are closer to the current location. You can also provide a custom proximity point to rank results closer to a specific location.

searchEngine.search(
    "cafe",
    OfflineSearchOptions(proximity = Point.fromLngLat(-77.03400094304453, 38.90484584480497)),
    searchCallback
)

Search along a street is a special case of forward geocoding. It allows you to find addresses near a specified street by using searchAddressesNearby.

searchEngine.searchAddressesNearby(
    street = "15th St",
    proximity = Point.fromLngLat(-77.03400094304453, 38.90484584480497),
    radiusMeters = 50.0,
    callback = searchCallback
)

EXAMPLE

Forward geocoding

Forward geocoding allows you to search for places by name.

Reverse geocoding

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

searchEngine.reverseGeocoding(
    OfflineReverseGeoOptions(Point.fromLngLat(-77.03400094304453, 38.90484584480497)),
    searchCallback
)

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 for EV Charging Stations

Experimental API

Search for EV Charging Stations is in a preview state and has a high chance of being changed in the future.

Limited support

Only specific datasets support the search for EV charging stations. Contact our sales team to access datasets that include EV charging station data.

Search for EV Charging Stations supports additional parameters and can provide extended metadata. For instance, you can filter charging stations by specific operators, connector types, and charging power. Call OfflineSearchEngine.search() and pass OfflineEvSearchOptions as the OfflineSearchOptions.evSearchOptions parameter:

val evSearchOptions = OfflineEvSearchOptions(
    connectorTypes = listOf(
        EvConnectorType.CHADEMO,
        EvConnectorType.IEC_62196_T2_COMBO,
        EvConnectorType.IEC_62196_T2,
    ),
    operators = getOperatorsList(),
    minChargingPower = 10000f, // Minimum power of 10 kW
    maxChargingPower = 50000f, // Maximum power of 50 kW
)

val options = OfflineSearchOptions.Builder()
    .evSearchOptions(evSearchOptions)
    .proximity(location)
    .build()

searchRequestTask = searchEngine.search(
    "charging station",
    options,
    searchCallback
)

The search response may include additional metadata, such as the charging station's operating hours, nearby facilities, detailed information about the station, and more.

fun processSearchResult(searchResult: OfflineSearchResult) {
    searchResult.metadata?.let { metadata ->
        val website = metadata.website
        val openHours = metadata.openHours
        val operatorName = metadata.evMetadata?.evLocation?.operatorDetails?.name
        // ...
    }
}

Refer to the documentation for the OfflineSearchResultMetadata and EvMetadata types for more details on the data they provide.

この{Type}は役に立ちましたか？

Need help? Visit the Support Center

Join our Mapbox Developer Discord

Check out the Developer Cheatsheet

Questions? Ask Mapbox Docs AI