ios-mapkit_skill

Overview

This skill provides a practical guide to implement MapKit in iOS 17+ SwiftUI apps. It covers map display, camera control, markers/annotations, Core Location integration, routing with MKDirections, local search, geocoding, Look Around, and custom overlays. The focus is on concise, copy-pasteable patterns and permission handling required for production apps.

How this skill works

It explains required Info.plist keys and shows how to wire CLLocationManager to SwiftUI via an Observable object for authorization and location updates. The skill demonstrates the new iOS 17 Map APIs: Map, MapCameraPosition, MapStyle, Marker, Annotation, and Map controls. It also provides async/await examples for MKDirections, MKLocalSearch, CLGeocoder, and MKLookAroundScene requests, plus examples to render polylines, circles, and polygons on the map.

When to use it

• Add a map view in a SwiftUI iOS 17+ app
• Show and track user location with proper permissions
• Add markers, custom annotations, or overlays (circles/polygons)
• Calculate and display routes with MKDirections
• Search nearby places with MKLocalSearch or provide search suggestions
• Embed Look Around previews for street-level context

Best practices

• Declare NSLocationWhenInUseUsageDescription (and NSLocationAlwaysAndWhenInUseUsageDescription if needed) in Info.plist before requesting permission
• Request authorization via CLLocationManager and react to authorization changes in the UI
• Use MapCameraPosition (.userLocation, .region, .camera) to provide expected camera behavior and fallbacks
• Perform network and MapKit operations with async/await and handle MKError/CLError gracefully
• Limit POI types and use mapStyle POI filtering to reduce clutter and improve performance
• Respect user privacy: show rationale, direct to Settings on denied, and avoid background location unless necessary

Example use cases

• Basic Map view showing markers and a MapUserLocationButton using Map(position:)
• LocationManager observable that requests authorization and updates user coordinates in SwiftUI
• Calculate route between two coordinates with MKDirections and render it as a MapPolyline
• Run a nearby restaurants search with MKLocalSearch and display results as markers
• Forward and reverse geocoding using CLGeocoder to convert between addresses and coordinates
• Fetch MKLookAroundScene for a coordinate and show LookAroundPreview when available