Mapkit

MapKit

Build map-based and location-aware features targeting iOS 17+ with SwiftUI MapKit and modern CoreLocation async APIs. Use Map with MapContentBuilder for views, CLLocationUpdate.liveUpdates() for streaming location, and CLMonitor for geofencing.

Read references/mapkit-patterns.md when you need full map setup, search, routes, Look Around, snapshots, or iOS 26 place APIs. Read references/mapkit-corelocation-patterns.md when the task involves location update lifecycle, geofencing, background location, testing, or privacy keys.

Contents

• Workflow
• SwiftUI Map View (iOS 17+)
• CoreLocation Modern API
• Geocoding
• Search
• Directions
• PlaceDescriptor (iOS 26+)
• Common Mistakes
• Review Checklist
• References

Workflow

1. Add a map with markers or annotations

1. Import MapKit. 2. Create a Map view with optional MapCameraPosition binding. 3. Add Marker, Annotation, MapPolyline, MapPolygon, or MapCircle inside the MapContentBuilder closure. 4. Configure map style with .mapStyle(). 5. Add map controls with .mapControls { }. 6. Handle selection with a selection: binding.

2. Track user location

1. Add NSLocationWhenInUseUsageDescription to Info.plist. 2. On iOS 18+, create a CLServiceSession to manage authorization. 3. Iterate CLLocationUpdate.liveUpdates() in a Task. 4. Filter updates by distance or accuracy before updating the UI. 5. Stop the task when location tracking is no longer needed.

3. Search for places

1. Configure MKLocalSearchCompleter for autocomplete suggestions. 2. Debounce user input (at least 300ms) before setting the query. 3. Convert selected completion to MKLocalSearch.Request for full results. 4. Display results as markers or in a list.

4. Get directions and display a route

1. Create an MKDirections.Request with source and destination MKMapItem. 2. Set transportType (.automobile, .walking, .transit, .cycling). 3. Await MKDirections.calculate(). 4. Draw the route with MapPolyline(route.polyline).

5. Review existing map/location code

Run through the Review Checklist at the end of this file.

SwiftUI Map View (iOS 17+)

import MapKit
import SwiftUI

struct PlaceMap: View {
    @State private var position: MapCameraPosition = .automatic

    var body: some View {
        Map(position: $position) {
            Marker("Apple Park", coordinate: applePark)
            Marker("Infinite Loop", systemImage: "building.2",
                   coordinate: infiniteLoop)
        }
        .mapStyle(.standard(elevation: .realistic))
        .mapControls {
            MapUserLocationButton()
            MapCompass()
            MapScaleView()
        }
    }
}

Marker and Annotation

// Balloon marker -- simplest way to pin a location
Marker("Cafe", systemImage: "cup.and.saucer.fill", coordinate: cafeCoord)
    .tint(.brown)

// Annotation -- custom SwiftUI view at a coordinate
Annotation("You", coordinate: userCoord, anchor: .bottom) {
    Image(systemName: "figure.wave")
        .padding(6)
        .background(.blue.gradient, in: .circle)
        .foregroundStyle(.white)
}

Overlays: Polyline, Polygon, Circle

Map {
    // Polyline from coordinates
    MapPolyline(coordinates: routeCoords)
        .stroke(.blue, lineWidth: 4)

    // Polygon (area highlight)
    MapPolygon(coordinates: parkBoundary)
        .foregroundStyle(.green.opacity(0.3))
        .stroke(.green, lineWidth: 2)

    // Circle (radius around a point)
    MapCircle(center: storeCoord, radius: 500)
        .foregroundStyle(.red.opacity(0.15))
        .stroke(.red, lineWidth: 1)
}

Camera Position

MapCameraPosition controls what the map displays. Bind it to let the user interact and to programmatically move the camera.

// Center on a region
@State private var position: MapCameraPosition = .region(
    MKCoordinateRegion(
        center: CLLocationCoordinate2D(latitude: 37.334, longitude: -122.009),
        span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05)
    )
)

// Follow user location
@State private var position: MapCameraPosition = .userLocation(fallback: .automatic)

// Specific camera angle (3D perspective)
@State private var position: MapCameraPosition = .camera(
    MapCamera(centerCoordinate: applePark, distance: 1000, heading: 90, pitch: 60)
)

// Frame specific items
position = .item(MKMapItem.forCurrentLocation())
position = .rect(MKMapRect(...))

Map Style

.mapStyle(.standard)                                        // Default road map
.mapStyle(.standard(elevation: .realistic, showsTraffic: true))
.mapStyle(.imagery)                                         // Satellite
.mapStyle(.imagery(elevation: .realistic))                  // 3D satellite
.mapStyle(.hybrid)                                          // Satellite + labels
.mapStyle(.hybrid(elevation: .realistic, showsTraffic: true))

Map Interaction Modes

.mapInteractionModes(.all)           // Default: pan, zoom, rotate, pitch
.mapInteractionModes(.pan)           // Pan only
.mapInteractionModes([.pan, .zoom])  // Pan and zoom
.mapInteractionModes([])             // Static map (no interaction)

Map Selection

@State private var selectedMarker: MKMapItem?

Map(selection: $selectedMarker) {
    ForEach(places) { place in
        Marker(place.name, coordinate: place.coordinate)
            .tag(place.mapItem)     // Tag must match selection type
    }
}
.onChange(of: selectedMarker) { _, newValue in
    guard let item = newValue else { return }
    // React to selection
}

CoreLocation Modern API

CLLocationUpdate.liveUpdates() (iOS 17+)

Replace CLLocationManagerDelegate callbacks with a single async sequence. Each iteration yields a CLLocationUpdate containing an optional CLLocation. On iOS 18+, handle diagnostic states such as denied authorization, globally disabled Location Services, unavailable location, and insufficient in-use conditions with a visible degraded path instead of silently waiting forever. Store the task so the feature can cancel it, and reject invalid, inaccurate, stale, or unusable movement data before driving map UI or background work.

import CoreLocation

@MainActor
@Observable
final class LocationTracker {
    var currentLocation: CLLocation?
    private var updateTask: Task<Void, Never>?

    func startTracking() {
        updateTask = Task {
            do {
                let updates = CLLocationUpdate.liveUpdates()
                for try await update in updates {
                    guard let location = update.location else { continue }
                    // Filter by horizontal accuracy
                    guard location.horizontalAccuracy >= 0,
                          location.horizontalAccuracy < 50 else { continue }
                    currentLocation = location
                }
            } catch is CancellationError {
                // Expected when tracking stops.
            } catch {
                currentLocation = nil
            }
        }
    }

