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

Once TileStore instance is initialized, you can create OfflineSearchEngine:

val searchEngine = OfflineSearchEngine.create(
OfflineSearchEngineSettings(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.
  • POI (Point of Interest): Locations such as cafes, charging stations, etc.
  • Place: Typically these are cities, villages, municipalities, etc.

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

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

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.

Was this page helpful?