How to accurately query HKWorkout segment data

Question

Created 2d

Replies 2

Boosts 0

Participants 2

Hello,

In my application, I need to obtain precise workout segment data from HKWorkout in order to calculate per-kilometer metrics such as heart rate and pace.

My current approach is:

1.Use HKWorkout to fetch the associated HKWorkoutEvents.

2.Take the end time of one event as the start time of the next event to derive per-kilometer segment ranges.

The issue I’m facing:

•If a user sets Apple Watch to notify every 5 kilometers, then at 5 km, 10 km, 15 km, etc., I see overlapping event times.

•From the HKWorkoutEvents data alone, I cannot distinguish between events that represent “per-kilometer splits” and those that represent “5-kilometer notifications.”

•As a result, my per-kilometer heart rate and pace calculations can be inaccurate.

My question is:

Is there a recommended way to reliably differentiate per-kilometer splits from custom distance notifications and ensure accurate segment data retrieval?

For example, should I instead reconstruct segments using HKWorkoutRoute and distance samples, rather than relying on HKWorkoutEvents?

STEPS TO REPRODUCE

1.On Apple Watch, start an Outdoor Run using the Workout app.

2.In workout notifications, set distance alerts to every 5 kilometers.

3.During the run, when reaching 5 km, 10 km, 15 km, etc., the watch triggers notifications.

4.Query the corresponding HKWorkout from HealthKit and inspect its HKWorkoutEvents.

5.Notice that some event start times are duplicated, and it is unclear which events represent “per-kilometer splits” and which represent “5-kilometer notifications.”

Expected Result:

Be able to differentiate between per-kilometer splits and custom distance alerts, so that heart rate and pace per kilometer can be calculated accurately.

Actual Result:

The HKWorkoutEvents data contains duplicated event times without a way to distinguish event types, leading to inaccurate per-kilometer statistics.

Boost

Answer 1

DTS Engineer OP

Apple

1d

Does the discussion in this post help? If not, please share why and I'd be interested in taking another look.

Thanks,
——
Ziqiao Chen
 Worldwide Developer Relations.

0

Answer 2

KookyBread OP

1d

Thank you for sharing this article — it directly touches on the issue I’m currently facing. I have actually tried both approaches mentioned:

1.Using .distanceWalkingRunning or .distanceCycling samples to accumulate distance and determine per-kilometer (or per-mile) ranges. This is a reasonable suggestion, but it comes with a major drawback. For example, processing a 100 km cycling workout produces a very large number of samples, and the overhead becomes even greater when handling multiple workouts in bulk. In other words, this method is valid but not efficient.

2.As edorphy pointed out, Apple Watch’s Activity app does record per-kilometer and per-mile split points as HKWorkoutEvents. In my own testing, these event markers are actually more accurate than the splits derived from accumulating .distanceWalkingRunning or .distanceCycling samples.

This leads to a simple but important question: how can developers make effective use of the HKWorkoutEvents that Apple Watch already records and stores in HealthKit? In other words, is there a way to reliably distinguish these events — even when they sometimes overlap — so that they can be used as accurate split markers?

I strongly believe that the iOS Fitness app is not inefficiently recalculating splits by iterating through every distance sample. There must be a more optimal solution.

I would greatly appreciate more professional guidance on this point, and I believe a clear answer here could benefit many HealthKit developers who want to implement split statistics more efficiently.

0