    func stopTracking() {
        updateTask?.cancel()
        updateTask = nil
    }
}

CLServiceSession (iOS 18+)

Declare authorization requirements for a feature's lifetime. Hold a reference to the session for as long as you need location services.

// When-in-use authorization with full accuracy preference
let session = CLServiceSession(
    authorization: .whenInUse,
    fullAccuracyPurposeKey: "NearbySearchPurpose"
)
// Hold `session` as a stored property; release it when done.

On iOS 18+, CLLocationUpdate.liveUpdates() and CLMonitor take an implicit CLServiceSession if you do not create one explicitly. Create one explicitly when you need .always authorization or full accuracy.

Authorization Flow

// Info.plist keys (required):
// NSLocationWhenInUseUsageDescription
// NSLocationAlwaysAndWhenInUseUsageDescription (only if .always needed)

// Check authorization and guide user to Settings when denied
struct LocationPermissionView: View {
    @Environment(\.openURL) private var openURL

    var body: some View {
        ContentUnavailableView {
            Label("Location Access Denied", systemImage: "location.slash")
        } description: {
            Text("Enable location access in Settings to use this feature.")
        } actions: {
            Button("Open Settings") {
                if let url = URL(string: UIApplication.openSettingsURLString) {
                    openURL(url)
                }
            }
        }
    }
}

Geocoding

CLGeocoder (iOS 8+)

let geocoder = CLGeocoder()

// Forward geocoding: address string -> coordinates
let placemarks = try await geocoder.geocodeAddressString("1 Apple Park Way, Cupertino")
if let location = placemarks.first?.location {
    print(location.coordinate) // CLLocationCoordinate2D
}

// Reverse geocoding: coordinates -> placemark
let location = CLLocation(latitude: 37.3349, longitude: -122.0090)
let placemarks = try await geocoder.reverseGeocodeLocation(location)
if let placemark = placemarks.first {
    let address = [placemark.name, placemark.locality, placemark.administrativeArea]
        .compactMap { $0 }
        .joined(separator: ", ")
}

MKGeocodingRequest and MKReverseGeocodingRequest (iOS 26+)

New MapKit-native geocoding that returns MKMapItem with richer data and MKAddress / MKAddressRepresentations for flexible address formatting.

@available(iOS 26, *)
func reverseGeocode(location: CLLocation) async throws -> MKMapItem? {
    guard let request = MKReverseGeocodingRequest(location: location) else {
        return nil
    }
    let mapItems = try await request.mapItems
    return mapItems.first
}

@available(iOS 26, *)
func forwardGeocode(address: String) async throws -> [MKMapItem] {
    guard let request = MKGeocodingRequest(addressString: address) else { return [] }
    return try await request.mapItems
}

Search

MKLocalSearchCompleter (Autocomplete)

@Observable
final class SearchCompleter: NSObject, MKLocalSearchCompleterDelegate {
    var results: [MKLocalSearchCompletion] = []
    var query: String = "" { didSet { completer.queryFragment = query } }

    private let completer = MKLocalSearchCompleter()

    override init() {
        super.init()
        completer.delegate = self
        completer.resultTypes = [.address, .pointOfInterest]
    }

    func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
        results = completer.results
    }

    func completer(_ completer: MKLocalSearchCompleter, didFailWithError error: Error) {
        results = []
    }
}

MKLocalSearch (Full Search)

func search(for completion: MKLocalSearchCompletion) async throws -> [MKMapItem] {
    let request = MKLocalSearch.Request(completion: completion)
    request.resultTypes = [.pointOfInterest, .address]
    let search = MKLocalSearch(request: request)
    let response = try await search.start()
    return response.mapItems
}

// Search by natural language query within a region
func searchNearby(query: String, region: MKCoordinateRegion) async throws -> [MKMapItem] {
    let request = MKLocalSearch.Request()
    request.naturalLanguageQuery = query
    request.region = region
    let search = MKLocalSearch(request: request)
    let response = try await search.start()
    return response.mapItems
}

Directions

func getDirections(from source: MKMapItem, to destination: MKMapItem,
                   transport: MKDirectionsTransportType = .automobile) async throws -> MKRoute? {
    let request = MKDirections.Request()
    request.source = source
    request.destination = destination
    request.transportType = transport
    let directions = MKDirections(request: request)
    let response = try await directions.calculate()
    return response.routes.first
}

Display Route on Map

@State private var route: MKRoute?

Map {
    if let route {
        MapPolyline(route.polyline)
            .stroke(.blue, lineWidth: 5)
    }
    Marker("Start", coordinate: startCoord)
    Marker("End", coordinate: endCoord)
}
.task {
    route = try? await getDirections(from: startItem, to: endItem)
}

ETA Calculation

func getETA(from source: MKMapItem, to destination: MKMapItem) async throws -> TimeInterval {
    let request = MKDirections.Request()
    request.source = source
    request.destination = destination
    let directions = MKDirections(request: request)
    let response = try await directions.calculateETA()
    return response.expectedTravelTime
}

Cycling Directions (iOS 14+)

func getCyclingDirections(to destination: MKMapItem) async throws -> MKRoute? {
    let request = MKDirections.Request()
    request.source = MKMapItem.forCurrentLocation()
    request.destination = destination
    request.transportType = .cycling
    let directions = MKDirections(request: request)
    let response = try await directions.calculate()
    return response.routes.first
}

PlaceDescriptor (iOS 26+)

Create rich place references from coordinates or addresses without needing a Place ID. Requires import GeoToolbox.

import GeoToolbox

@available(iOS 26, *)
func lookupPlace(name: String, coordinate: CLLocationCoordinate2D) async throws -> MKMapItem {
    let descriptor = PlaceDescriptor(
        representations: [.coordinate(coordinate)],
        commonName: name
    )
    let request = MKMapItemRequest(placeDescriptor: descriptor)
    return try await request.mapItem
}

Common Mistakes

DON'T: Request always authorization upfront. DO: Start with when-in-use authorization. On iOS 18+, hold a CLServiceSession for the feature lifetime; request .always only for background features that need system relaunch after termination.

DON'T: Use CLLocationManagerDelegate for simple location fetches on iOS 17+. DO: Use CLLocationUpdate.liveUpdates() async stream for cleaner, more concise code.

DON'T: Ignore CLLocationUpdate diagnostics such as denied, globally denied, or unavailable location. DO: Stop or degrade the feature, show recovery UI such as Settings guidance, and keep search/manual flows usable.

