/mapkit

name: mapkit
description: "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."

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

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

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

@State private var selectedMarker: MKMapItem?

Map(selection: $selectedMarker) {
    ForEach(places) { place in
        Marker(place.name, coor