Loading the Region Catalog

This page explains how to load and refresh the route-network and map-tile region catalogs before users choose required offline regions. Use cached data first, synchronize catalogs when needed, and handle partial catalog results from each subsystem.

Cache and TTL

syncRegions() synchronizes the road-network and map catalogs in parallel and applies the same cache policy to both. The default TTL is 24 hours. Each catalog atomically replaces its own cache, and a failed refresh does not delete the last successful result.

fetchRegionLists() reads only the local road-network and map caches without making a network request. To avoid leaving the region screen in a loading state, read and display the cache first, then run AUTO and read the caches again after synchronization. Keep the initial loading state only for a first installation with no cached catalog.

Cache-first Screen Implementation

1
private var catalogReadToken = 0L
2
fun loadRegionCatalog(force: Boolean) {
3
    readCachedRegions()
4
    val mode = if (force) RegionListSyncMode.FORCE else RegionListSyncMode.AUTO
5
    NBNavigation.syncRegions(
6
        mode,
7
        object : NBNavigationTaskCallback<OfflineRegionCatalogSyncResult> {
8
            override fun onSuccess(result: OfflineRegionCatalogSyncResult?) {
9
                readCachedRegions()
10
            }
11
            override fun onError(throwable: Throwable) {
12
                readCachedRegions()
13
                showCatalogRefreshWarning(throwable)
14
            }
15
        }
16
    )
17
}
18
private fun readCachedRegions() {
19
    val token = ++catalogReadToken
20
    NBNavigation.fetchRegionLists(
21
        "United States",
22
        object : NBNavigationTaskCallback<OfflineRegionListResult> {
23
            override fun onSuccess(result: OfflineRegionListResult?) {
24
                if (token != catalogReadToken || result == null) return
25
                showRegions(result.regionRows.filter { it.hasRoute && it.hasMap })
26
                result.routeError?.let(::showRouteCatalogWarning)
27
                result.mapError?.let(::showMapCatalogWarning)
28
            }
29
            override fun onError(throwable: Throwable) {
30
                if (token == catalogReadToken) {
31
                    showOfflineError("Loading cached regions failed", throwable)
32
                }
33
            }
34
        }
35
    )
36
}

OfflineRegionCatalogSyncResult contains synchronization details for both route and map catalogs. map.networkSkipped is true when AUTO uses a valid cached map catalog. A successful sync does not guarantee that downloadable regions exist. To verify, call fetchRegionLists() after synchronization to read the catalogs.

Country Filtering and Partial Results

The no-argument fetchRegionLists() overload queries United States by default. NBNavigation does not currently expose a public country-enumeration API. Obtain the supported full English country name from the deployment configuration, your product backend, or NextBillion.ai, then pass that exact value to fetchRegionLists(country, callback). Do not pass an ISO code, a localized name, or a whitespace-only string. Treat the country as product configuration rather than deriving it from the device locale.

OfflineRegionListResult may contain data from only the road-network or map side. Check routeError, mapError, hasRouteData, hasMapData, and regionRows together. Do not interpret an empty list after filtering on hasRoute and hasMap as proof that no data exists, because the screen can display whichever cache remains available.

Reading installed map regions on a cold start may access the disk. Use the asynchronous listInstalledMapTileRegions() API instead of reading Maps SDK storage directly on the main thread.

Region List Fields, Data Size, and Update Detection

After fetchRegionLists() succeeds, use result.regionRows as the primary screen model. It aligns route and map catalogs by regionId and preserves regions available from only one source. Filter on hasRoute && hasMap only when the product explicitly requires a complete offline-navigation package.

Result object OfflineRegionListResult

Read routeRegionList.listSyncedAtMs and mapRegionList.listSyncedAtMs for catalog freshness; updatedAtMs only timestamps this response. mapRegionList.listSyncStatus can be empty, ok, or failed. Do not infer synchronization success from total or an empty list alone without simultaneously inspecting routeError and mapError.

List item OfflineRegionListRow

Route item routeRegion and OfflineRegionLeaf

Map item mapRegion and MapTileRegionListItem

Calculate download size and available storage

For a first download, add non-null routeSizeBytes and mapSizeBytes to obtain the combined estimated compressed download size. This excludes extraction, database pages, temporary files, and filesystem overhead, so it is not the final on-disk size.

For a resumed download, when downloaded and total are available from observeOfflineProgress(), sum max(total - downloaded, 0) for both subtasks or else fall back to the full catalog estimate.

1
private fun estimatedBytes(row: OfflineRegionListRow): Long {
2
    val route = (row.routeSizeBytes ?: 0L).coerceAtLeast(0L)
3
    val map = (row.mapSizeBytes ?: 0L).coerceAtLeast(0L)
4
    return if (route > Long.MAX_VALUE - map) Long.MAX_VALUE else route + map
5
}
6

7
val text = Formatter.formatFileSize(context, estimatedBytes(row))

Recommended preflight: available bytes >= remaining download bytes + max(20% of remaining bytes, 100 MB). NBNavigation does not currently expose one combined storage-preflight result for route and map downloads, so the application should still use StatFs on the volume that contains the actual data directory. Check each volume separately if route and map data use different volumes. Insufficient storage can still surface through progress or callbacks as FAILED, FAILED_STORAGE, or a structured error.

1
val remaining = remainingBytes.coerceAtLeast(0L)
2
val reserve = maxOf(
3
    100L * 1024L * 1024L,
4
    (remaining * 0.20).roundToLong()
5
)
6
val required = if (remaining > Long.MAX_VALUE - reserve) Long.MAX_VALUE
7
               else remaining + reserve
8
val enoughSpace = StatFs(storageDir.absolutePath).availableBytes >= required