DON'T: Let liveUpdates() run from an unowned task after the map/view is gone. DO: Store the Task, cancel it when the feature stops, and filter invalid, inaccurate, stale, or impossible movement fixes.

DON'T: Force-unwrap CLPlacemark properties — they are all optional. DO: Use nil-coalescing: placemark.locality ?? "Unknown".

DON'T: Fire MKLocalSearchCompleter queries on every keystroke. DO: Debounce with .task(id: searchText) + Task.sleep(for: .milliseconds(300)).

DON'T: Silently fail when location authorization is denied. DO: Detect .denied status and show an alert with a Settings deep link.

DON'T: Assume geocoding always succeeds — handle empty results and network errors.

Review Checklist

• [ ] Info.plist has NSLocationWhenInUseUsageDescription with specific reason
• [ ] Authorization denial handled with Settings deep link
• [ ] CLLocationUpdate task cancelled when not needed (battery)
• [ ] Location accuracy appropriate for the use case
• [ ] Map annotations use Identifiable data with stable IDs
• [ ] Geocoding errors handled (network failure, no results)
• [ ] Search completer input debounced
• [ ] CLMonitor limited to 20 conditions, instance kept alive
• [ ] Background location uses CLBackgroundActivitySession
• [ ] Map tested with VoiceOver
• [ ] Map annotation view models and location UI updates are @MainActor-isolated

References

• references/mapkit-patterns.md — Map setup, annotations, search, routes, clustering, Look Around, snapshots.
• references/mapkit-corelocation-patterns.md — CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.

CoreLocation Patterns Reference

Extended patterns for CoreLocation on iOS 17+ with modern Swift concurrency. Import CoreLocation in every file that uses these APIs.

import CoreLocation

---

Contents

• CLLocationUpdate.liveUpdates() (iOS 17+)
• CLServiceSession (iOS 18+)
• CLMonitor for Geofencing (iOS 17+)
• CLBackgroundActivitySession
• Significant Location Change Monitoring
• Visit Monitoring
• Region Monitoring Migration (CLCircularRegion to CLMonitor)
• Location Accuracy Management
• Testing Location in Simulator
• Privacy and Info.plist Keys
• Common Pitfalls
• References

CLLocationUpdate.liveUpdates() (iOS 17+)

Basic Usage

func startReceivingLocation() async {
    for try await update in CLLocationUpdate.liveUpdates() {
        guard let location = update.location else { continue }
        print("Lat: \(location.coordinate.latitude), Lon: \(location.coordinate.longitude)")
        print("Accuracy: \(location.horizontalAccuracy)m")
    }
}

Full Implementation with Filtering

Filter out stale, inaccurate, or duplicate updates to avoid unnecessary UI refreshes and reduce battery impact.

@MainActor
@Observable
final class LocationService {
    var currentLocation: CLLocation?
    var isTracking = false

    private var trackingTask: Task<Void, Never>?
    private var lastReportedLocation: CLLocation?

    /// Minimum distance in meters between reported locations.
    private let distanceFilter: CLLocationDistance = 10
    /// Maximum acceptable horizontal accuracy in meters.
    private let accuracyThreshold: CLLocationAccuracy = 100
    /// Maximum acceptable age for a delivered location.
    private let maximumLocationAge: TimeInterval = 15

    func startTracking() {
        guard !isTracking else { return }
        isTracking = true

        trackingTask = Task {
            do {
                let updates = CLLocationUpdate.liveUpdates(.default)

                for try await update in updates {
                    if Task.isCancelled { break }

                    // Skip updates without a location
                    guard let location = update.location else { continue }

                    // Skip inaccurate readings
                    guard location.horizontalAccuracy >= 0,
                          location.horizontalAccuracy < accuracyThreshold else {
                        continue
                    }

                    // Skip stale readings
                    guard abs(location.timestamp.timeIntervalSinceNow) < maximumLocationAge else {
                        continue
                    }

                    // Skip impossible movement when speed/course are available
                    if location.speed >= 0, location.speed > 80 {
                        continue
                    }
                    if location.course >= 0, location.courseAccuracy < 0 {
                        continue
                    }

                    // Skip if the user has not moved enough
                    if let last = lastReportedLocation,
                       location.distance(from: last) < distanceFilter {
                        continue
                    }

                    lastReportedLocation = location
                    currentLocation = location
                }
            } catch is CancellationError {
                // Expected when tracking stops.
            } catch {
                currentLocation = nil
            }

            isTracking = false
        }
    }

    func stopTracking() {
        trackingTask?.cancel()
        trackingTask = nil
        isTracking = false
    }
}

LiveConfiguration Options

CLLocationUpdate.liveUpdates(_:) accepts a LiveConfiguration parameter:

// Default: balanced power and accuracy
CLLocationUpdate.liveUpdates(.default)

// Best for navigation: highest accuracy, most frequent updates
CLLocationUpdate.liveUpdates(.automotiveNavigation)

// Fitness tracking
CLLocationUpdate.liveUpdates(.fitness)

// Other-navigation (non-automotive)
CLLocationUpdate.liveUpdates(.otherNavigation)

// Airborne: for drone or aviation apps
CLLocationUpdate.liveUpdates(.airborne)

Handling Diagnostics and Degraded Behavior (iOS 18+)

Keep every liveUpdates() stream in an owned Task so the feature can cancel it when the map, route, or monitoring workflow stops. Treat diagnostics and bad location samples as state changes: update UI, fall back to cached/manual input, or suspend background work instead of continuing an invisible loop.

for try await update in CLLocationUpdate.liveUpdates() {
    // Check authorization status (iOS 18+)
    if update.authorizationDenied {
        // User denied location; prompt to open Settings
        break
    }

    if update.authorizationDeniedGlobally {
        // Location Services disabled system-wide
        break
    }

    if update.insufficientlyInUse {
        // App does not meet in-use requirements
        continue
    }

    if update.locationUnavailable {
        // Temporarily unable to determine location; keep iterating
        continue
    }

    if update.stationary {
        // Device stopped moving; updates will pause
        continue
    }

    guard let location = update.location else { continue }
    // Use location
}

Note: authorizationDenied, authorizationDeniedGlobally, insufficientlyInUse, locationUnavailable, and stationary are only available on iOS 18+. On iOS 17, check update.location == nil to detect unavailable location.

Map diagnostics to user-visible behavior instead of silently waiting:

• authorizationDenied: stop location work and show a Settings recovery path.
• authorizationDeniedGlobally: explain that system Location Services are off.
• insufficientlyInUse: suspend live updates until the feature is active again.
• locationUnavailable: keep the feature usable with cached, typed, or map-region

