HR zone distribution from recent activities, Yousuli Help

What this is

The HR zones distribution is the time-in-zone breakdown computed across recent activities, using the athlete's sport-specific LTHR. It is a quick read on whether training is concentrated in the right intensity bands.

URL (API): GET /api/athlete/<public_id>/hr-zones/?days=<N>&sport=<sport>.

What you see

For each Yousuli HR zone (see Glossary: zones), the endpoint returns:

The zone label (Z1 Recovery through Z5 VO2 / Max).
The total time spent in that zone in the window (in minutes or hours, depending on the renderer).
The percentage of total HR-recorded time.

How it is computed

Each Activity stores its own per-second HR stream (extracted by the parser). The HR zones logic walks the stream, bins each second into the appropriate zone using the athlete's sport- specific LTHR, and aggregates across activities in the window.

Activities without HR data are skipped. Activities with HR but no LTHR for the sport are also skipped (the zones cannot be computed).

Sport selection

The zone breakdown is sport-scoped because the athlete has a separate LTHR for bike, run, and swim:

sport=bike uses bike_hr_threshold.
sport=run uses run_hr_threshold.
sport=swim uses swim_hr_threshold.

Reading the result

A typical balanced endurance program shows:

70 to 80 percent in Z1 plus Z2 (the easy aerobic base).
5 to 10 percent in Z3 (tempo / sub-threshold).
10 to 20 percent in Z4 plus Z5 (threshold and VO2max).

Heavily polarised programs push Z1+Z2 closer to 85% and Z3 close to zero. Heavily tempo-biased programs push Z3 higher at the cost of Z1+Z2.

Neither pattern is universally right; the right shape depends on the athlete and the phase.

Caveats

HR lags power by 30 to 90 seconds. For short hard intervals, HR-based time-in-zone underestimates time at the top of the power curve because HR has not caught up yet. For long steady efforts, HR-based zones are reliable.

HR zone distribution from recent activities