Implement, review, or improve maps and location features in iOS/macOS apps using MapKit and CoreLocation. Use when working with Map views, annotations, markers, polylines, user location tracking, geocoding, reverse geocoding, search/autocomplete, directions and routes, geofencing, region monitoring, CLLocationUpdate async streams, or location authorization flows. Also use when working with maps, coordinates, addresses, places, directions, distance calculations, or location-based features in Swift apps.
SKILL.md
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.
// 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
Default to .standard; select .imagery or .hybrid, realistic elevation,
traffic, and point-of-interest filtering only when the feature requires them.
See Complete Map View Setup.
Map Interaction Modes
Keep .all for an interactive map. Restrict modes only for intentional gesture
coordination; use [] for a static embedded map. See
Map in a List or ScrollView.
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.
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.
