axiom-mapkit-ref
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 scenariosaxiom-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
MKLocalSearchCompleterhandles its own throttling — safe to call on every keystrokeMKLocalSearch— Apple rate-limits these; don't fire more than ~1/second- If rate-limited, you'll get an error in the completion handler
- Reuse
MKLocalSearchCompleterinstances — 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