input while waiting for recovery.

• Reduced or approximate accuracy: widen search/geofence assumptions or request

full accuracy only from a user-triggered feature that needs it.

Before publishing a location, filter for valid horizontal accuracy, acceptable timestamp age, and plausible movement. Use speed and course only when their values are valid; negative values mean the measurement is unavailable.

---

CLServiceSession (iOS 18+)

Setup and Lifecycle

CLServiceSession declares your authorization requirements for a feature. Hold a strong reference for the session's entire duration.

@MainActor
@Observable
final class LocationFeature {
    private var serviceSession: CLServiceSession?
    private var locationTask: Task<Void, Never>?

    func activate() {
        // Declare that this feature needs when-in-use authorization
        serviceSession = CLServiceSession(authorization: .whenInUse)

        locationTask = Task {
            do {
                for try await update in CLLocationUpdate.liveUpdates() {
                    guard let location = update.location else { continue }
                    // process location
                }
            } catch is CancellationError {
                // Expected when the feature stops.
            } catch {
                // Show a degraded state or retry from user action.
            }
        }
    }

    func deactivate() {
        locationTask?.cancel()
        locationTask = nil
        // Release the session to signal you no longer need location
        serviceSession = nil
    }
}

Full Accuracy Request

Request full accuracy when the user has granted approximate-only permission:

// Requires Info.plist:
// NSLocationTemporaryUsageDescriptionDictionary
//   NearbySearchPurpose: "Show nearby stores within walking distance."

let session = CLServiceSession(
    authorization: .whenInUse,
    fullAccuracyPurposeKey: "NearbySearchPurpose"
)

Always Authorization

Only use .always when you need the system to relaunch your app in the background for significant location changes after termination.

let session = CLServiceSession(authorization: .always)

Requires NSLocationAlwaysAndWhenInUseUsageDescription in Info.plist.

Implicit vs. Explicit Sessions

On iOS 18+, CLLocationUpdate.liveUpdates() and CLMonitor create an implicit CLServiceSession behind the scenes if you do not create one. You need an explicit session when:

• You require .always authorization
• You need full accuracy via fullAccuracyPurposeKey
• You want to enforce explicit session management (add

NSLocationRequireExplicitServiceSession to Info.plist)

---

CLMonitor for Geofencing (iOS 17+)

Basic Setup

Use CLMonitor for modern condition monitoring. It is an actor, so its async APIs require await.

@available(iOS 17, *)
actor GeofenceMonitor {
    private var monitor: CLMonitor?
    private var monitoringTask: Task<Void, any Error>?

    func startMonitoring(regions: [GeofenceRegion]) async {
        let monitor = await CLMonitor("myAppGeofences")
        self.monitor = monitor

        // Add circular geographic conditions
        for region in regions {
            let condition = CLMonitor.CircularGeographicCondition(
                center: region.center,
                radius: region.radius
            )
            await monitor.add(condition, identifier: region.id)
        }

        // Listen for events
        monitoringTask = Task {
            for try await event in await monitor.events {
                switch event.state {
                case .satisfied:
                    // Device entered the region
                    handleEntry(identifier: event.identifier)
                case .unsatisfied:
                    // Device exited the region
                    handleExit(identifier: event.identifier)
                case .unknown:
                    break
                default:
                    break
                }
            }
        }
    }

    func stopMonitoring() async {
        monitoringTask?.cancel()
        monitoringTask = nil

        if let monitor {
            for identifier in await monitor.identifiers {
                await monitor.remove(identifier)
            }
        }
        monitor = nil
    }

    private func handleEntry(identifier: String) {
        print("Entered region: \(identifier)")
    }

    private func handleExit(identifier: String) {
        print("Exited region: \(identifier)")
    }
}

struct GeofenceRegion: Identifiable {
    let id: String
    let center: CLLocationCoordinate2D
    let radius: CLLocationDistance
}

Critical CLMonitor Rules

1. Maximum 20 conditions per app. Adding more causes excess conditions to report unmonitored state. This limit is per-app, not per-monitor.

2. Do not recreate CLMonitor instances rapidly. Creating a monitor with the same name while one is still alive crashes the app. Reuse the instance and call add/remove to change conditions.

3. Subscribe to `events` exactly once per CLMonitor. Cancelling and re-subscribing causes the new subscription to immediately cancel. Keep a single long-lived subscription.

4. Use diffing for condition updates. Instead of removing all conditions and re-adding them, calculate which to add and which to remove.

5. Target iOS 18+ for best results. Pair CLMonitor with CLServiceSession for reliable authorization management.

Adding Conditions with Initial State

Specify an assumed initial state to avoid spurious events on first add:

await monitor.add(condition, identifier: "office", assuming: .unsatisfied)

Use .unsatisfied when you believe the device is outside the region. Use .satisfied when you believe the device is inside.

Updating Conditions Dynamically

func updateRegions(_ newRegions: [GeofenceRegion]) async {
    guard let monitor else { return }

    let existingIDs = Set(await monitor.identifiers)
    let newIDs = Set(newRegions.map(\.id))

    // Remove stale conditions
    for id in existingIDs.subtracting(newIDs) {
        await monitor.remove(id)
    }

    // Add new conditions
    for region in newRegions where !existingIDs.contains(region.id) {
        let condition = CLMonitor.CircularGeographicCondition(
            center: region.center,
            radius: region.radius
        )
        await monitor.add(condition, identifier: region.id, assuming: .unsatisfied)
    }
}

Checking Last Known State

if let record = await monitor.record(for: "office") {
    let lastState = record.lastEvent.state
    let lastDate = record.lastEvent.date
    print("Region 'office' was \(lastState) at \(lastDate)")
}

---

CLBackgroundActivitySession

Allow a when-in-use authorized app to receive location updates in the background. Requires the Location updates background mode capability.

@available(iOS 17, *)
actor BackgroundLocationTracker {
    private var backgroundSession: CLBackgroundActivitySession?
    private var serviceSession: CLServiceSession?
    private var trackingTask: Task<Void, Never>?

    func startBackgroundTracking() {
        // Declare authorization intent (iOS 18+)
        serviceSession = CLServiceSession(authorization: .whenInUse)

        // Start background activity session -- shows blue location indicator
        backgroundSession = CLBackgroundActivitySession()

        trackingTask = Task {
            do {
                for try await update in CLLocationUpdate.liveUpdates(.fitness) {
                    guard let location = update.location else { continue }
                    // Record location for fitness tracking, navigation, etc.
                    await recordLocation(location)
                }
            } catch is CancellationError {
                // Expected when background tracking stops.
            } catch {
                // Persist an error state or retry from user action.
            }
        }
    }

    func stopBackgroundTracking() {
        trackingTask?.cancel()
        trackingTask = nil
        backgroundSession?.invalidate()
        backgroundSession = nil
        serviceSession = nil
    }

    private func recordLocation(_ location: CLLocation) async {
        // Persist to database, update Live Activity, etc.
    }
}

