PowerMap iOS SDK

Step 1: Add SDK to Project

1. Download the PowerMapSDK.xcframework.zip file from: http://download.powermap.live/#sdks
2. Extract the .zip file to get the PowerMapSDK.xcframework folder
3. Drag the PowerMapSDK.xcframework file into your Xcode project
4. In General → Frameworks, Libraries, and Embedded Content, set it to Embed & Sign

Step 2: Configure API Key

Insert the initialize code into your AppDelegate or App struct:

import PowerMapSDK

@main
struct MyApp: App {
    init() {
        PowerMapSDK.shared.initialize(
            mapApiKey: "YOUR_MAP_API_KEY",
            clientId: "YOUR_CLIENT_ID",
            clientSecret: "YOUR_CLIENT_SECRET"
        )
    }
}

The PowerMap iOS SDK is built with a Layered Facade Architecture, ensuring that high-performance native rendering is wrapped in an easy-to-use Swift API.

graph TD
    App[iOS App] --> PowerMap[MLNMapView]
    PowerMap --> Controller[PowerMapController]
    
    subgraph "Facade Layer"
        Controller
    end

    subgraph "Manager Layer"
        Controller --> MarkerMgr[MarkerManager]
        Controller --> SearchMgr[SearchManager]
        Controller --> RouteMgr[RoutingManager]
        Controller --> GeomMgr[GeometryManager]
        Controller --> TrackingMgr[TrackingManager]
    end

    subgraph "Native Engine"
        PowerMap --> NativeEngine[High-Performance Metal Rendering]
    end

• Unified Facade: PowerMapController provides a single entry point for all features, matching the Web and Flutter DX.
• Native Rendering: Polygons, Lines, and Symbols are rendered via the native Metal rendering engine for fluid performance.
• Async/Await Native: Fully async APIs (search, addRoute, etc.) built natively with Swift 5.5 concurrency.

Get a map up and running in less than 2 minutes.

import UIKit
import PowerMapSDK

class MapViewController: UIViewController, MLNMapViewDelegate {
    var mapView: MLNMapView!
    var controller: PowerMapController!

    override func viewDidLoad() {
        super.viewDidLoad()
        
        mapView = MLNMapView(frame: view.bounds)
        mapView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(mapView)
        
        // 1. Initialize the Facade Controller
        controller = PowerMapController(mapView: mapView)
        
        // 2. Set Map Style
        controller.setStyle(.dark)
        
        // 3. Move Camera
        controller.moveCamera(target: CLLocationCoordinate2D(latitude: 13.7563, longitude: 100.5018), zoom: 14.0)
        
        // 4. Listen to events
        controller.onMapClick = { coord in
            print("Tapped at: \(coord)")
        }
    }
}

PowerMapView Initialization

Global Event Callbacks (on PowerMapController)

• onMapClick: ((CLLocationCoordinate2D) -> Void)?
• onMapLongClick: ((CLLocationCoordinate2D) -> Void)?
• onPoiTapped: ((MLNFeature) -> Void)?
• onMarkerTapped: ((MLNAnnotation) -> Void)?
• onCameraMove: ((CLLocationCoordinate2D) -> Void)?
• onCameraIdle: (() -> Void)?
• onError: ((Error) -> Void)?

Direct viewport manipulation matching the Android SDK.

Movement Methods

State Properties

controller.moveCamera(
    target: CLLocationCoordinate2D(latitude: 13.7649, longitude: 100.5383),
    zoom: 17.0,
    tilt: 60.0,
    bearing: 90.0
)

// Zoom to fit a route
controller.fitRouteBounds(routeCoordinates, paddingPx: 80, durationMs: 600)

Core Marker Methods

High Performance GL Markers

Best for large datasets. Rendered directly by the GPU via Metal.

let marker = controller.markers.addMarker(
    position: CLLocationCoordinate2D(latitude: 13.76, longitude: 100.50),
    color: "#f97316"
)

controller.onMarkerTapped = { annotation in
    print("Marker tapped!")
}

Calculate logistics-grade paths. Automatically draws the route polyline on the map.

addRoute() Options

Task {
    let route = try await controller.addRoute(
        start: CLLocationCoordinate2D(latitude: 13.7468, longitude: 100.5346),
        destination: CLLocationCoordinate2D(latitude: 13.7649, longitude: 100.5383),
        optimize: true
    )
    print("Route calculated: \(route?.distanceStr ?? "")")
}

A full-featured navigation engine with 60 FPS simulation, TTS voice guidance, GPS snap-to-route, automatic rerouting, and real-time state publishing.

Quick Start

import SwiftUI
import PowerMapSDK

struct MapView: View {
    @StateObject var navigator = PowerMapNavigator()
    var controller: PowerMapController?

    var body: some View {
        // ...
        .onReceive(navigator.$state) { state in
            guard let state else { return }
            print("Turn in: \(Int(state.distanceToNextManeuver))m")
            print("Progress: \(Int(state.progress * 100))%")
            print("Instruction: \(state.currentInstruction ?? "")")
        }
        .task {
            navigator.setController(controller)
            if let route = try? await controller?.routing.addRoute(
                start: CLLocationCoordinate2D(latitude: 13.7468, longitude: 100.5346),
                destination: CLLocationCoordinate2D(latitude: 13.7649, longitude: 100.5383)
            ) {
                navigator.startNavigation(route: route, mode: .simulation)
            }
        }
    }
}

Navigation Mode

Playback Controls

// Pause / Resume
navigator.pauseSimulation()
navigator.resumeSimulation()

