Getting Started with Offline Pack API - Swift SDK

The MapTiler SDK for iOS provides a powerful Offline Pack API that allows you to download map regions for use without an active internet connection. This is essential for applications used in remote areas or to reduce data consumption.

Before you begin, ensure you have followed the iOS SDK Getting Started guide to set up your project and obtain your API key.

Installation

Ensure you have the MapTilerSDK added to your project via Swift Package Manager.

View Installation Instructions

Basic usage

Downloading an offline map involves four simple steps: defining the region, creating a pack, setting up a delegate, and starting the download.

Step 1: define the region

Use MTOfflineRegionDefinition to specify the area, zoom levels, and map style you want to download.

import MapTilerSDK

// Define a bounding box (e.g., Zurich area)
let bbox = MTBoundingBox(
    minLon: 8.52, minLat: 47.36,
    maxLon: 8.56, maxLat: 47.39
)

// Create the definition
let definition = MTOfflineRegionDefinition(
    geometry: .boundingBox(bbox),
    minZoom: 1,
    maxZoom: 12,
    referenceStyle: .streets
)

Step 2: create the offline pack

Create the pack instance which manages the storage and metadata on disk.

Task {
    do {
        let pack = try await MTOfflinePack.createPack(region: definition)
        // Store the pack ID or the pack instance for later use
    } catch {
        print("Failed to create pack: \(error)")
    }
}

Step 3: observe download progress

Implement the MTOfflineDownloadDelegate to track the state and progress of your download.

class MapDownloadManager: MTOfflineDownloadDelegate {
    func offlinePack(_ packId: String, didChangeState state: MTOfflinePackState) {
        print("Pack \(packId) changed state to: \(state)")
    }

    func offlinePack(_ packId: String, didUpdateProgress progress: MTOfflinePackProgress) {
        print("Download progress: \(progress.percentage * 100)%")
    }
}

// ... in your setup code ...
let manager = MapDownloadManager()
await pack.setDelegate(manager)
await pack.setProgressReportingEnabled(true)

Step 4: start the download

You can start the download in the foreground or background. Background downloads continue even if the app is suspended.

try await pack.download(useBackground: true)

Features

Flexible Geometries

Offline regions aren’t limited to rectangles. You can define regions based on:

• Bounding Box: A simple rectangular area.
• Route: Download tiles along a GeoJSON route with a specific buffer.
• Polygon: Download tiles within a custom polygon boundary.

Background Downloading

By setting useBackground: true, the SDK leverages iOS URLSession background transfers, ensuring your maps keep downloading while the user is away from the app.

Pack Management

Easily manage your stored maps:

• List Packs: await MTOfflinePack.packs()
• Resume/Pause: await pack.resume() or await pack.pause()
• Remove: await pack.remove()

What to Expect

Storage: Map tiles are stored in a dedicated folder. A typical city-sized area at zoom level 12 might take 50-100MB depending on the style complexity.

Expiration: Packs have an expiration date (default is 30 days). You can use pack.refresh() to update the resources and reset the timer.

Network: The SDK automatically handles intermittent connectivity, pausing and resuming downloads as the network becomes available.

Learn more

For more information browse our API Reference, or build your own documentation in Xcode: Product -> Build Documentation.

Check out our SDK Swift Examples. In addition to the documentation examples take a look at the plug and play examples provided in the SDK GitHub repository, as well as pre-made demo app: maptiler-sdk-swift/Examples