Background Requirements Summary

To receive location in the background you need ALL of these:

1. Background Modes > Location updates capability enabled. 2. NSLocationWhenInUseUsageDescription in Info.plist. 3. .whenInUse or .always authorization granted. 4. Either a CLBackgroundActivitySession held or a Live Activity running. 5. An active CLLocationUpdate or CLMonitor subscription.

.always authorization is NOT required for background location. The difference: with .always, the system can relaunch your terminated app for significant location changes. With .whenInUse + background session, the app must be running (foreground or suspended).

---

Significant Location Change Monitoring

Use when you only need coarse location updates at ~500-meter intervals. Extremely battery efficient because it piggybacks on cellular tower changes.

// Legacy CLLocationManager approach (still valid, no modern replacement)
let manager = CLLocationManager()
manager.startMonitoringSignificantLocationChanges()

// The delegate receives updates when the device moves ~500m+ from the
// last reported location. Updates arrive 1-5 minutes apart.

There is no CLLocationUpdate equivalent for significant location changes. Use CLLocationManager for this specific use case.

---

Visit Monitoring

Detect when the user arrives at or departs from a place. Useful for journaling, check-in, and context-aware features.

let manager = CLLocationManager()
manager.startMonitoringVisits()

// Delegate callback:
func locationManager(_ manager: CLLocationManager, didVisit visit: CLVisit) {
    let coordinate = visit.coordinate
    let arrivalDate = visit.arrivalDate
    let departureDate = visit.departureDate
    // departureDate == .distantFuture means the user is still at the location
}

---

Region Monitoring Migration (CLCircularRegion to CLMonitor)

Older Delegate Approach

let region = CLCircularRegion(center: coordinate, radius: 200, identifier: "office")
region.notifyOnEntry = true
region.notifyOnExit = true
manager.startMonitoring(for: region)

Modern Approach (iOS 17+)

// MODERN
let monitor = await CLMonitor("appMonitor")
let condition = CLMonitor.CircularGeographicCondition(center: coordinate, radius: 200)
await monitor.add(condition, identifier: "office")

for try await event in await monitor.events {
    if event.identifier == "office" {
        switch event.state {
        case .satisfied: handleEntry()
        case .unsatisfied: handleExit()
        default: break
        }
    }
}

Key differences:

---

Location Accuracy Management

Accuracy Levels for CLLocationManager

manager.desiredAccuracy = kCLLocationAccuracyBest             // GPS, ~5m, highest power
manager.desiredAccuracy = kCLLocationAccuracyNearestTenMeters // ~10m
manager.desiredAccuracy = kCLLocationAccuracyHundredMeters    // WiFi, ~100m
manager.desiredAccuracy = kCLLocationAccuracyKilometer        // Cell tower, ~1km
manager.desiredAccuracy = kCLLocationAccuracyThreeKilometers  // ~3km, lowest power
manager.desiredAccuracy = kCLLocationAccuracyReduced          // ~5km, privacy-safe

Activity Type (Influences Power Management)

manager.activityType = .other                 // Default
manager.activityType = .automotiveNavigation  // Highway speeds, high accuracy
manager.activityType = .fitness               // Walking/running
manager.activityType = .otherNavigation       // Boats, trains
manager.activityType = .airborne              // Drones, aircraft (iOS 12+)

CLLocationUpdate has no filtering

CLLocationUpdate.liveUpdates() does not support desiredAccuracy or distanceFilter. Filter the stream yourself:

for try await update in CLLocationUpdate.liveUpdates() {
    guard let location = update.location,
          location.horizontalAccuracy < 50,
          location.horizontalAccuracy >= 0 else { continue }
    // Use filtered location
}

---

Testing Location in Simulator

Set a fixed simulated location

In Xcode: Debug > Simulate Location > choose a city or custom coordinate.

GPX File for a Moving Route

Create a .gpx file and add it to your Xcode project:

<?xml version="1.0"?>
<gpx version="1.1" creator="Xcode">
    <wpt lat="37.3349" lon="-122.0090">
        <time>2025-01-01T00:00:00Z</time>
        <name>Apple Park</name>
    </wpt>
    <wpt lat="37.3318" lon="-122.0312">
        <time>2025-01-01T00:01:00Z</time>
        <name>Infinite Loop</name>
    </wpt>
    <wpt lat="37.3230" lon="-122.0322">
        <time>2025-01-01T00:02:00Z</time>
        <name>De Anza College</name>
    </wpt>
</gpx>

Set this file in the scheme: Edit Scheme > Run > Options > Default Location.

The simulator interpolates between waypoints using timestamps. Playback loops automatically when it reaches the last waypoint.

Programmatic Simulation in Tests

Use CLLocationManager with XCTest by injecting a location protocol:

protocol LocationProviding: Sendable {
    func updates() -> AsyncStream<CLLocation>
}

// Production
struct LiveLocationProvider: LocationProviding {
    func updates() -> AsyncStream<CLLocation> {
        AsyncStream { continuation in
            Task {
                for try await update in CLLocationUpdate.liveUpdates() {
                    if let location = update.location {
                        continuation.yield(location)
                    }
                }
                continuation.finish()
            }
        }
    }
}

// Test mock
struct MockLocationProvider: LocationProviding {
    let locations: [CLLocation]

    func updates() -> AsyncStream<CLLocation> {
        AsyncStream { continuation in
            for location in locations {
                continuation.yield(location)
            }
            continuation.finish()
        }
    }
}

---

Privacy and Info.plist Keys

Required Keys

Optional Keys

Usage Description Best Practices

Good: "Shows nearby coffee shops within walking distance so you can find your next stop quickly."

Bad: "This app uses your location."

App Review rejects vague usage descriptions. Be specific about what the user gains from sharing their location.

---

Common Pitfalls

CLMonitor crash on rapid recreation

// CRASH -- creating a monitor with a name already in use
let monitorA = await CLMonitor("myMonitor")
// ... immediately discard monitorA ...
let monitorB = await CLMonitor("myMonitor") // NSInternalInconsistencyException

Fix: reuse the existing monitor instance. Only create a new one after the old one has been fully torn down (conditions removed, reference released, NOT in the same run loop).

