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](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+)

```swift
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

```swift
// 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

```swift
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.

```swift
// 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

```swift
.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

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

### Map Selection

```swift
@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+)