MapKit API Reference

Complete MapKit API reference for iOS development. Covers both SwiftUI Map (iOS 17+) and MKMapView (UIKit).

Related Skills

• axiom-mapkit — Decision trees, anti-patterns, pressure scenarios

• axiom-mapkit-diag — Symptom-based troubleshooting

Part 1: Modern API Overview

Feature SwiftUI Map (iOS 17+) MKMapView

Declaration Map(position:) { content }

MKMapView()

Camera control MapCameraPosition binding setRegion(_:animated:)

Annotations Marker , Annotation in content addAnnotation(_:)

• delegate

Overlays MapCircle , MapPolyline , MapPolygon

addOverlay(_:)

• renderer delegate

User location UserAnnotation()

showsUserLocation = true

Selection .mapSelection($selection)

delegate didSelect

Controls .mapControls { }

showsCompass , showsScale

Interaction modes .mapInteractionModes([])

delegate methods

Clustering Built-in via .mapItemClusteringIdentifier

MKClusterAnnotation

Part 2: SwiftUI Map API

Basic Map

@State private var cameraPosition: MapCameraPosition = .automatic

Map(position: $cameraPosition) { Marker("Home", coordinate: homeCoord) Annotation("Custom", coordinate: coord) { Image(systemName: "star.fill") .foregroundStyle(.yellow) .padding(4) .background(.blue, in: Circle()) } UserAnnotation() MapCircle(center: coord, radius: 500) .foregroundStyle(.blue.opacity(0.3)) MapPolyline(coordinates: routeCoords) .stroke(.blue, lineWidth: 3) } .mapStyle(.standard(elevation: .realistic)) .mapControls { MapUserLocationButton() MapCompass() MapScaleView() }

MapCameraPosition

Controls where the camera is positioned:

// System manages camera to show all content .automatic

// Specific region .region(MKCoordinateRegion( center: CLLocationCoordinate2D(latitude: 37.7749, longitude: -122.4194), span: MKCoordinateSpan(latitudeDelta: 0.05, longitudeDelta: 0.05) ))

// Specific camera with pitch and heading .camera(MapCamera( centerCoordinate: coordinate, distance: 1000, // meters from center heading: 90, // degrees from north pitch: 60 // degrees from vertical (0 = top-down) ))

// Follow user location .userLocation(followsHeading: true, fallback: .automatic)

// Show specific item .item(mapItem)

// Show specific rect .rect(MKMapRect(...))

Programmatic Camera Changes

// Animate to new position withAnimation { cameraPosition = .region(newRegion) }

// Keyframe animation (iOS 17+) Map(position: $cameraPosition) .mapCameraKeyframeAnimator(trigger: flyToTrigger) { initialCamera in KeyframeTrack(.centerCoordinate) { LinearKeyframe(destination, duration: 2.0) } KeyframeTrack(.distance) { CubicKeyframe(5000, duration: 1.0) CubicKeyframe(1000, duration: 1.0) } }

Map Selection

@State private var selectedItem: MKMapItem?