Accuracy-limited updates need explicit handling

Approximate location may update infrequently. On iOS 18+, check diagnostic properties such as accuracyLimited and locationUnavailable; otherwise, treat update.location == nil as a state change and provide a degraded experience instead of spinning or timing out.

Forgetting to hold CLBackgroundActivitySession

// WRONG -- session is immediately deallocated
func startBackground() {
    let _ = CLBackgroundActivitySession()
    // ^ No strong reference; session ends immediately
}

// CORRECT -- hold as a stored property
private var bgSession: CLBackgroundActivitySession?

func startBackground() {
    bgSession = CLBackgroundActivitySession()
}

Not checking horizontalAccuracy

// WRONG -- using location with negative accuracy (invalid)
guard let location = update.location else { continue }
updateMap(location) // May have accuracy of -1 (invalid)

// CORRECT
guard let location = update.location,
      location.horizontalAccuracy >= 0 else { continue }
updateMap(location)

A horizontalAccuracy of -1 means the coordinate is invalid.

---

References

• Apple docs: CLLocationUpdate
• Apple docs: CLServiceSession
• Apple docs: CLMonitor
• Apple docs: CLBackgroundActivitySession
• Apple docs: Requesting authorization
• Apple docs: Handling background location

MapKit Patterns Reference

Extended patterns for MapKit on iOS 17+ with SwiftUI. Import MapKit and SwiftUI in every file that uses these APIs.

import MapKit
import SwiftUI

---

Contents

• Complete Map View Setup
• Custom Annotation Views
• Camera Control (MapCameraPosition)
• Map Selection Handling
• Search with Autocomplete
• Route Display
• Look Around Preview
• Map Snapshots (MKMapSnapshotter)
• Clustering Annotations
• MapKit with MKMapItem Utilities
• iOS 26 New APIs
• User Location Display
• Map in a List or ScrollView
• Coordinate Utilities
• Accessibility
• References

Complete Map View Setup

A production-ready map view with markers, user location, and controls.

struct StoreLocatorMap: View {
    let stores: [Store]
    @State private var position: MapCameraPosition = .automatic
    @State private var selectedStore: Store?

    var body: some View {
        Map(position: $position, selection: $selectedStore) {
            UserAnnotation()

            ForEach(stores) { store in
                Marker(store.name, systemImage: "storefront",
                       coordinate: store.coordinate)
                    .tint(store.isOpen ? .green : .gray)
                    .tag(store)
            }
        }
        .mapStyle(.standard(pointsOfInterest: .excludingAll))
        .mapControls {
            MapUserLocationButton()
            MapCompass()
            MapScaleView()
            MapPitchToggle()
        }
        .safeAreaInset(edge: .bottom) {
            if let store = selectedStore {
                StoreDetailCard(store: store)
                    .padding()
            }
        }
    }
}

Conform the data model to Hashable for use with map selection:

struct Store: Identifiable, Hashable {
    let id: UUID
    let name: String
    let coordinate: CLLocationCoordinate2D
    let isOpen: Bool

    static func == (lhs: Store, rhs: Store) -> Bool { lhs.id == rhs.id }
    func hash(into hasher: inout Hasher) { hasher.combine(id) }
}

---

Custom Annotation Views

Use Annotation for fully custom SwiftUI content at a coordinate. Prefer Marker for standard pins because it provides the platform marker appearance and a title that VoiceOver can announce.

Map {
    ForEach(friends) { friend in
        Annotation(friend.name, coordinate: friend.coordinate, anchor: .bottom) {
            VStack(spacing: 0) {
                AsyncImage(url: friend.avatarURL) { image in
                    image.resizable().scaledToFill()
                } placeholder: {
                    Color.gray
                }
                .frame(width: 40, height: 40)
                .clipShape(.circle)
                .overlay(Circle().stroke(.white, lineWidth: 2))

                Image(systemName: "triangle.fill")
                    .font(.caption2)
                    .foregroundStyle(.white)
                    .rotationEffect(.degrees(180))
                    .offset(y: -3)
            }
        }
    }
}

Annotation with anchorOffset for callout-style layout

Annotation(place.name, coordinate: place.coordinate, anchor: .bottom) {
    VStack(spacing: 2) {
        Text(place.name)
            .font(.caption)
            .fontWeight(.semibold)
            .padding(.horizontal)
            .padding(.vertical)
            .background(.ultraThinMaterial, in: .capsule)

        Image(systemName: "mappin.circle.fill")
            .font(.title)
            .foregroundStyle(.red)
    }
}

---

Camera Control (MapCameraPosition)

Animate camera changes

Wrap position updates in withAnimation for smooth transitions:

func flyTo(_ coordinate: CLLocationCoordinate2D) {
    withAnimation(.easeInOut(duration: 1.0)) {
        position = .camera(
            MapCamera(centerCoordinate: coordinate, distance: 2000,
                      heading: 0, pitch: 45)
        )
    }
}

Frame multiple annotations

func frameAllStores() {
    withAnimation {
        position = .automatic  // Frames all map content
    }
}

// Or frame a specific rect
func frameRegion(_ region: MKCoordinateRegion) {
    withAnimation {
        position = .region(region)
    }
}

Read current camera position

Use onMapCameraChange to observe what the user is looking at:

@State private var visibleRegion: MKCoordinateRegion?

Map(position: $position) { ... }
    .onMapCameraChange(frequency: .onEnd) { context in
        visibleRegion = context.region
    }

frequency: .onEnd fires after the user finishes scrolling. Use .continuous only when you need live tracking (costs more CPU).

---

Map Selection Handling

Select markers by MKMapItem

Use MKMapItem as the selection type when you want to look up place details:

@State private var selectedItem: MKMapItem?

Map(selection: $selectedItem) {
    ForEach(searchResults) { result in
        Marker(item: result)
    }
}
.onChange(of: selectedItem) { _, newItem in
    guard let item = newItem else { return }
    Task { await fetchLookAround(for: item) }
}

Select by custom Identifiable tag

@State private var selectedPlaceID: Place.ID?

Map(selection: $selectedPlaceID) {
    ForEach(places) { place in
        Marker(place.name, coordinate: place.coordinate)
            .tag(place.id)
    }
}

---

Search with Autocomplete

Full pattern: completer feeds suggestions, selecting a suggestion triggers a full search that returns MKMapItem results.

@Observable
final class MapSearchService: NSObject, MKLocalSearchCompleterDelegate {
    var completions: [MKLocalSearchCompletion] = []
    var searchResults: [MKMapItem] = []
    var queryFragment: String = "" {
        didSet { completer.queryFragment = queryFragment }
    }

