Core Location Reference

Comprehensive API reference for modern Core Location (iOS 17+).

When to Use

• Need API signatures for CLLocationUpdate, CLMonitor, CLServiceSession
• Implementing geofencing or region monitoring
• Configuring background location updates
• Understanding authorization patterns
• Debugging location service issues

Related Skills

• axiom-core-location — Anti-patterns, decision trees, pressure scenarios
• axiom-core-location-diag — Symptom-based troubleshooting
• axiom-energy-ref — Location as battery subsystem (accuracy vs power)

---

Part 1: Modern API Overview (iOS 17+)

Four key classes replace legacy CLLocationManager patterns:

Class	Purpose	iOS
CLLocationUpdate	AsyncSequence for location updates	17+
CLMonitor	Condition-based geofencing/beacons	17+
CLServiceSession	Declarative authorization goals	18+
CLBackgroundActivitySession	Background location support	17+

Migration path: Legacy CLLocationManager still works, but new APIs provide:

• Swift concurrency (async/await)
• Automatic pause/resume
• Simplified authorization
• Better battery efficiency

---

Part 2: CLLocationUpdate API

Basic Usage

import CoreLocation

Task {
    do {
        for try await update in CLLocationUpdate.liveUpdates() {
            if let location = update.location {
                // Process location
            }
            if update.isStationary {
                break // Stop when user stops moving
            }
        }
    } catch {
        // Handle location errors
    }
}

LiveConfiguration Options

CLLocationUpdate.liveUpdates(.default)
CLLocationUpdate.liveUpdates(.automotiveNavigation)
CLLocationUpdate.liveUpdates(.otherNavigation)
CLLocationUpdate.liveUpdates(.fitness)
CLLocationUpdate.liveUpdates(.airborne)

Choose based on use case. If unsure, use .default or omit parameter.

Key Properties

Property	Type	Description
location	CLLocation?	Current location (nil if unavailable)
isStationary	Bool	True when device stopped moving
authorizationDenied	Bool	User denied location access
authorizationDeniedGlobally	Bool	Location services disabled system-wide
authorizationRequestInProgress	Bool	Awaiting user authorization decision
accuracyLimited	Bool	Reduced accuracy (updates every 15-20 min)
locationUnavailable	Bool	Cannot determine location
insufficientlyInUse	Bool	Can't request auth (not in foreground)

Automatic Pause/Resume

When device becomes stationary:

1. Final update delivered with isStationary = true and valid location
2. Updates pause (saves battery)
3. When device moves, updates resume with isStationary = false

No action required—happens automatically.

AsyncSequence Operations

// Get first location with speed > 10 m/s
let fastUpdate = try await CLLocationUpdate.liveUpdates()
    .first { $0.location?.speed ?? 0 > 10 }

// WARNING: Avoid filters that may never match (e.g., horizontalAccuracy < 1)

---

Part 3: CLMonitor API

Swift actor for monitoring geographic conditions and beacons.

Basic Geofencing

let monitor = await CLMonitor("MyMonitor")

// Add circular region
let condition = CLMonitor.CircularGeographicCondition(
    center: CLLocationCoordinate2D(latitude: 37.33, longitude: -122.01),
    radius: 100
)
await monitor.add(condition, identifier: "ApplePark")

// Await events
for try await event in monitor.events {
    switch event.state {
    case .satisfied:  // User entered region
        handleEntry(event.identifier)
    case .unsatisfied:  // User exited region
        handleExit(event.identifier)
    case .unknown:
        break
    @unknown default:
        break
    }
}

CircularGeographicCondition

CLMonitor.CircularGeographicCondition(
    center: CLLocationCoordinate2D,
    radius: CLLocationDistance  // meters, minimum ~100m effective
)

BeaconIdentityCondition

Three granularity levels:

// All beacons with UUID (any site)
CLMonitor.BeaconIdentityCondition(uuid: myUUID)

// Specific site (UUID + major)
CLMonitor.BeaconIdentityCondition(uuid: myUUID, major: 100)

// Specific beacon (UUID + major + minor)
CLMonitor.BeaconIdentityCondition(uuid: myUUID, major: 100, minor: 5)

Condition Limit

Maximum 20 conditions per app. Prioritize what to monitor. Swap regions dynamically based on user location if needed.

Adding with Assumed State

// If you know initial state
await monitor.add(condition, identifier: "Work", assuming: .unsatisfied)

Core Location will correct if assumption wrong.

Accessing Records

// Get single record
if let record = await monitor.record(for: "ApplePark") {
    let condition = record.condition
    let lastEvent = record.lastEvent
    let state = lastEvent.state
    let date = lastEvent.date
}

// Get all identifiers
let allIds = await monitor.identifiers

Event Properties

Property	Description
identifier	String identifier of condition
state	.satisfied, .unsatisfied, .unknown
date	When state changed
refinement	For wildcard beacons, actual UUID/major/minor detected
conditionLimitExceeded	Too many conditions (max 20)
conditionUnsupported	Condition type not available
accuracyLimited	Reduced accuracy prevents monitoring

Critical Requirements

1. One monitor per name — Only one instance with given name at a time
2. Always await events — Events only become lastEvent after handling
3. Reinitialize on launch — Recreate monitor in didFinishLaunchingWithOptions

---

Part 4: CLServiceSession API (iOS 18+)

Declarative authorization—tell Core Location what you need, not what to do.

Basic Usage

// Hold session for duration of feature
let session = CLServiceSession(authorization: .whenInUse)

for try await update in CLLocationUpdate.liveUpdates() {
    // Process updates
}

Authorization Requirements

CLServiceSession(authorization: .none)       // No auth request
CLServiceSession(authorization: .whenInUse)  // Request When In Use
CLServiceSession(authorization: .always)     // Request Always (must start in foreground)

Full Accuracy Request

// For features requiring precise location (e.g., navigation)
CLServiceSession(
    authorization: .whenInUse,
    fullAccuracyPurposeKey: "NavigationPurpose"  // Key in Info.plist
)

Requires NSLocationTemporaryUsageDescriptionDictionary in Info.plist.

Implicit Sessions

Iterating CLLocationUpdate.liveUpdates() or CLMonitor.events creates implicit session with .whenInUse goal.

To disable implicit sessions:

<!-- Info.plist -->
<key>NSLocationRequireExplicitServiceSession</key>
<true/>

Session Layering

Don't replace sessions—layer them:

how to use axiom-core-location-ref
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use axiom-core-location-ref on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add axiom-core-location-ref
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/charleswiltgen/axiom --skill axiom-core-location-refcopy
The skills CLI fetches axiom-core-location-ref from GitHub repository charleswiltgen/axiom and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/axiom-core-location-ref
Reload or restart Cursor to activate axiom-core-location-ref. Access the skill through slash commands (e.g., /axiom-core-location-ref) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?