A sample that contains a workout’s route data.


When creating a workout route, you do not instantiate the HKWorkoutRoute objects directly. Instead, create a HKWorkoutRouteBuilder object, and provide it with location data throughout the workout. After the workout ends, call finishRoute(with:metadata:completion:) to create the route.

The route’s location data is stored as an array of CLLocation objects. Because the route may contain a large number of location objects, use a HKWorkoutRouteQuery object to read the route’s location data from the HealthKit store.

Query Route Data

Unlike most HealthKit data, workout route data can change over time. The routes are associated with the workout after the workout is saved. Additionally, route data is often post processed and updated using sync identifiers. For example, you may generate the initial route data on Apple Watch, but perform additional smoothing on iPhone or your server. As a result, any query that just returns a snapshot of the current workout route data may result in incomplete or outdated information.

To guarantee that your app receives the most up-to-date route information, use an anchored object query:

let runningObjectQuery = HKQuery.predicateForObjects(from: myWorkout)

let routeQuery = HKAnchoredObjectQuery(type: HKSeriesType.workoutRoute(), predicate: runningObjectQuery, anchor: nil, limit: HKObjectQueryNoLimit) { (query, samples, deletedObjects, anchor, error) in
    guard error == nil else {
        // Handle the error here.
        fatalError("The initial query failed.")
    // Process the initial route data here.

routeQuery.updateHandler = { (query, samples, deleted, anchor, error) in
    guard error == nil else {
        // Handle the error here.
        fatalError("The update failed.")
    // Process updates or additions here.


Any additions or changes to the route data are then passed to the query's update handler.


Inherits From

Conforms To

See Also