# 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:

```kotlin
lifecycleScope.launch {
    RegionalOffline.fetchRegionList()
        .onSuccess { catalog ->
            renderCatalog(catalog)
        }
        .onFailure { throwable ->
            renderError(OfflineRegionError.from(throwable))
        }
}
```

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

```kotlin
lifecycleScope.launch {
    RegionalOffline.fetchRegionDetail(regionId)
        .onSuccess { result ->
            val detail = result.detail ?: return@onSuccess
            renderPackages(detail.packages)
        }
        .onFailure { throwable ->
            renderError(OfflineRegionError.from(throwable))
        }
}
```

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:

```kotlin
lifecycleScope.launch {
    RegionalOffline.queryRegions()
        .onSuccess { snapshot ->
            renderCatalog(snapshot.catalog)
            renderInstalled(snapshot.installed)
        }
        .onFailure { throwable ->
            renderError(OfflineRegionError.from(throwable))
        }
}
```

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.