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,

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](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](references/mapkit corelocation patterns.md) when the task involves location update lifecycle, geofencing, background location, testing, or privacy keys. Contents [Workflow]( workflow) [SwiftUI Map View (iOS 17+)]( swiftui map view ios 17) [CoreLocation Modern API]( corelocation modern api) [Geocoding]( geocoding) [Search]( search) [Directions]( directions) [PlaceDescriptor (iOS 26+)]( placedescriptor ios 26) [Common Mistakes]( common mistakes) [Review Checklist]( review checklist) [References]( 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+) Marker and Annotation Overlays: Polyline, Polygon, Circle Camera Position MapCameraPosition controls what the map displays. Bind it to let the user interact and to programmatically move the camera. 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](references/mapkit patterns.md 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](references/mapkit patterns.md map in a list or scrollview). Map 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. 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. 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 Geocoding CLGeocoder (iOS 8+) MKGeocodingRequest and MKReverseGeocodingRequest (iOS 26+) New MapKit native geocoding that returns MKMapItem with richer data and MKAddress / MKAddressRepresentations for flexible address formatting. Search MKLocalSearchCompleter (Autocomplete) MKLocalSearch (Full Search) Directions Display Route on Map ETA Calculation Cycling Directions (iOS 14+) Use .cycling as the request transport type; see the complete [cycling route](references/mapkit patterns.md cycling directions ios 14) example. PlaceDescriptor (iOS 26+) Create rich place references from coordinates or addresses without needing a Place ID. Requires import GeoToolbox . 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](references/mapkit patterns.md) — Map setup, annotations, search, routes, clustering, Look Around, snapshots. [references/mapkit corelocation patterns.md](references/mapkit corelocation patterns.md) — CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.