Location & Maps
You MUST use this skill for ANY location services, mapping, geofencing, or Core Location / MapKit work.
Quick Reference
| Symptom / Task |
Reference |
| Authorization strategy (When In Use vs Always) |
See skills/core-location.md |
| Monitoring approach (continuous, significant-change, CLMonitor) |
See skills/core-location.md |
| Accuracy selection, background location |
See skills/core-location.md |
| CLLocationUpdate, CLMonitor, CLServiceSession APIs |
See skills/core-location-ref.md |
| Authorization API patterns, geofencing API |
See skills/core-location-ref.md |
Compass heading, heading reference body (headingBody) |
See skills/core-location-ref.md (Part 12) |
| Location updates never arrive |
See skills/core-location-diag.md |
| Background location stops working |
See skills/core-location-diag.md |
| Authorization always denied, geofence failures |
See skills/core-location-diag.md |
| SwiftUI Map, annotations, markers, clustering |
See skills/mapkit.md |
| MKMapView vs SwiftUI Map decision |
See skills/mapkit.md |
| Search, directions, routing |
See skills/mapkit.md |
| MapKit API: Marker, Annotation, MKLocalSearch, MKDirections |
See skills/mapkit-ref.md |
| Look Around, MKMapSnapshotter, MKMapItem |
See skills/mapkit-ref.md |
| Annotations not appearing, region jumping |
See skills/mapkit-diag.md |
| Clustering not working, search failures |
See skills/mapkit-diag.md |
| Overlay rendering, user location not showing |
See skills/mapkit-diag.md |
Decision Tree
digraph location {
start [label="Location / Maps task" shape=ellipse];
domain [label="Core Location or MapKit?" shape=diamond];
cl_type [label="Need what?" shape=diamond];
mk_type [label="Need what?" shape=diamond];
start -> domain;
domain -> cl_type [label="Core Location"];
domain -> mk_type [label="MapKit / Maps"];
cl_type -> "skills/core-location.md" [label="authorization, monitoring\nstrategy, accuracy,\nbackground location"];
cl_type -> "skills/core-location-ref.md" [label="API syntax\n(CLLocationUpdate,\nCLMonitor, CLServiceSession)"];
cl_type -> "skills/core-location-diag.md" [label="something broken\n(no updates, denied,\ngeofence not firing)"];
mk_type -> "skills/mapkit.md" [label="patterns, decisions\n(SwiftUI Map vs MKMapView,\nannotations, search)"];
mk_type -> "skills/mapkit-ref.md" [label="API syntax\n(Marker, Annotation,\nMKLocalSearch, MKDirections)"];
mk_type -> "skills/mapkit-diag.md" [label="something broken\n(annotations missing,\nregion jumping, clustering)"];
}
- Authorization strategy, monitoring approach, accuracy? →
skills/core-location.md
1a. Need specific API syntax (CLLocationUpdate, CLMonitor, CLServiceSession)? → skills/core-location-ref.md
1b. Location not working? → skills/core-location-diag.md
- Adding a map, annotations, search, directions? →
skills/mapkit.md
2a. Need specific MapKit API syntax (Marker, MKLocalSearch, MKDirections)? → skills/mapkit-ref.md
2b. Map display broken? → skills/mapkit-diag.md
- Location draining battery? → See axiom-performance (skills/energy.md)
- Background task scheduling for location? → See axiom-integration
- Privacy manifest for location? → See axiom-integration
Conflict Resolution
location vs axiom-performance: When location is draining battery:
- Try location FIRST — Excessive accuracy or continuous updates are the #1 cause.
skills/core-location.md covers accuracy selection and monitoring strategy.
- Only use axiom-performance if location settings are already correct — Profile after ruling out obvious over-tracking.
location vs axiom-integration: When implementing background location:
- Background location configuration (Info.plist, capabilities, CLServiceSession) → use location
- BGTaskScheduler for periodic location processing → use axiom-integration
location vs axiom-data: When storing or syncing location data:
- Getting location updates, geofencing → use location
- Persisting location history, CloudKit sync → use axiom-data
location vs axiom-build: When location permissions fail in simulator:
- Authorization dialogs, Info.plist keys → use location (
skills/core-location-diag.md)
- Simulator GPS simulation,
simctl location → use axiom-build
Critical Patterns
Core Location (skills/core-location.md):
- Authorization escalation strategy (When In Use first, Always later)
- Monitoring decision tree (continuous vs significant-change vs CLMonitor)
- Accuracy selection with battery impact
- Background location configuration
- Anti-patterns with time costs (premature Always authorization, unnecessary continuous updates)
Core Location API (skills/core-location-ref.md):
- CLLocationUpdate AsyncSequence (iOS 17+)
- CLMonitor condition-based geofencing (iOS 17+)
- CLServiceSession declarative authorization (iOS 18+)
- Authorization API patterns, background mode configuration
Core Location Diagnostics (skills/core-location-diag.md):
- Location updates never arrive
- Background location stops working
- Authorization always denied
- Geofence events not triggering
- Location accuracy unexpectedly poor
MapKit (skills/mapkit.md):
- SwiftUI Map vs MKMapView decision tree
- Annotation patterns (Marker, custom Annotation)
- Search (MKLocalSearch, autocomplete)
- Directions and routing
- Anti-patterns (annotations in view body, no view reuse, setRegion loops)
MapKit API (skills/mapkit-ref.md):
- SwiftUI Map API (MapCameraPosition, content builders, controls)
- MKMapView delegate patterns
- MKLocalSearch, MKDirections
- Look Around, MKMapSnapshotter
- Clustering configuration
MapKit Diagnostics (skills/mapkit-diag.md):
- Annotations not appearing (lat/lng swapped, missing delegate)
- Map region jumping/looping (updateUIView guard)
- Clustering not working (missing clusteringIdentifier)
- Search returning no results (resultTypes, region bias)
- Overlay rendering failures
Anti-Rationalization
| Thought |
Reality |
| "Just request Always authorization upfront" |
30-60% denial rate. Request When In Use first, escalate later. skills/core-location.md covers the strategy. |
| "Continuous updates are fine for my use case" |
Continuous updates drain battery even when the app doesn't need sub-second location. Use significant-change or CLMonitor. |
| "I'll use MKMapView, it's more flexible" |
SwiftUI Map covers most use cases since iOS 17. MKMapView means UIViewRepresentable boilerplate. skills/mapkit.md has the decision tree. |
| "Annotations in the view body is fine for a few items" |
Annotations recreate on every view update. Even 50 items cause hitches. Move to model with @State or @Observable. |
| "I know how geofencing works" |
CLMonitor (iOS 17+) replaces legacy region monitoring with conditions. The API changed significantly. |
| "Background location just needs the capability" |
It needs Info.plist keys, capability, CLServiceSession (iOS 18+), AND correct authorization level. Missing any one silently fails. |
| "I'll handle location errors later" |
Authorization denial is not an error — it's the default state. Handle it from the start. |
Example Invocations
User: "How do I request location permissions?"
→ Read: skills/core-location.md
User: "What's the CLLocationUpdate API?"
→ Read: skills/core-location-ref.md
User: "My location updates never arrive"
→ Read: skills/core-location-diag.md
User: "How do I add a map with pins?"
→ Read: skills/mapkit.md
User: "What's the SwiftUI Map API?"
→ Read: skills/mapkit-ref.md
User: "My annotations aren't showing on the map"
→ Read: skills/mapkit-diag.md
User: "How do I implement geofencing?"
→ Read: skills/core-location.md then skills/core-location-ref.md
User: "Location is draining battery"
→ Read: skills/core-location.md, then See axiom-performance (skills/energy.md)
User: "How do I add search to my map?"
→ Read: skills/mapkit.md then skills/mapkit-ref.md
1---2name: axiom-location-23description: "Use when implementing location services, maps, geofencing, or debugging location/MapKit issues. Covers Core Location, CLMonitor, MapKit, annotations, directions."4metadata:5 source: https://skillmd.com/skills/charleswiltgen/axiom-location-26---789# Location & Maps1011**You MUST use this skill for ANY location services, mapping, geofencing, or Core Location / MapKit work.**1213## Quick Reference1415| Symptom / Task | Reference |16|----------------|-----------|17| Authorization strategy (When In Use vs Always) | See `skills/core-location.md` |18| Monitoring approach (continuous, significant-change, CLMonitor) | See `skills/core-location.md` |19| Accuracy selection, background location | See `skills/core-location.md` |20| CLLocationUpdate, CLMonitor, CLServiceSession APIs | See `skills/core-location-ref.md` |21| Authorization API patterns, geofencing API | See `skills/core-location-ref.md` |22| Compass heading, heading reference body (`headingBody`) | See `skills/core-location-ref.md` (Part 12) |23| Location updates never arrive | See `skills/core-location-diag.md` |24| Background location stops working | See `skills/core-location-diag.md` |25| Authorization always denied, geofence failures | See `skills/core-location-diag.md` |26| SwiftUI Map, annotations, markers, clustering | See `skills/mapkit.md` |27| MKMapView vs SwiftUI Map decision | See `skills/mapkit.md` |28| Search, directions, routing | See `skills/mapkit.md` |29| MapKit API: Marker, Annotation, MKLocalSearch, MKDirections | See `skills/mapkit-ref.md` |30| Look Around, MKMapSnapshotter, MKMapItem | See `skills/mapkit-ref.md` |31| Annotations not appearing, region jumping | See `skills/mapkit-diag.md` |32| Clustering not working, search failures | See `skills/mapkit-diag.md` |33| Overlay rendering, user location not showing | See `skills/mapkit-diag.md` |3435## Decision Tree3637```dot38digraph location {39 start [label="Location / Maps task" shape=ellipse];40 domain [label="Core Location or MapKit?" shape=diamond];41 cl_type [label="Need what?" shape=diamond];42 mk_type [label="Need what?" shape=diamond];4344 start -> domain;4546 domain -> cl_type [label="Core Location"];47 domain -> mk_type [label="MapKit / Maps"];4849 cl_type -> "skills/core-location.md" [label="authorization, monitoring\nstrategy, accuracy,\nbackground location"];50 cl_type -> "skills/core-location-ref.md" [label="API syntax\n(CLLocationUpdate,\nCLMonitor, CLServiceSession)"];51 cl_type -> "skills/core-location-diag.md" [label="something broken\n(no updates, denied,\ngeofence not firing)"];5253 mk_type -> "skills/mapkit.md" [label="patterns, decisions\n(SwiftUI Map vs MKMapView,\nannotations, search)"];54 mk_type -> "skills/mapkit-ref.md" [label="API syntax\n(Marker, Annotation,\nMKLocalSearch, MKDirections)"];55 mk_type -> "skills/mapkit-diag.md" [label="something broken\n(annotations missing,\nregion jumping, clustering)"];56}57```58591. Authorization strategy, monitoring approach, accuracy? → `skills/core-location.md`601a. Need specific API syntax (CLLocationUpdate, CLMonitor, CLServiceSession)? → `skills/core-location-ref.md`611b. Location not working? → `skills/core-location-diag.md`622. Adding a map, annotations, search, directions? → `skills/mapkit.md`632a. Need specific MapKit API syntax (Marker, MKLocalSearch, MKDirections)? → `skills/mapkit-ref.md`642b. Map display broken? → `skills/mapkit-diag.md`653. Location draining battery? → See axiom-performance (skills/energy.md)664. Background task scheduling for location? → See axiom-integration675. Privacy manifest for location? → See axiom-integration6869## Conflict Resolution7071**location vs axiom-performance**: When location is draining battery:721. **Try location FIRST** — Excessive accuracy or continuous updates are the #1 cause. `skills/core-location.md` covers accuracy selection and monitoring strategy.732. **Only use axiom-performance** if location settings are already correct — Profile after ruling out obvious over-tracking.7475**location vs axiom-integration**: When implementing background location:76- Background location configuration (Info.plist, capabilities, CLServiceSession) → **use location**77- BGTaskScheduler for periodic location processing → **use axiom-integration**7879**location vs axiom-data**: When storing or syncing location data:80- Getting location updates, geofencing → **use location**81- Persisting location history, CloudKit sync → **use axiom-data**8283**location vs axiom-build**: When location permissions fail in simulator:84- Authorization dialogs, Info.plist keys → **use location** (`skills/core-location-diag.md`)85- Simulator GPS simulation, `simctl location` → **use axiom-build**8687## Critical Patterns8889**Core Location** (`skills/core-location.md`):90- Authorization escalation strategy (When In Use first, Always later)91- Monitoring decision tree (continuous vs significant-change vs CLMonitor)92- Accuracy selection with battery impact93- Background location configuration94- Anti-patterns with time costs (premature Always authorization, unnecessary continuous updates)9596**Core Location API** (`skills/core-location-ref.md`):97- CLLocationUpdate AsyncSequence (iOS 17+)98- CLMonitor condition-based geofencing (iOS 17+)99- CLServiceSession declarative authorization (iOS 18+)100- Authorization API patterns, background mode configuration101102**Core Location Diagnostics** (`skills/core-location-diag.md`):103- Location updates never arrive104- Background location stops working105- Authorization always denied106- Geofence events not triggering107- Location accuracy unexpectedly poor108109**MapKit** (`skills/mapkit.md`):110- SwiftUI Map vs MKMapView decision tree111- Annotation patterns (Marker, custom Annotation)112- Search (MKLocalSearch, autocomplete)113- Directions and routing114- Anti-patterns (annotations in view body, no view reuse, setRegion loops)115116**MapKit API** (`skills/mapkit-ref.md`):117- SwiftUI Map API (MapCameraPosition, content builders, controls)118- MKMapView delegate patterns119- MKLocalSearch, MKDirections120- Look Around, MKMapSnapshotter121- Clustering configuration122123**MapKit Diagnostics** (`skills/mapkit-diag.md`):124- Annotations not appearing (lat/lng swapped, missing delegate)125- Map region jumping/looping (updateUIView guard)126- Clustering not working (missing clusteringIdentifier)127- Search returning no results (resultTypes, region bias)128- Overlay rendering failures129130## Anti-Rationalization131132| Thought | Reality |133|---------|---------|134| "Just request Always authorization upfront" | 30-60% denial rate. Request When In Use first, escalate later. `skills/core-location.md` covers the strategy. |135| "Continuous updates are fine for my use case" | Continuous updates drain battery even when the app doesn't need sub-second location. Use significant-change or CLMonitor. |136| "I'll use MKMapView, it's more flexible" | SwiftUI Map covers most use cases since iOS 17. MKMapView means UIViewRepresentable boilerplate. `skills/mapkit.md` has the decision tree. |137| "Annotations in the view body is fine for a few items" | Annotations recreate on every view update. Even 50 items cause hitches. Move to model with `@State` or `@Observable`. |138| "I know how geofencing works" | CLMonitor (iOS 17+) replaces legacy region monitoring with conditions. The API changed significantly. |139| "Background location just needs the capability" | It needs Info.plist keys, capability, CLServiceSession (iOS 18+), AND correct authorization level. Missing any one silently fails. |140| "I'll handle location errors later" | Authorization denial is not an error — it's the default state. Handle it from the start. |141142## Example Invocations143144User: "How do I request location permissions?"145→ Read: `skills/core-location.md`146147User: "What's the CLLocationUpdate API?"148→ Read: `skills/core-location-ref.md`149150User: "My location updates never arrive"151→ Read: `skills/core-location-diag.md`152153User: "How do I add a map with pins?"154→ Read: `skills/mapkit.md`155156User: "What's the SwiftUI Map API?"157→ Read: `skills/mapkit-ref.md`158159User: "My annotations aren't showing on the map"160→ Read: `skills/mapkit-diag.md`161162User: "How do I implement geofencing?"163→ Read: `skills/core-location.md` then `skills/core-location-ref.md`164165User: "Location is draining battery"166→ Read: `skills/core-location.md`, then See axiom-performance (skills/energy.md)167168User: "How do I add search to my map?"169→ Read: `skills/mapkit.md` then `skills/mapkit-ref.md`