Home

Structured workouts

  • Version: 1.0
  • Host: whats.todaysplan.com.au/rest
  • Protocols: https
  • Accepts: application/json
  • Responds With: application/json
More Info

Overview

Today’s Plan supports structured and unstructured workouts.

A structured workout is where the intervals are defined, and each interval has a duration, distance, cadence and/or pace targets.

ie 10 mins at 200 watts with 80 rpm

An unstructured workout only contains a free form text / html description of the workout.

Structured workouts are configured relative to the user. The user’s power, pace and heart rate zones table is used to calculate the specific intensity targets in each interval.

Structured workouts can be exported in a number of different formats, for use in 3rd party systems and head units.

  • zwo - export to a Zwift workout format
  • fit - export to a fit workout format which can be used on Garmin headunits and watches
  • mrc/erg - export to formats used by TrainerRoad
  • stages - export to a Stages Dash v1 format (swo)

Your application can also export the native json intervals definitions. These can be obtained using the GET /rest/plans/workouts/fragment/workout/{workoutId} or use the Activities API and request the “scheduled.intervals” field.

The Activities API to search for upcoming workouts.

Notes on structured workouts

TWorkouts vs UserWorkouts

An important concept in the Today’s Plan system is the differentiation between a TWorkout and UserWorkout.

A TWorkout is a template workout. It defines all the attributes of a workout - description, media, intervals etc.

The intervals are defined as zone ranges, ie power zone 2.3 - 3.1. There are no absolute power or heart rate references.

The TWorkout resides in a “workout library”. A TWorkout is “instantiated” against a user and date. At this point, a UserWorkout is created - and the specific wattage, pace and heart rate ranges are set relative to the user’s zone table and threshold.

TWorkout intervals can have overloads. Overloads are an increment to an interval. An overload could be on the number of reps, duration or intensity of the interval. They are applied in weekly blocks.

ie every 2 weeks, add 2 reps and 1 min to the interval.

By specifying overloads into TWorkouts you can effectivly increase the number of workouts you have access to in your library. When you instantiate a TWorkout to a user, you can select which overload week you are selecting.

Workout structure

A structured workout has a number of metadata elements;

  • type - The sport type. ie ride, run, swim
  • media - A YouTube id, or a URL to video content
  • name - A nice display name for the workout
  • preDescr - A text/html description of the workout
  • workout - tag if this workout is training or a specific test session
  • day - A unix timestamp (ms) of when this workout is scheduled
  • tz - The timezone of when this workout is scheduled
  • goals - A collection of training goals for this workout. ie strength, endurance etc
  • equipment - A collection of recommended bike choice for this workout. ie TT, MTB etc
  • terrain - A collection of recommended terrain choice for this workout. ie flat, hills etc
  • tscorepwr - The estimated TScore for this workout. This is automatically calculated from the structured intervals.
  • durationSecs - The estimated duration for this workout. This is automatically calculated from the structured intervals.
  • distance - The estimated distance for this workout. This is automatically calculated from the structured intervals.
  • pace - The overall estimated pace for this workout. This is automatically calculated from the structured intervals.
  • zoneSize - This is the power zone table size that this workout was designed for - See notes below
  • zoneHrSize - This is the heart rate zone table size that this workout was designed for - See notes below
  • zonePaceSize - This is the pace zone table size that this workout was designed for - See notes below
  • mask - A bit mask for tracking manual overrides to the tscore, duration, distance of pace - See notes below
  • ext.water - For swim workouts, should this workout be completed in a pool or open water
  • ext.poolLen - For swim workouts, the pool length this workout is designed for
  • ext.poolLenUnits - For swim workouts, the pool length this workout is designed for

Zone size notes - Structured workouts have their power, heart rate and pace intensity specific as zone ranges. Each workout is therefore designed against a specific zone table size. If you have 6 zones, then 6.9 would be maximal intensity.

However, a user may have a zones table of a different structure - they may have 7 or 8 zones. In this situation, the system will transpose the user’s zone range to the workout’s required zone size. This may not always be ideal, as the zone range are often not linear mappings.

