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 [blocked] when you need full map setup, search, routes, Look Around, snapshots, or iOS 26 place APIs. Read references/mapkit-corelocation-patterns.md [blocked] 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
- Import
MapKit. - Create a
Mapview with optionalMapCameraPositionbinding. - Add
Marker,Annotation,MapPolyline,MapPolygon, orMapCircleinside theMapContentBuilderclosure. - Configure map style with
.mapStyle(). - Add map controls with
.mapControls { }. - Handle selection with a
selection:binding.
2. Track user location
- Add
NSLocationWhenInUseUsageDescriptionto Info.plist. - On iOS 18+, create a
CLServiceSessionto manage authorization. - Iterate
CLLocationUpdate.liveUpdates()in aTask. - 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
MKLocalSearchCompleterfor autocomplete suggestions. - Debounce user input (at least 300ms) before setting the query.
- Convert selected completion to
MKLocalSearch.Requestfor full results. - Display results as markers or in a list.
4. Get directions and display a route
- Create an
MKDirections.Requestwith source and destinationMKMapItem. - 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+)
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 [blocked].
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 [blocked].
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 [blocked] 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
NSLocationWhenInUseUsageDescriptionwith specific reason - Authorization denial handled with Settings deep link
-
CLLocationUpdatetask cancelled when not needed (battery) - Location accuracy appropriate for the use case
- Map annotations use
Identifiabledata with stable IDs - Geocoding errors handled (network failure, no results)
- Search completer input debounced
-
CLMonitorlimited 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 [blocked] — Map setup, annotations, search, routes, clustering, Look Around, snapshots.
- references/mapkit-corelocation-patterns.md [blocked] — CLLocationUpdate, CLMonitor, CLServiceSession, background location, testing.


