Fetch Regional Catalog

Regional Catalog is a service metadata index listing available offline map regions and its details, serving as a resource to discover downloadable regions. This section deals with fetching the online region catalog, combining catalog data with local installation state, and fetching package details before starting a regional map download.

Fetch the regional catalog

1
NGLRegionalOffline.fetchRegionList {
2
    [weak self] items, error in
3
    guard let self else { return }
4
 
5
    if let error {
6
        handleRegionalOfflineError(error)
7
        return
8
    }
9
 
10
    let regions = items ?? []
11
    catalog = regions
12
 
13
    for region in regions {
14
        print(
15
            "region=\(region.regionId) " +
16
            "name=\(region.name) " +
17
            "version=\(region.version ?? "-") " +
18
            "size=\(region.totalSize)"
19
        )
20
    }
21
}

The region catalog commonly has the following fields:

Field	Description
`regionId`	Unique region identifier used by download and management APIs
`name`	Display name
`adminL0/adminL1/adminL3`	Administrative hierarchy
`version`	Server-side region version, suitable for update detection
`timestamp`	Server-side resource timestamp
`totalSize`	Estimated download size in bytes
`tileCount`	Number of tiles in the region

Query the online catalog and local installations together

Execute queryRegions whenever the user interface requires both current catalog listings and regional installation statuses. Should the client lack network connectivity, the remote catalog returns empty results while locally stored regions remain accessible.

1
NGLRegionalOffline.queryRegions { snapshot, error in
2
    if let error {
3
        self.handleRegionalOfflineError(error)
4
        return
5
    }
6
 
7
    let catalog = snapshot?.catalog ?? []
8
    let installed = snapshot?.installed ?? []
9
    let previewResourcesAreReady = snapshot?.ambientReady ?? false
10
 
11
    // Update the user interface.
12
}

When the device is offline, the online catalog may be empty, but locally installed regions remain available.

Fetch region details

1
NGLRegionalOffline.fetchRegionDetail(forRegionId: regionId) {
2
    detail, detailJSON, error in
3
    if let error {
4
        self.handleRegionalOfflineError(error)
5
        return
6
    }
7
 
8
    for package in detail?.tarList ?? [] {
9
        print(
10
            "package=\(package.tarName) " +
11
            "version=\(package.version) " +
12
            "size=\(package.tarSize)"
13
        )
14
    }
15
}