Mask notes - although the tscore, duration, distance and pace are automatically calculated, they can be manually overriden. The mask field is a bitmask used to track manual overrides. Set the bitmask to prevent automatic recalculation

  • 0 - distance override
  • 1 - duration override
  • 2 - tscore override
  • 3 - pace override

Interval structure

An interval basically has a repetition count, a name, a volume (distance or duration), and an intensity (power/heart/pace) range. It then has an optional rest volume and intensity.

  • name - A display name for an interval. ie Effort
  • descr - A more detailed explanation of the interval
  • reps - The number of times the interval should be repeated
  • rpe - The suggested RPE for this interval
  • ord - The interval order (sort by this column to get the correct interval order)
  • durationSecs - The duration of this interval (does not include rest period)
  • distance - The distance (m) of this interval (does not include rest period)
  • pace - The pace (seconds) of this interval (does not include rest period)
  • startSpan - See notes below
  • endSpan - See notes below
  • zoneLo - The low power zone range. 1.0 - {zoneSize}.9.
  • zoneHi - The high power zone range. 1.0 - {zoneSize}.9
  • wattsLo - The wattage range based on the zone range + user’s zone table + user’s threshold
  • wattsHi - The wattage range based on the zone range + user’s zone table + user’s threshold
  • zoneHrLo - The low heart zone rate range. 1.0 - {zoneSizeHr}.9
  • zoneHrHi - The high heart zone range. 1.0 - {zoneSizeHr}.9
  • bmpLo - The heart rate range based on the zone range + user’s zone table + user’s threshold
  • bmpHi - The heart rate range based on the zone range + user’s zone table + user’s threshold
  • zonePaceLo - The low pace zone range. 1.0 - {zoneSizePace}.9.
  • zonePaceHi - The high pace zone range. 1.0 - {zoneSizePace}.9
  • paceLo - The pace rate range based on the zone range + user’s zone table + user’s threshold
  • paceHi - The pace rate range based on the zone range + user’s zone table + user’s threshold
  • cadenceLoRpm - Target cadence range for this interval
  • cadenceHiRpm - Target cadence range for this interval
  • restSecs - Rest duration (static rest is possible by not setting any rest intensity)
  • restDistance - Rest distance
  • restPace - Rest pace
  • restZone - The power zone for the rest intensity
  • restZoneHr - The heart rate zone for the rest intensity
  • restZonePace - The pace zone for the rest intensity
  • bmpRest - The bpm target (restZoneHr + user’s zone table + user’s threshold)
  • wattsRest - The wattage target (restZone + user’s zone table + user’s threshold)
  • mask - A bitmask for tracking some additional option - see below

Bitmask notes;

  • 0 - Set this bit to mark the interval as a “cycle”. Complete the duration in a set distance
  • 1 - Pin the pace calculation to duration (pace + duration will calculate distance)
  • 2 - Pin the rest pace calculation to duration

Spans

Today’s Plan intervals have the concept of an “inner” and “outer span”.

In the most simple case, all intervals are outer intervals. They are completed sequentially.

ie 3 x 2 mins @ zone 3.2 - 4.0, each with 30s rest @ zone 1

Multiple inner intervals can be set within an outer interval. What this means is that the inner intervals should be completed WITHIN the outer intervals duration/distance.

  • Main set - 2 hours @ tempo
  • Inner 1 - 2 x 30s @ vo2 with 20s rest
  • Inner 2 - 4 x 1m @ sst

In this example, the rider has a 2 hour block at a tempo intensity. At anytime within that 2 hours, they should complete 2 x 30s efforts, each with short rest. Then they should do 4 x 1 min reps. Once these inners are completed, they should return back to the tempo intensity for the remainder of the 2 hours.

The reason for model is to give a rider more flexibility as to when they complete their efforts. Often a rider will need to commute to a hill or specific area to complete their efforts. This commute is different for each athlete.

From a headunit perspective, we suggest that the user presses a lap button to transition from an outer to an inner interval. Once all the inners are complete, the interval target is back to the original outer intensity - and the time remaining is the orginal time spent in the outer, minus the time spent in the inners.