    private let completer: MKLocalSearchCompleter

    override init() {
        completer = MKLocalSearchCompleter()
        super.init()
        completer.delegate = self
        completer.resultTypes = [.address, .pointOfInterest]
    }

    // Restrict suggestions to the visible map region
    func updateRegion(_ region: MKCoordinateRegion) {
        completer.region = region
    }

    func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) {
        completions = completer.results
    }

    func completer(_ completer: MKLocalSearchCompleter, didFailWithError error: Error) {
        completions = []
    }

    func select(_ completion: MKLocalSearchCompletion) async {
        let request = MKLocalSearch.Request(completion: completion)
        request.resultTypes = [.pointOfInterest, .address]
        do {
            let response = try await MKLocalSearch(request: request).start()
            searchResults = response.mapItems
        } catch {
            searchResults = []
        }
    }
}

Search View Integration

struct MapSearchView: View {
    @State private var searchService = MapSearchService()
    @State private var searchText = ""
    @State private var position: MapCameraPosition = .automatic

    var body: some View {
        Map(position: $position) {
            ForEach(searchService.searchResults, id: \.self) { item in
                Marker(item: item)
            }
        }
        .searchable(text: $searchText, prompt: "Search places")
        .searchSuggestions {
            ForEach(searchService.completions, id: \.self) { completion in
                Button {
                    Task { await searchService.select(completion) }
                } label: {
                    VStack(alignment: .leading) {
                        Text(completion.title)
                        Text(completion.subtitle)
                            .font(.caption)
                            .foregroundStyle(.secondary)
                    }
                }
            }
        }
        .task(id: searchText) {
            try? await Task.sleep(for: .milliseconds(300))
            guard !Task.isCancelled else { return }
            searchService.queryFragment = searchText
        }
        .onMapCameraChange(frequency: .onEnd) { context in
            searchService.updateRegion(context.region)
        }
    }
}

---

Route Display

Calculate directions and draw the route polyline on the map.

struct DirectionsMapView: View {
    let source: MKMapItem
    let destination: MKMapItem
    @State private var route: MKRoute?
    @State private var position: MapCameraPosition = .automatic
    @State private var travelTime: String = ""

    var body: some View {
        Map(position: $position) {
            if let route {
                MapPolyline(route.polyline)
                    .stroke(.blue, lineWidth: 6)
            }
            Marker(item: source)
                .tint(.green)
            Marker(item: destination)
                .tint(.red)
        }
        .overlay(alignment: .top) {
            if !travelTime.isEmpty {
                Text(travelTime)
                    .font(.caption)
                    .padding()
                    .background(.ultraThinMaterial, in: .capsule)
                    .padding(.top)
            }
        }
        .task { await calculateRoute() }
    }

    private func calculateRoute() async {
        let request = MKDirections.Request()
        request.source = source
        request.destination = destination
        request.transportType = .automobile

        do {
            let response = try await MKDirections(request: request).calculate()
            route = response.routes.first
            if let route {
                let formatter = DateComponentsFormatter()
                formatter.unitsStyle = .abbreviated
                formatter.allowedUnits = [.hour, .minute]
                travelTime = formatter.string(from: route.expectedTravelTime) ?? ""

                withAnimation {
                    position = .rect(route.polyline.boundingMapRect)
                }
            }
        } catch {
            print("Directions error: \(error.localizedDescription)")
        }
    }
}

Multiple Route Options

request.requestsAlternateRoutes = true
let response = try await MKDirections(request: request).calculate()

// response.routes contains multiple route options
// Display all routes, highlight the selected one:
ForEach(Array(response.routes.enumerated()), id: \.offset) { index, route in
    MapPolyline(route.polyline)
        .stroke(index == 0 ? .blue : .gray.opacity(0.5), lineWidth: index == 0 ? 6 : 3)
}

---

Look Around Preview

Show Apple's street-level imagery for a selected location. Availability depends on region coverage.

struct LookAroundView: View {
    let mapItem: MKMapItem
    @State private var scene: MKLookAroundScene?

    var body: some View {
        Group {
            if let scene {
                LookAroundPreview(scene: .constant(scene))
                    .frame(height: 200)
                    .clipShape(.rect(cornerRadius: 12))
            } else {
                ContentUnavailableView("No Look Around",
                    systemImage: "eye.slash",
                    description: Text("Look Around is not available here."))
            }
        }
        .task(id: mapItem) {
            scene = nil
            let request = MKLookAroundSceneRequest(mapItem: mapItem)
            scene = try? await request.scene
        }
    }
}

Look Around overlay on a Map

Map(selection: $selectedItem) { ... }
    .overlay(alignment: .bottomTrailing) {
        if lookAroundScene != nil {
            LookAroundPreview(scene: $lookAroundScene)
                .frame(width: 200, height: 130)
                .clipShape(.rect(cornerRadius: 10))
                .padding()
        }
    }
    .onChange(of: selectedItem) { _, newItem in
        guard let item = newItem else {
            lookAroundScene = nil
            return
        }
        Task {
            let request = MKLookAroundSceneRequest(mapItem: item)
            lookAroundScene = try? await request.scene
        }
    }

---

Map Snapshots (MKMapSnapshotter)

Generate a static image of a map region. Useful for share sheets, widgets, notifications, or thumbnails.

func generateMapSnapshot(center: CLLocationCoordinate2D,
                         size: CGSize = CGSize(width: 300, height: 200)) async throws -> UIImage {
    let options = MKMapSnapshotter.Options()
    options.region = MKCoordinateRegion(
        center: center,
        span: MKCoordinateSpan(latitudeDelta: 0.01, longitudeDelta: 0.01)
    )
    options.size = size
    options.mapType = .standard
    options.showsBuildings = true

    let snapshotter = MKMapSnapshotter(options: options)
    let snapshot = try await snapshotter.start()

    // Draw a pin at the center
    let image = UIGraphicsImageRenderer(size: size).image { context in
        snapshot.image.draw(at: .zero)
        let point = snapshot.point(for: center)
        let pin = UIImage(systemName: "mappin.circle.fill")?
            .withTintColor(.red, renderingMode: .alwaysOriginal)
        pin?.draw(at: CGPoint(x: point.x - 15, y: point.y - 30),
                  blendMode: .normal, alpha: 1.0)
    }
    return image
}

---

Dense Annotations and Clustering

For dense SwiftUI maps, hide titles at low zoom or reduce visible items based on the current camera region. Use MKMapView when you need explicit cluster configuration.

