Fetch Regional Catalog

Retrieve the Online Catalog

The online regional catalog is the list of all the regions that the service can download. fetchRegionList() requires a network connection and can retrieve the online catalog:

1
lifecycleScope.launch {
2
    RegionalOffline.fetchRegionList()
3
        .onSuccess { catalog ->
4
            renderCatalog(catalog)
5
        }
6
        .onFailure { throwable ->
7
            renderError(OfflineRegionError.from(throwable))
8
        }
9
}

OfflineCatalogItem's commonly used fields:

Field	Purpose
`regionId`	Stable ID for subsequent queries, downloads, and task control
`name, adminL0, adminL1, adminL3`	Build the region-list hierarchy
`version`	Compare with the local regionVersion to detect updates
`totalSize`	Estimated compressed download size in bytes
`tileCount`	Estimated server-side tile count

totalSize and tileCount are server estimates. Actual disk usage may differ because of file formats, SQLite overhead, and file-system overhead.

Retrieve a Region’s details

Fetch region details before download to inspect the package list, size, and zoom range for the selected region.

1
lifecycleScope.launch {
2
    RegionalOffline.fetchRegionDetail(regionId)
3
        .onSuccess { result ->
4
            val detail = result.detail ?: return@onSuccess
5
            renderPackages(detail.packages)
6
        }
7
        .onFailure { throwable ->
8
            renderError(OfflineRegionError.from(throwable))
9
        }
10
}

Each OfflinePackageInfo provides tarName, tarSize, minZoom and maxZoom. A region consists of one or more pre-generated packages.

Query Online and Local State Together

Use queryRegions() when the download page needs a combined snapshot of the online catalog and the regions already installed on the device. The download page can use the following on initial load:

1
lifecycleScope.launch {
2
    RegionalOffline.queryRegions()
3
        .onSuccess { snapshot ->
4
            renderCatalog(snapshot.catalog)
5
            renderInstalled(snapshot.installed)
6
        }
7
        .onFailure { throwable ->
8
            renderError(OfflineRegionError.from(throwable))
9
        }
10
}

When the device is offline, queryRegions() still returns installed regions, while the catalog is empty. Keep the local list and mark regions from the online catalog as temporarily unavailable.