Loading the Region Catalog

After initialization, synchronize the routing catalog and read the combined region list. The combined list contains routing catalog entries, map catalog entries, and installed map packages by regionId.

Sync and read the region list

1
@MainActor
2
func reloadRegions() async throws {
3
    _ = try await NBNavigation.syncOfflineRegionList(syncMode: .auto)
4

5
    // nil or an empty array returns every country.
6
   let result = await NBNavigation.fetchRegionLists()
7
rows = result.regionRows
8

9
    if let routeError = result.routeError {
10
        showComponentWarning("Routing catalog: \(routeError)")
11
    }
12
    if let mapError = result.mapError {
13
        showComponentWarning("Map catalog: \(mapError)")
14
    }
15
    if let installedError = result.mapInstalledError {
16
        showComponentWarning("Installed maps: \(installedError)")
17
    }
18
}

Note that syncOfflineRegionList(syncMode: .auto) uses the cache freshness policy. For an explicit user refresh use .force. Also, fetchRegionLists does not synchronize catalogs and it does not fail the entire request when one component fails. Instead, it reports component errors through routeError, mapError, and mapInstalledError, so the screen can display content that loaded successfully.

Catalog API comparison

Region List Item Fields

fetchRegionLists returns regionRows merged by regionId from the routing catalog, the map catalog, and locally installed map packages. Optional values in a row may be “nil”, so evaluate each dataset independently. A missing component object does not by itself mean that downloaded data was lost.

Useful Nested Fields

The following fields cover the common status, version, and diagnostic needs of an offline-region management screen.

Checking Size Download State and Updates

Refresh the catalogs through the normal screen flow before reading regionRows. The following example evaluates installed and update states separately and shows a combined size only when at least one size is known:

1
import Foundation
2

3
_ = try await NBNavigation.syncOfflineRegionList(syncMode: .auto)
4
let result = await NBNavigation.fetchRegionLists()
5

6
let formatter = ByteCountFormatter()
7
formatter.countStyle = .file
8

9
for row in result.regionRows {
10
    let knownBytes = [row.routeSizeBytes, row.mapSizeBytes]
11
        .compactMap { $0 }
12
        .reduce(0, +)
13
    let hasKnownSize = row.routeSizeBytes != nil || row.mapSizeBytes != nil
14
    let packageSizeText = hasKnownSize
15
        ? formatter.string(fromByteCount: knownBytes)
16
        : "--"
17

18
    let routingDownloaded = row.routeRegion?.isDownloaded == true
19
    let mapInstalled = row.mapInstalledRegion != nil
20
    let mapPackagesReady = row.mapInstalledRegion?.allPackagesOk == true
21

22
    let routingUpdateAvailable = row.routeRegion?.updateAvailable == true
23
    let mapUpdateAvailable = row.mapRegion?.updateAvailable == true
24
    let anyUpdateAvailable = routingUpdateAvailable || mapUpdateAvailable
25

26
    // Render row.displayName, packageSizeText, installed state,
27
    // and anyUpdateAvailable in the region list UI.
28
}

• Size fields: routeSizeBytes and mapSizeBytes are suitable for pre-download estimates. During a download, read downloaded, total, and percent from observeOfflineRegionProgress or observeUnifiedOfflineProgress.
• Update fields: fetchRegionLists reads the current catalog snapshot and does not synchronize it. To check for the latest update, refresh the catalogs first, then read routeRegion.updateAvailable and mapRegion.updateAvailable.
• Partial failure: regionRows may still contain data from another component when routeError, mapError, or mapInstalledError is set. Display the available content and offer retry for the failed component.

Result Level Fields

Offline Download Screen Lifecycle

Pair the screen ownership calls:

1
override func viewWillAppear(_ animated: Bool) {
2
    super.viewWillAppear(animated)
3
    NBNavigation.beginDownloadPageWithOwner(self)
4
    NBNavigation.onOfflineMapViewWillAppear()
5
    NBNavigation.registerOfflineMapStyle(
6
        mapView: previewMapView,
7
        styleURL: previewMapView.styleURL
8
    )
9
}
10

11
override func viewDidDisappear(_ animated: Bool) {
12
    super.viewDidDisappear(animated)
13
    NBNavigation.endDownloadPage()
14
}

endDownloadPage releases screen ownership but does not cancel region downloads that have already started.