MapKit and CoreLocation

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.

See references/mapkit-patterns.md for extended MapKit patterns and references/corelocation-patterns.md for CoreLocation patterns.

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

• Import MapKit .

• Create a Map view with optional MapCameraPosition binding.

• Add Marker , Annotation , MapPolyline , MapPolygon , or MapCircle

inside the MapContentBuilder closure.

• Configure map style with .mapStyle() .

• Add map controls with .mapControls { } .

• Handle selection with a selection: binding.

2. Track user location

• Add NSLocationWhenInUseUsageDescription to Info.plist.

• On iOS 18+, create a CLServiceSession to manage authorization.

• Iterate CLLocationUpdate.liveUpdates() in a Task .

• Filter updates by distance or accuracy before updating the UI.

• Stop the task when location tracking is no longer needed.

3. Search for places

• Configure MKLocalSearchCompleter for autocomplete suggestions.

• Debounce user input (at least 300ms) before setting the query.

• Convert selected completion to MKLocalSearch.Request for full results.

• Display results as markers or in a list.

4. Get directions and display a route

• Create an MKDirections.Request with source and destination MKMapItem .

• Set transportType (.automobile , .walking , .transit , .cycling ).

• Await MKDirections.calculate() .

• 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 .

import CoreLocation

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

func startTracking() {
    updateTask = Task {
        let updates = CLLocationUpdate.liveUpdates()
        for try await update in updates {
            guard let location = update.location else { continue }
            // Filter by horizontal accuracy
            guard location.horizontalAccuracy < 50 else { continue }
            await MainActor.run {
                self.currentLocation = location
            }
        }
    }
}

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 26+)

@available(iOS 26, *) 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 .

@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 .authorizedAlways upfront — users distrust broad permissions. DO: Start with .requestWhenInUseAuthorization() , escalate to .always only when the user enables a background feature.

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

DON'T: Keep location updates running when the map/view is not visible (drains battery). DO: Use .task { } in SwiftUI so updates cancel automatically on disappear.

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/corelocation-patterns.md — CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.