CMAltimeter: relative and absolute altitude on iPhone and Apple Watch

Hiking, stair workouts and trail runs all want elevation, and the phone has a barometer for it. Apple's CMAltimeter documentation, read 2026-10-03, splits the job into two streams that answer different questions.

Two streams, two questions#

Apple's own example covers both: a hiking app "could use this object to track the user's elevation change over the course of a hike, or to report their current absolute altitude during the hike."

Relative altitude is relative to your first event#

Apple: "For the first altitude event delivered to your altimeter object, the value of this property is 0. Subsequent events contain a number that reflects the relative change in altitude with respect to the first reported event." Each time you start the stream, zero moves to wherever the user is standing. If a session can stop and restart, store the last value before stopping and add it back, or the climb resets mid-hike.

Calling the start method again replaces the handler: "Only the last installed handler receives events." And on a device without the hardware it fails silently: "If altitude data isn't available on the current device, this method does nothing." Hence the availability check.

Absolute altitude: which devices#

Apple repeats one sentence on the availability check, the start method and the data class: "Absolute altitude is only available on iPhone 12 and later and Apple Watch 6 or SE and later." CMAbsoluteAltitudeData adds accuracy ("The estimated uncertainty of the altimeter in meters, based on one standard deviation") and precision ("The recommended resolution for the altitude, in meters"). Use precision to decide how many digits to display; showing centimetres when Apple recommends a coarser resolution is false precision. Apple notes the altitude "can be positive or negative."

Events arrive on a schedule, not on change#

"Core Motion generates events at regular intervals (regardless of whether the data has changed)". Apple does not state the interval. Expect a steady stream of nearly identical values while the user stands still, and do not treat each event as movement.

import CoreMotion

let altimeter = CMAltimeter()
var climbed = 0.0
var last: Double?

func startClimbTracking() {
    guard CMAltimeter.isRelativeAltitudeAvailable() else { return }
    altimeter.startRelativeAltitudeUpdates(to: .main) { data, error in
        guard let metres = data?.relativeAltitude.doubleValue, error == nil else { return }
        if let previous = last, metres - previous > 0 {
            climbed += metres - previous           // gain only; tune a threshold on real data
        }
        last = metres
    }
}

func stopClimbTracking() { altimeter.stopRelativeAltitudeUpdates() }

The gain arithmetic is ours, not Apple's. Summing every small upward wiggle from a barometer will overstate a climb; most apps add a minimum step before counting. Apple publishes no noise figure for relative altitude, so the threshold is something to tune against recorded sessions.

Permission#

The class page carries the usual Core Motion warning: include NSMotionUsageDescription, because "If you don't include a usage description string, your app crashes when you call this API." authorizationStatus() arrived in iOS 11.0 and watchOS 4.0. Apple's CMAltimeter page lists no macOS version.

Pitfalls#

• Expecting zero to mean sea level. In the relative stream it means the point where this stream started.
• Restarting mid-session. The baseline resets. Carry the previous total across.
• Skipping the availability check. The start method does nothing on unsupported hardware, with no error.
• Promising absolute altitude on older phones. Apple names iPhone 12 and Apple Watch 6 or SE as the floor.
• Counting every event as movement. Events are periodic whether or not anything changed.
• Looking for history. The CMAltimeter page lists start and stop methods only, with no query for past altitude.

For stair counting without your own arithmetic, CMPedometer reports floorsAscended, which Apple sizes at approximately three meters per floor and limits to walking or running up stairs. Why hiking apps disagree on elevation gain is covered in building a hiking app.