Map {
    ForEach(allStores) { store in
        Marker(store.name, systemImage: "cart", coordinate: store.coordinate)
            .annotationTitles(.hidden)  // Hide titles at low zoom
    }
}
.mapStyle(.standard(pointsOfInterest: .excludingAll))

For custom clustering behavior with MKMapView (UIKit interop), set clusteringIdentifier on MKMarkerAnnotationView.

---

MapKit with MKMapItem Utilities

Open in Apple Maps

let item = MKMapItem(placemark: MKPlacemark(coordinate: coordinate))
item.name = "Destination"
item.openInMaps(launchOptions: [
    MKLaunchOptionsDirectionsModeKey: MKLaunchOptionsDirectionsModeDriving
])

Distance Calculation

func distanceBetween(_ a: CLLocationCoordinate2D,
                     _ b: CLLocationCoordinate2D) -> CLLocationDistance {
    let locA = CLLocation(latitude: a.latitude, longitude: a.longitude)
    let locB = CLLocation(latitude: b.latitude, longitude: b.longitude)
    return locA.distance(from: locB) // meters
}

Format Distance for Display

let formatter = MKDistanceFormatter()
formatter.unitStyle = .abbreviated
let text = formatter.string(fromDistance: 1500) // "0.9 mi" or "1.5 km"

---

iOS 26 New APIs

MKGeocodingRequest

Convert an address string to map items with richer data than CLGeocoder:

@available(iOS 26, *)
func geocodeAddresses(_ addresses: [String]) async -> [MKMapItem] {
    var items: [MKMapItem] = []
    for address in addresses {
        guard let request = MKGeocodingRequest(addressString: address) else { continue }
        if let mapItems = try? await request.mapItems {
            items.append(contentsOf: mapItems)
        }
    }
    return items
}

MKReverseGeocodingRequest

Convert coordinates to map items with MKAddress:

@available(iOS 26, *)
func reverseGeocode(_ coordinate: CLLocationCoordinate2D) async -> MKAddress? {
    let location = CLLocation(latitude: coordinate.latitude,
                              longitude: coordinate.longitude)
    guard let request = MKReverseGeocodingRequest(location: location) else {
        return nil
    }
    let mapItems = try? await request.mapItems
    return mapItems?.first?.address
}

MKAddress and MKAddressRepresentations

MKAddress provides full and short address strings. Use an MKMapItem's MKAddressRepresentations to format addresses for different contexts:

@available(iOS 26, *)
func formatAddress(for item: MKMapItem) -> String {
    // Use address representations for locale-aware formatting
    item.addressRepresentations?.fullAddress(includingRegion: true, singleLine: true)
        ?? item.address?.fullAddress
        ?? ""
}

PlaceDescriptor (via GeoToolbox)

Create place references from coordinates when you do not have a Place ID:

import GeoToolbox

@available(iOS 26, *)
func mapItem(for myCoordinate: CLLocationCoordinate2D) async throws -> MKMapItem {
    let descriptor = PlaceDescriptor(
        representations: [.coordinate(myCoordinate)],
        commonName: "My Favorite Cafe"
    )

    let request = MKMapItemRequest(placeDescriptor: descriptor)
    return try await request.mapItem
}

// Use mapItem with any MapKit API: Marker(item:), directions, place cards

Cycling Directions (iOS 14+)

func cyclingRoute(to destination: MKMapItem) async throws -> MKRoute? {
    let request = MKDirections.Request()
    request.source = .forCurrentLocation()
    request.destination = destination
    request.transportType = .cycling
    let response = try await MKDirections(request: request).calculate()
    return response.routes.first
}

---

User Location Display

Show the user's position with the built-in blue dot:

Map(position: $position) {
    UserAnnotation()       // Blue dot with accuracy ring
    // ... other content
}
.mapControls {
    MapUserLocationButton()  // Button to re-center on user
}

UserAnnotation() requires location authorization. If authorization is denied, the annotation does not appear and no error is thrown.

---

Map in a List or ScrollView

When embedding a Map inside a ScrollView, disable map gestures that conflict with scrolling:

ScrollView {
    Map(position: $position, interactionModes: []) {
        Marker("Location", coordinate: coord)
    }
    .frame(height: 200)
    .clipShape(.rect(cornerRadius: 12))

    Text("Details below the map...")
}

Use interactionModes: [] for a fully static map thumbnail or interactionModes: [.zoom] to allow pinch-to-zoom without pan conflicts.

---

Coordinate Utilities

Region from an array of coordinates

func regionForCoordinates(_ coords: [CLLocationCoordinate2D]) -> MKCoordinateRegion {
    guard !coords.isEmpty else {
        return MKCoordinateRegion()
    }
    var minLat = coords[0].latitude
    var maxLat = coords[0].latitude
    var minLon = coords[0].longitude
    var maxLon = coords[0].longitude

    for coord in coords {
        minLat = min(minLat, coord.latitude)
        maxLat = max(maxLat, coord.latitude)
        minLon = min(minLon, coord.longitude)
        maxLon = max(maxLon, coord.longitude)
    }

    let center = CLLocationCoordinate2D(
        latitude: (minLat + maxLat) / 2,
        longitude: (minLon + maxLon) / 2
    )
    let span = MKCoordinateSpan(
        latitudeDelta: (maxLat - minLat) * 1.3,  // 30% padding
        longitudeDelta: (maxLon - minLon) * 1.3
    )
    return MKCoordinateRegion(center: center, span: span)
}

CLLocationCoordinate2D Equatable conformance

CLLocationCoordinate2D does not conform to Equatable by default. Extend it when needed for comparisons:

extension CLLocationCoordinate2D: @retroactive Equatable {
    public static func == (lhs: Self, rhs: Self) -> Bool {
        lhs.latitude == rhs.latitude && lhs.longitude == rhs.longitude
    }
}

Note: Use @retroactive (Swift 5.10+) to silence the warning about conforming types from other modules.

---

Accessibility

Marker accessibility

Marker views include built-in VoiceOver support using the title string. Add .accessibilityLabel for richer descriptions:

Marker(store.name, coordinate: store.coordinate)
    .accessibilityLabel("\(store.name), \(store.distanceText) away")

Map accessibility

Add a concise description of the map purpose:

Map { ... }
    .accessibilityElement()
    .accessibilityLabel("Store locations map showing \(stores.count) stores")

---

References

• Apple docs: MapKit for SwiftUI
• Apple docs: Map
• Apple docs: MapCameraPosition
• Apple docs: MKLocalSearch
• Apple docs: MKDirections
• Apple docs: MKLookAroundScene