// Speed multiplier (1x, 2x, 3x, 5x recommended)
navigator.setSpeedMultiplier(3)

// Follow vehicle (unlock/re-lock camera)
navigator.followVehicle = false  // Free-roam camera
navigator.followVehicle = true   // Re-lock

// Stop navigation
navigator.stopNavigation()

Vehicle Arrow Customization

// By UIColor
controller.setVehicleColor(UIColor.systemBlue)

// By hex string
controller.setVehicleColor("#4285F4")

NavigationState Fields

Observe via navigator.$state (Combine @Published):

@Published Properties (SwiftUI / Combine)

The SDK features a robust GeometryManager that natively handles GeoJSON Polygon, LineString, or Point types.

// 1. Prepare your Geometry Data (GeoJSON format: Lng, Lat)
let geofenceData: [String: Any] = [
    "type": "Feature",
    "geometry": [
        "type": "Polygon",
        "coordinates": [[
            [100.534, 13.746], [100.538, 13.746], 
            [100.538, 13.749], [100.534, 13.749], 
            [100.534, 13.746] // Must close the loop
        ]]
    ]
]

// 2. Inject Data into the Map Source
controller.geometry.addGeoJson(sourceId: "my-geofence", geoJson: geofenceData)

// 3. Apply Visual Styles to that Source ID
controller.geometry.addPolygonLayer(
    sourceId: "my-geofence",
    fillColor: .blue, 
    fillOpacity: 0.5
)

Safe, async/await driven Geocoding with debouncing and LRU Caching (50 items) built-in.

Search Methods

Language Detection (lang Parameter)

// 1. Debounced Autocomplete
controller.autocompleteDebounced(query: query, delay: 0.5, lang: "th") { results in
    if let first = results.first {
        print("Found: \(first.name)")
    }
}

// 2. One-shot forward search
Task {
    let results = try await controller.search(query: "Central World", lang: "en")
    print("Found: \(results.first?.name ?? "")")
}

// 3. Reverse Geocode (Lat/Lng to Address)
Task {
    if let address = await controller.reverseGeocode(location: CLLocationCoordinate2D(latitude: 14.2558, longitude: 100.9810)) {
        print("Address: \(address.name)")
    }
}

// 4. Category Search (Nearby POIs by type)
Task {
    if let myLocation = await controller.getCurrentLocation() {
        let restaurants = try await controller.searchByCategory(
            categoryId: "2100",
            location: myLocation,
            dist: 5
        )
        print("Found \(restaurants.count) nearby restaurants!")
    }
}

Category IDs Reference

Highly integrated with CoreLocation for battery-efficient GPS positioning.

Core Methods

Task {
    // 1. One-shot: Get current coordinates
    let myLocation = await controller.getCurrentLocation()

    // 2. Navigation mode with compass heading (3D view)
    await controller.enableFollowModeWithCompass()

    // 3. Stop tracking later
    controller.disableFollowMode()
}

@main
struct MyApp: App {
    @Environment(\.scenePhase) private var scenePhase
    @StateObject private var mapViewModel = MapViewModel()

    var body: some Scene {
        WindowGroup {
            ContentView().environmentObject(mapViewModel)
        }
        .onChange(of: scenePhase) { phase in
            if phase == .background || phase == .inactive {
                mapViewModel.controller?.disposeTracking()
            }
        }
    }
}

The SDK exposes a unified PowerMapError enum that conforms to LocalizedError, providing consistent error codes across iOS, Android, and Flutter platforms.

Error Cases

Standard Error Code Constants

PowerMapError.NETWORK         // "NETWORK_ERROR"
PowerMapError.AUTH            // "AUTH_FAILED"
PowerMapError.INVALID_REQUEST // "INVALID_REQUEST"
PowerMapError.NOT_FOUND       // "NOT_FOUND"
PowerMapError.STYLE_LOAD      // "STYLE_LOAD_FAILED"
PowerMapError.MAP_INTERNAL    // "MAP_INTERNAL_ERROR"
PowerMapError.ROUTE_NOT_FOUND // "ROUTE_NOT_FOUND"
PowerMapError.SERVER_ERROR    // "SERVER_ERROR"

Global Error Callback

controller.onError = { error in
    guard let mapError = error as? PowerMapError else { return }

    switch mapError {
    case .notInitialized(let msg):
        print("SDK not ready: \(msg)")
    case .network(let msg, let underlying):
        print("Network error: \(msg)")
    case .auth(let msg):
        print("Authentication failed: \(msg)")
    case .serverError(let msg, let code):
        print("Server error \(code): \(msg)")
    case .routeNotFound:
        print("No route available.")
    case .invalidRequest(let msg):
        print("Bad request: \(msg)")
    case .styleLoadFailed(let msg):
        print("Style failed to load: \(msg)")
    case .mapInternal(let msg):
        print("Internal map error: \(msg)")
    }
}

Inline try/catch for Async APIs

Task {
    do {
        let route = try await controller.addRoute(
            start: CLLocationCoordinate2D(latitude: 13.7468, longitude: 100.5346),
            destination: CLLocationCoordinate2D(latitude: 13.7649, longitude: 100.5383)
        )
        print("Route: \(route?.distanceStr ?? "")")
    } catch PowerMapError.routeNotFound {
        print("No route found — try different waypoints.")
    } catch PowerMapError.network(let msg, _) {
        print("Network issue: \(msg)")
    } catch {
        print("Unexpected error: \(error.localizedDescription)")
    }
}

Browse the generated DocC documentation for a comprehensive API surface. Start with PowerMapView and PowerMapController as your primary integration points.

© 2026 PowerMap Development Team. All rights reserved.