Map(position: $cameraPosition, selection: $selectedItem) { ForEach(mapItems, id: .self) { item in Marker(item: item) } } .onChange(of: selectedItem) { _, newItem in if let newItem { // Handle selection } }

Camera Change Callback

Map(position: $cameraPosition) { ... } .onMapCameraChange { context in // context.region — visible MKCoordinateRegion // context.camera — current MapCamera // context.rect — visible MKMapRect fetchAnnotations(in: context.region) } .onMapCameraChange(frequency: .continuous) { context in // Called during gesture (not just at end) }

Map Styles

.mapStyle(.standard) // Default .mapStyle(.standard(elevation: .realistic)) // 3D buildings .mapStyle(.standard(emphasis: .muted)) // Muted colors .mapStyle(.standard(pointsOfInterest: .including([.restaurant, .cafe]))) .mapStyle(.imagery) // Satellite .mapStyle(.imagery(elevation: .realistic)) // 3D satellite .mapStyle(.hybrid) // Satellite + labels .mapStyle(.hybrid(elevation: .realistic)) // 3D hybrid

Interaction Modes

// Allow all interactions (default) .mapInteractionModes(.all)

// Read-only map (no interaction) .mapInteractionModes([])

// Pan only, no zoom .mapInteractionModes([.pan])

// Pan and zoom, no rotate/pitch .mapInteractionModes([.pan, .zoom])

Part 3: Map Content

Marker

System-styled map marker with callout:

// Basic marker Marker("Coffee Shop", coordinate: coord)

// With system image Marker("Coffee Shop", systemImage: "cup.and.saucer.fill", coordinate: coord)

// With monogram (2 characters max) Marker("Coffee Shop", monogram: Text("CS"), coordinate: coord)

// Color Marker("Coffee Shop", coordinate: coord) .tint(.brown)

// From MKMapItem Marker(item: mapItem)

Annotation

Fully custom view at a coordinate:

Annotation("Custom Pin", coordinate: coord) { VStack { Image(systemName: "mappin.circle.fill") .font(.title) .foregroundStyle(.red) Text("Here") .font(.caption) } }

// Anchor point (default is bottom center) Annotation("Pin", coordinate: coord, anchor: .center) { Circle() .fill(.blue) .frame(width: 20, height: 20) }

UserAnnotation

Current user location indicator:

UserAnnotation()

// Custom appearance UserAnnotation(anchor: .center) { Image(systemName: "location.circle.fill") .foregroundStyle(.blue) }

Shape Overlays

// Circle MapCircle(center: coord, radius: 1000) // radius in meters .foregroundStyle(.blue.opacity(0.2)) .stroke(.blue, lineWidth: 2)

// Polygon MapPolygon(coordinates: polygonCoords) .foregroundStyle(.green.opacity(0.3)) .stroke(.green, lineWidth: 2)

// Polyline MapPolyline(coordinates: routeCoords) .stroke(.blue, lineWidth: 4)

// From MKRoute MapPolyline(route.polyline) .stroke(.blue, lineWidth: 5)

Clustering

ForEach(locations) { location in Marker(location.name, coordinate: location.coordinate) .tag(location.id) } .mapItemClusteringIdentifier("locations")

Part 4: MKMapView Lifecycle and Delegates

Creating MKMapView in SwiftUI

struct MapViewWrapper: UIViewRepresentable { @Binding var region: MKCoordinateRegion let annotations: [MKAnnotation]

func makeUIView(context: Context) -> MKMapView {
    let mapView = MKMapView()
    mapView.delegate = context.coordinator
    mapView.showsUserLocation = true
    mapView.register(
        MKMarkerAnnotationView.self,
        forAnnotationViewWithReuseIdentifier: "marker"
    )
    return mapView
}

func updateUIView(_ mapView: MKMapView, context: Context) {
    // Guard against infinite loops
    if !regionsAreEqual(mapView.region, region) {
        mapView.setRegion(region, animated: true)
    }

    // Diff annotations instead of removing all
    let current = Set(mapView.annotations.compactMap { $0 as? MyAnnotation })
    let desired = Set(annotations.compactMap { $0 as? MyAnnotation })
    let toAdd = desired.subtracting(current)
    let toRemove = current.subtracting(desired)
    mapView.addAnnotations(Array(toAdd))
    mapView.removeAnnotations(Array(toRemove))
}

func makeCoordinator() -> Coordinator {
    Coordinator(self)
}

static func dismantleUIView(_ mapView: MKMapView, coordinator: Coordinator) {
    mapView.removeAnnotations(mapView.annotations)
    mapView.removeOverlays(mapView.overlays)
}

}

Key MKMapViewDelegate Methods

class Coordinator: NSObject, MKMapViewDelegate { var parent: MapViewWrapper

init(_ parent: MapViewWrapper) {
    self.parent = parent
}

// Annotation view customization
func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? {
    guard !(annotation is MKUserLocation) else { return nil }  // Use default for user

    let view = mapView.dequeueReusableAnnotationView(
        withIdentifier: "marker",
        for: annotation
    ) as! MKMarkerAnnotationView
    view.markerTintColor = .systemRed
    view.glyphImage = UIImage(systemName: "mappin")
    view.clusteringIdentifier = "poi"
    view.canShowCallout = true
    return view
}

// Overlay rendering
func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer {
    if let circle = overlay as? MKCircle {
        let renderer = MKCircleRenderer(circle: circle)
        renderer.fillColor = UIColor.systemBlue.withAlphaComponent(0.2)
        renderer.strokeColor = .systemBlue
        renderer.lineWidth = 2
        return renderer
    }
    if let polyline = overlay as? MKPolyline {
        let renderer = MKPolylineRenderer(polyline: polyline)
        renderer.strokeColor = .systemBlue
        renderer.lineWidth = 4
        return renderer
    }
    if let polygon = overlay as? MKPolygon {
        let renderer = MKPolygonRenderer(polygon: polygon)
        renderer.fillColor = UIColor.systemGreen.withAlphaComponent(0.3)
        renderer.strokeColor = .systemGreen
        renderer.lineWidth = 2
        return renderer
    }
    return MKOverlayRenderer(overlay: overlay)
}

// Region change tracking
func mapView(_ mapView: MKMapView, regionDidChangeAnimated animated: Bool) {
    parent.region = mapView.region
}

// Annotation selection
func mapView(_ mapView: MKMapView, didSelect annotation: MKAnnotation) {
    // Handle tap
}

// Cluster annotation
func mapView(
    _ mapView: MKMapView,
    clusterAnnotationForMemberAnnotations memberAnnotations: [MKAnnotation]
) -> MKClusterAnnotation {
    MKClusterAnnotation(memberAnnotations: memberAnnotations)
}

}

Part 5: Annotation Types and Customization

MKMarkerAnnotationView (iOS 11+)

Balloon-shaped marker with glyph:

let view = MKMarkerAnnotationView(annotation: annotation, reuseIdentifier: "marker") view.markerTintColor = .systemPurple view.glyphImage = UIImage(systemName: "star.fill") view.glyphText = "A" // Text glyph (overrides image) view.displayPriority = .required // Always visible view.clusteringIdentifier = "category" // Enable clustering view.canShowCallout = true view.titleVisibility = .adaptive // Show title based on space view.subtitleVisibility = .hidden

MKAnnotationView

Fully custom annotation view:

let view = MKAnnotationView(annotation: annotation, reuseIdentifier: "custom") view.image = UIImage(named: "custom-pin") view.centerOffset = CGPoint(x: 0, y: -view.image!.size.height / 2) view.canShowCallout = true view.leftCalloutAccessoryView = UIImageView(image: thumbnail) view.rightCalloutAccessoryView = UIButton(type: .detailDisclosure)

Custom Callout

func mapView( _ mapView: MKMapView, annotationView view: MKAnnotationView, calloutAccessoryControlTapped control: UIControl ) { guard let annotation = view.annotation as? MyAnnotation else { return } // Navigate to detail view }

Annotation View Reuse

Always use dequeueReusableAnnotationView(withIdentifier:for:) :

// Register in makeUIView (once) mapView.register(MKMarkerAnnotationView.self, forAnnotationViewWithReuseIdentifier: "marker")

// Dequeue in delegate (every time) func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView? { let view = mapView.dequeueReusableAnnotationView(withIdentifier: "marker", for: annotation) // Configure... return view }

Without reuse: 1000 annotations = 1000 views in memory. With reuse: ~20-30 views recycled as user scrolls.

Part 6: MKLocalSearch and MKLocalSearchCompleter

MKLocalSearchCompleter — Real-Time Autocomplete

let completer = MKLocalSearchCompleter() completer.delegate = self completer.resultTypes = [.pointOfInterest, .address] completer.region = visibleMapRegion // Bias results to visible area

// Update on each keystroke completer.queryFragment = "coffee"

// Delegate receives results func completerDidUpdateResults(_ completer: MKLocalSearchCompleter) { let results = completer.results // [MKLocalSearchCompletion] for result in results { // result.title — "Starbucks" // result.subtitle — "123 Main St, San Francisco, CA" // result.titleHighlightRanges — Ranges matching query } }

func completer(_ completer: MKLocalSearchCompleter, didFailWithError error: Error) { // Network error, rate limit, etc. }

MKLocalSearch — Full Search

// From autocomplete completion let request = MKLocalSearch.Request(completion: selectedCompletion)

// From natural language let request = MKLocalSearch.Request() request.naturalLanguageQuery = "coffee shops" request.region = mapRegion // Bias results request.resultTypes = .pointOfInterest // Filter type request.pointOfInterestFilter = MKPointOfInterestFilter( including: [.cafe, .restaurant] )

let search = MKLocalSearch(request: request) let response = try await search.start()

for item in response.mapItems { // item.name — "Starbucks" // item.placemark — MKPlacemark with address // item.placemark.coordinate — CLLocationCoordinate2D // item.phoneNumber — optional phone // item.url — optional website // item.pointOfInterestCategory — .cafe, .restaurant, etc. }

Result Types

// Filter what kind of results to return request.resultTypes = .address // Street addresses only request.resultTypes = .pointOfInterest // Businesses, landmarks request.resultTypes = .physicalFeature // Mountains, lakes, parks request.resultTypes = .query // Suggested search queries (iOS 18+) request.resultTypes = [.pointOfInterest, .address] // Multiple types

Rate Limiting

• MKLocalSearchCompleter handles its own throttling — safe to call on every keystroke

• MKLocalSearch — Apple rate-limits these; don't fire more than ~1/second

• If rate-limited, you'll get an error in the completion handler

• Reuse MKLocalSearchCompleter instances — don't create new ones per query

Part 7: MKDirections and MKRoute

Calculate Directions

let request = MKDirections.Request() request.source = MKMapItem.forCurrentLocation() request.destination = destinationMapItem request.transportType = .automobile request.requestsAlternateRoutes = true // Get multiple routes

let directions = MKDirections(request: request) let response = try await directions.calculate()

for route in response.routes { route.polyline // MKPolyline — display on map route.expectedTravelTime // TimeInterval in seconds route.distance // CLLocationDistance in meters route.name // "I-280 S" — route name route.advisoryNotices // [String] — warnings route.steps // [MKRoute.Step] — turn-by-turn }

Transport Types

.automobile // Driving directions .walking // Pedestrian directions .transit // Public transit (where available) .any // All modes

ETA Only (Faster)

let directions = MKDirections(request: request) let eta = try await directions.calculateETA() eta.expectedTravelTime // TimeInterval eta.distance // CLLocationDistance eta.expectedArrivalDate // Date eta.expectedDepartureDate // Date eta.transportType // MKDirectionsTransportType

Turn-by-Turn Steps

for step in route.steps { step.instructions // "Turn right onto Main St" step.distance // CLLocationDistance in meters step.polyline // MKPolyline for this step's segment step.transportType // May change for transit routes step.notice // Optional advisory }

Part 8: Look Around

Check Availability

let request = MKLookAroundSceneRequest(coordinate: coordinate) do { let scene = try await request.scene // scene is non-nil — Look Around available at this coordinate } catch { // Look Around not available here }

SwiftUI

@State private var lookAroundScene: MKLookAroundScene?

LookAroundPreview(scene: $lookAroundScene) .frame(height: 200)

// Load scene func loadLookAround(for coordinate: CLLocationCoordinate2D) async { let request = MKLookAroundSceneRequest(coordinate: coordinate) lookAroundScene = try? await request.scene }

UIKit

let controller = MKLookAroundViewController(scene: scene) // Present modally or embed as child view controller

Static Snapshot

let snapshotter = MKLookAroundSnapshotter(scene: scene, options: .init()) let snapshot = try await snapshotter.snapshot let image = snapshot.image // UIImage

Part 9: Overlays and Renderers

Adding Overlays (MKMapView)

// Circle let circle = MKCircle(center: coordinate, radius: 1000) mapView.addOverlay(circle)

// Polygon let polygon = MKPolygon(coordinates: &coords, count: coords.count) mapView.addOverlay(polygon)

// Polyline let polyline = MKPolyline(coordinates: &coords, count: coords.count) mapView.addOverlay(polyline, level: .aboveRoads)

// Custom tile overlay let template = "https://tile.example.com/{z}/{x}/{y}.png" let tileOverlay = MKTileOverlay(urlTemplate: template) tileOverlay.canReplaceMapContent = true // Hides Apple Maps base layer mapView.addOverlay(tileOverlay, level: .aboveLabels)

Renderer Delegate

func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer { switch overlay { case let circle as MKCircle: let renderer = MKCircleRenderer(circle: circle) renderer.fillColor = UIColor.systemBlue.withAlphaComponent(0.2) renderer.strokeColor = .systemBlue renderer.lineWidth = 2 return renderer

case let polyline as MKPolyline:
    let renderer = MKPolylineRenderer(polyline: polyline)
    renderer.strokeColor = .systemBlue
    renderer.lineWidth = 4
    return renderer

case let polygon as MKPolygon:
    let renderer = MKPolygonRenderer(polygon: polygon)
    renderer.fillColor = UIColor.systemGreen.withAlphaComponent(0.3)
    renderer.strokeColor = .systemGreen
    renderer.lineWidth = 2
    return renderer

case let tile as MKTileOverlay:
    return MKTileOverlayRenderer(tileOverlay: tile)

default:
    return MKOverlayRenderer(overlay: overlay)
}

}

Overlay Levels

mapView.addOverlay(overlay, level: .aboveRoads) // Above roads, below labels mapView.addOverlay(overlay, level: .aboveLabels) // Above everything

Gradient Polyline

let renderer = MKGradientPolylineRenderer(polyline: polyline) renderer.setColors([.green, .yellow, .red], locations: [0.0, 0.5, 1.0]) renderer.lineWidth = 6

Part 10: Map Snapshots

Generate static map images for sharing, thumbnails, or offline display:

let options = MKMapSnapshotter.Options() options.region = MKCoordinateRegion( center: coordinate, span: MKCoordinateSpan(latitudeDelta: 0.01, longitudeDelta: 0.01) ) options.size = CGSize(width: 300, height: 200) options.scale = UIScreen.main.scale // Retina support options.mapType = .standard options.showsBuildings = true options.pointOfInterestFilter = .excludingAll // Clean map

let snapshotter = MKMapSnapshotter(options: options) let snapshot = try await snapshotter.start() let image = snapshot.image

// Draw custom annotations on snapshot UIGraphicsBeginImageContextWithOptions(image.size, true, image.scale) image.draw(at: .zero)

let pinImage = UIImage(systemName: "mappin.circle.fill")! let point = snapshot.point(for: coordinate) pinImage.draw(at: CGPoint( x: point.x - pinImage.size.width / 2, y: point.y - pinImage.size.height ))

let finalImage = UIGraphicsGetImageFromCurrentImageContext() UIGraphicsEndImageContext()

Snapshot Coordinate Conversion

// Convert coordinate to point in snapshot image let point = snapshot.point(for: coordinate)

// Check if coordinate is in snapshot bounds let isVisible = CGRect(origin: .zero, size: snapshot.image.size).contains(point)

Part 11: iOS Version Feature Matrix

Feature iOS Version

MKMapView 3.0+

MKLocalSearch 6.1+

MKDirections 7.0+

MKMarkerAnnotationView 11.0+

MKMapSnapshotter 7.0+

MKLookAroundSceneRequest 16.0+

LookAroundPreview (SwiftUI) 17.0+

SwiftUI Map (content builder) 17.0+

MapCameraPosition 17.0+

.mapSelection 17.0+

.mapCameraKeyframeAnimator 17.0+

.onMapCameraChange 17.0+

MapUserLocationButton 17.0+

MapCompass 17.0+

MapScaleView 17.0+

.mapInteractionModes 17.0+

MKLocalSearch.ResultType.query 18.0+

GeoToolbox / PlaceDescriptor 26.0+

MKGeocodingRequest 26.0+

MKReverseGeocodingRequest 26.0+

MKAddress 26.0+

Part 12: GeoToolbox and Geocoding

GeoToolbox Framework

GeoToolbox provides PlaceDescriptor — a standardized representation of physical locations that works across MapKit and third-party mapping services.

import GeoToolbox

// From address let fountain = PlaceDescriptor( representations: [.address("121-122 James's St \n Dublin 8 \n D08 ET27 \n Ireland")], commonName: "Obelisk Fountain" )

// From coordinates let tower = PlaceDescriptor( representations: [.coordinate(CLLocationCoordinate2D(latitude: 48.8584, longitude: 2.2945))], commonName: "Eiffel Tower" )

// Multiple representations let statue = PlaceDescriptor( representations: [ .coordinate(CLLocationCoordinate2D(latitude: 40.6892, longitude: -74.0445)), .address("Liberty Island, New York, NY 10004, United States") ], commonName: "Statue of Liberty" )

// From MKMapItem let descriptor = PlaceDescriptor(item: mapItem) // Returns optional

PlaceRepresentation

Enum representing a place using common mapping concepts:

Case Usage

.coordinate(CLLocationCoordinate2D)

Latitude/longitude

.address(String)

Full address string

Convenience accessors on PlaceDescriptor :

descriptor.coordinate // CLLocationCoordinate2D? descriptor.address // String? descriptor.commonName // String?

SupportingPlaceRepresentation

Proprietary identifiers for places from different mapping services:

let place = PlaceDescriptor( representations: [.coordinate(CLLocationCoordinate2D(latitude: 51.5074, longitude: -0.1278))], commonName: "London Eye", supportingRepresentations: [ .serviceIdentifiers([ "com.apple.maps": "AppleMapsID123", "com.google.maps": "GoogleMapsID456" ]) ] )

// Retrieve a specific service identifier let appleID = place.serviceIdentifier(for: "com.apple.maps")

MKGeocodingRequest — Forward Geocoding

Convert an address string to map items (address to coordinates):

guard let request = MKGeocodingRequest(addressString: "1 Apple Park Way, Cupertino, CA") else { return } let mapItems = try await request.mapItems

MKReverseGeocodingRequest — Reverse Geocoding

Convert coordinates to map items (coordinates to address):

let location = CLLocation(latitude: 37.3349, longitude: -122.0090) guard let request = MKReverseGeocodingRequest(location: location) else { return } let mapItems = try await request.mapItems

MKAddress

Structured address type used when creating MKMapItem from a PlaceDescriptor :

if let coordinate = descriptor.coordinate { let location = CLLocation(latitude: coordinate.latitude, longitude: coordinate.longitude) let address = MKAddress() let mapItem = MKMapItem(location: location, address: address) }

Geocoding vs MKLocalSearch

Need Use

Address string to coordinates MKGeocodingRequest

Coordinates to address MKReverseGeocodingRequest

Natural language place search MKLocalSearch

Autocomplete suggestions MKLocalSearchCompleter

Cross-service place identifiers PlaceDescriptor with SupportingPlaceRepresentation

Resources

WWDC: 2023-10043, 2024-10094

Docs: /mapkit, /mapkit/map, /mapkit/mklocalsearch, /mapkit/mkdirections, /geotoolbox, /geotoolbox/placedescriptor, /mapkit/mkgeocodingrequest, /mapkit/mkreversegeocodingrequest, /mapkit/mkaddress

Skills: mapkit, mapkit-diag, core-location-ref