FIT file description

FIT file is the data format Suunto provides the data from the API. The file consists majority of the data measured with Suunto products.

FIT or Flexible and Interoperable Data Transfer is a file format used for GPS tracks and routes. It is used by Garmin fitness GPS devices, as well as many other manufactures for data transfer.

Format description and SDK can be found here:

FIT SDK

Activity messages

timestamp

UTC timestamp when the activity ended.

`local_timestamp`

Local timestamp when the activity ended.

Meant for determining the UTC offset of times in the file. The UTC offset is the local time difference to UTC when the exercise started.

See here for details:

FIT SDK page

Session messages

Contains information about a workout session doing one kind of sport.

Typical FIT files have a single session message since it's most common to do single sport during workout, for example running.

Multi-sports activities have many session messages, for example triathlon.

Note that currently the sessions made from multi-sports have fewer fields than from single sport:

start_time
total_timer_time
total_elapsed_time
sport / sub_sport

sport / sub_sport

The type of sport / activity.

See the following Activity ID list with sports in Suunto products, Suunto App, Movescount and how these are mapped to the FIT files:

Suunto Activity IDs

total_ascent

Ascent Altitude is the elevation that was measured during the activity. This is cumulative value of the total ascent created during the activity.

Measurement:

Altitude measurement is based on barometric sensor or data from GPS.
Some of the Suunto products which have barometric sensor can combine the gps and barometric to get the best possible value, this combination is called Fused Alti
If one has used pause during activity, the altitude change during the pause is not part of the ascent

avg_cadence

Cadence as round per minute is the number of revolutions in minute done in average during cycling /indoor cycling / mountainbiking or number of steps (pair of steps / step with same leg) in running /walking / hiking /trekking/treamdill running/ trail running.

Measurement:

Cadence in cycling requires separate sensors such as Suunto bike sensor or power meter.
Cadence in running is measured from external running sensor and if not available directly from wrist
The average cadence doesn't consider 0 values in average. the average cadence is calculated only from cadence values that are not 0.
If user has paused the exercise the data is not measured / stored from that period.
Typical values are between 0 - 200.

avg_heart_rate

The average number of heart beats measured during the activity.

Measurement:

Heart rate measurement is based either on heart rate belt kept on the chest or directly from wrist via optical heart rate sensor.
Typical values are between 50 - 220.

avg_speed

The average of the speed measured during activity.

Measurement:

Speed is measured based on GPS data, external speed sensors in cycling i.e. Suunto bike sensor and running or using acceleration in swimming to measure speed in pool.
Pool swim speed is based on identification of each turn and using the pool lenght to evaluate the speed of the swimmer.

avg_temperature

The average temperature measured during the activity

Measurement:

Temperature capability is in Suunto watches that have barometric sensor.

avg_power

The average power measured during the cycling or running session.

Measurement:

Power is measured with cycling power sensor or running power sensor. Cycling power is usually in cycling, mountain cycling and indoor dycling. Running treadmill, running and trail running
Average power measured with Suunto devices do not have 0 values. For example when person rides uphill and the coasts downhill, (doesn't pedal) the average power is the power on the uphill.

total_descent

Descent Altitude is the decline that was measured during the activity. This is a cumulative value of the total decline created during the activity.

Measurement:

Altitude measurement is based on barometric sensor or data from GPS.
Some of the Suunto products which have barometric sensor can combine the gps and barometric to get the best possible value, this combination is called Fused Alti.
If one has used pause during activity, the altitude change during the pause is not part of the descent.

total_distance

Distance is the distance measured during the activity.

Measurement:

Distance is measured based on GPS data, external sensors in cycling i.e. Suunto bike sensor and running or using acceleration in swimming to measure speed in pool.
Pool swim distance is based on identification of each turn and using the pool lenght to evaluate the the distance of the swimmer

total_timer_time

The duration measured during the activity.

Measurement:

Duration is the duration between start time and stop time. If there is pause during the activity, its removed from total duration. The duration is not related to moving time.
session.total_elapsed_time
What: Elapsed time is the total time elapsed between start and stop time, including pauses.
Elapsed time is the total elapsed time between start time and stop time. If there is pause during the activity, its included to the elapsed time. The value is not related to moving time.

total_calories

Energy consumption evaluated based on measured heart rate, work volume from speed, power values.

Measurement:

Depends of the users weight, gender and other personal parameters. The energy values are different between various apps/services.

max_altitude

Highest altitude reached during the workout.

Measurement:

Altitude measurement is based on barometric sensor or data from GPS.
Some of the Suunto products which have barometric sensor can combine the GPS and barometric to get the best possible value, this combination is called Fused Alti.

min_altitude

Lowest altitude reached during the workout.

Measurement:

Altitude measurement is based on barometric sensor or data from GPS.
Some of the Suunto products which have barometric sensor can combine the GPS and barometric to get the best possible value, this combination is called Fused Alti.

max_cadence

The maximum cadence reached during the workout.

Measurement:

Cadence is measured based on watch activity senor or external speed sensors in cycling or running

max_speed

The maximum of the speed reached during the activity.

Measurement:

Speed is measured based on GPS data, external speed sensors in cycling i.e. Suunto bike sensor and running or using acceleration in swimming to measure speed in pool.
Pool swim speed is based on identification of each turn and using the pool lenght to evaluate the speed of the swimmer.

max_temperature

The maximum temperature reached during the activity.

Measurement:

Suunto products which have barometric sensor have a capability to measure temperature. As the Suunto watches are usually kept on wrist, the temperature can differ considerably from outdoor weather temperature. In some sports the watch is place in location where the temperature measurement doesnt have a problems i.e. when placing in bike handlebar.

max_power

The maximum power measured during the cycling or running session.

Measurement:

Power is measured with cycling power sensor or running power sensor. Cycling power is usually in cycling, mountain cycling and indoor dycling. Running treadmill, running and trail running.

min_heart_rate

The lowest heart rate measured during the activity.

Measurement:

Heart rate measurement is based either on heart rate belt kept on the chest or directly from wrist via optical heart rate sensor.
Typical values are between 50 - 220.

max_heart_rate

The maximum heart rate reached during the activity.

Measurement:

Peak heart rate is highest value heart rate value measured during activity.

total_training_effect

PeakTrainingEffect is the value defining the impact of the training session.

Measurement:

PeakTrainingEffect rate measurement is based either on heart rate belt kept on the chest or directly from wrist via optical heart rate sensor.
Typical values are between 50 - 220.

start_time

The local start time in UTC format

pool_length_unit

METRIC if pool distance is in meters.

STATUTE if pool distance is in yards.

Typical values are between 25m or 25 yards and 50m or 50 yards.

pool_length

Length of pool in meters or yards depending on the pool_length_unit.

active_length

Number of pool lengths swum.

time_in_hr_zone

Duration during the workout in five heart rate zones. HR zones can be set by the user and by the sport.

The fields contains a 5 element list of durations in seconds ordered from zone 1 to zone 5.

time_in_speed_zone

Duration during the workout in five speed or pace zones. Zones can be set by the user and by the sport.

The fields contains a 5 element list of durations in seconds ordered from zone 1 to zone 5.

time_in_power_zone

Duration during the workout in five power zones. Zones can be set by the user and by the sport. Power is available in cycling and running sports.

The fields contains a 5 element list of durations in seconds ordered from zone 1 to zone 5.

feeling (Standard Suunto Developer Field)

Integer, range 1 - 5.

Values describe feeling from worst (1) to best (5). User gives this after the exercise session at end of the workout.

description (Standard Suunto Developer Field)

String.

Suunto watches create in the watch automatically summary string from interval sessions. Can also be written by user after the session with the Suunto App.

recovery_time (Standard Suunto Developer Field)

Integer, range 0 - 315360000, unit is seconds.

Recovery time illustrates the training load from each workout with a needed time to recover.

avg_swolf (Standard Suunto Developer Field)

Float, range 0 - 600, two decimal accuracy.

Swolf illustrates the swimming technique. This is based on number of strokes done as well as the swim pace swimmer has.

peak_epoc (Standard Suunto Developer Field)

Float, range 0 - 6000, one decimal accuracy, unit is l/kg.

Epoc value from each session. Epoc means Excess Post-Exercice Oxygen Consumption. It informs about the training load the workout had.

estimated_vo2_max (Standard Suunto Developer Field)

Float, range 0 - 100, one decimal accuracy, unit is ml/min/kg.

max_depth (Standard Suunto Developer Field)

Float, range 0 - 13000, 0.2 meter accuracy, unit is meters.

Depth of the Dive. How deep did the diver go during the dive.

dive_number_in_series (Standard Suunto Developer Field)

Integer, range 0 - 254.

How many dives diver has done in the series.

dive_mode (Standard Suunto Developer Field)

Integer, range 0 - 10.

Dive mode used in diving:

OFF = 0 GAUGE = 1 FREE = 2 AIR = 3 EAN = 4 MIXED = 5 CCR = 6 NITROX = 7 TRIMIX = 8 CCR_NITROX = 9 CCR_TRIMIX = 10

surface_time (Standard Suunto Developer Field)

Float, range 0 - 315360000, one decimal accuracy, unit is seconds.

Duration the diver has been on the water surface.

HRV messages

time

Sample from each heart rate beat to beat values. Also called as R-R values.

With heart rate of 60 beats a minute, there is 60 values in minute. If the heart rate is 120 in minute, there are 120 values.

Record messages

position_lat / position_lon

The track information in latitude and longitude.

Measurement:

Measured with GPS devices.
The GPS points on the track is based on device settings. Maximum recording rate is point from each second. There is possibility to have less track points i.e. every 10s or every minute. (Usually used on longer session where the device battery is wanted to last longer).

speed

Recorded speed values. The values stored are the speed values ie. measured with fused speed, cycling sensor. If not avaialble the GPS speed is used for the speed samples.

The number of values are based on the GPS fix rate if based on GPS. Otherwise the sample volume can be by each second or every 10 seconds.

altitude

Altitude values. The altitude values are stored by barometric sensor and useing the fused alti algorithm. If not available then the GPS altitude data is stored as samples.

The number of values are based on the GPS fix rate if based on GPS. Otherwise the sample volume can be by each second or every 10 seconds.

cadence

Cadence values are stored from external sensor.

The cadence values are stored each second or every 10 seconds.

distance

Recorded distance values. The values stored are measured with GPS, using accelerometer, cycling or running sensors.

The number of values are based on the GPS fix rate if based on GPS. Otherwise the sample volume can be by each second or every 10 seconds when using other measurements.

calories

The calorie values are stored each second or every 10 seconds.

heart_rate

The heart rate values are stored each second or every 10 seconds.

power

The power values are stored each second or every 10 seconds.

epoc (Standard Suunto Developer Field)

Float,range 0 - 1000, one decimal accuracy, unit is l/kg.

Epoc samples.

Lap messages

timestamp

Timestamp when lap ended.

total_elapsed_time

Duration of lap including pauses.

total_timer_time

Duration of lap excluding pauses.

min_altitude

Minimum altitude reached during the lap.

avg_altitude

Average altitude during the lap.

max_altitude

Maximum altitude reached during the lap.

total_ascent

Total ascent in the lap.

total_descent

Total descent in the lap.

avg_cadence

Average cadence in the lap.

max_cadence

Maximum cadence reached during the lap.

total_distance

Total distance covered during the lap.

min_heart_rate

Mimium heartrate reached during the lap.

avg_heart_rate

Average heart rate during the lap.

total_calories

Total calories during the lap.

max_heart_rate

Maximum heart rate reached during the lap.

avg_power

Average power during the lap.

max_power

Maximum power reached during the lap.

avg_speed

Average speed during the lap.

max_speed

Maximum speed reached during the lap.

swim_stroke

Total number of strokes in lap.

avg_temperature

Average temperature during the lap.

max_temperature

Maximum temperature reached during the lap.

event

Type of event. For example, the type is LAP for lap events.

event_type

Specifies more information about the event. For example, the event type is STOP when a lap ends.

lap_trigger

Trigger that caused the lap to be generated. For example MANUAL if user pressed a button manually on a watch to create a lap.

Suunto devices create lap data based on pressing a lap button, triggering automatically laps based on defined duration or distance, creating laps from each vertical slope in downhill skiing and from defined interval sessions.

The following lap_trigger values are used:

MANUAL - Manual laps.
DISTANCE - Distance auto-laps.
DURATION - Duration auto-laps.
FITNESS_EQUIPMENT - Intervals and downhills.

The laps generated by Suunto always have the value LAP in event and the value STOP in event_type.

Length messages

timestamp

Timestamp when lap ended.

start_time

Timestamp when lap started.

total_elapsed_time

Duration of pool length including pauses.

total_timer_time

Duration of pool length excluding pauses.

length_type

Always ACTIVE.

event

Always LENGTH.

event_type

Always STOP.

avg_speed

Average speed during a pool length.

swim_stroke

Swimming style during the pool length (FREESTYLE, BACKSTROKE, BREASTSTROKE, BUTTERFLY, DRILL).

avg_swimming_cadence

Average stroke rate during the pool length.

total_strokes

Total number of strokes during the pool length.

total_calories

Total calories during the pool length.

avg_swolf (Standard Suunto Developer Field)

Swolf for each pool length. Only in swimming in the pool.

Same as avg_swolf in session messages but for a single pool length.

Event messages

timestamp

Timestamp of the event.

event

Always TIMER.

event_type

START at start of workout and at end of pauses.

STOP at end of workout and start of pauses.

File ID messages

manufacturer

Company id. This case Suunto is 23.

product

Each product has an ID number. Check the list of product IDs, their compatibility with Suunto digital systems and the product measurement capabibilities HERE.

product_name

Product name as a string.

Standard Suunto Developer Fields

These developer fields consists of values that are specific for Suunto watches and mobile apps. As Suunto watch features get richer, new developer fields will get added.

The application ID used in the related DeveloperDataId -message is:

83, 117, 117, 110, 116, 111, 70, 105, 116, 69, 120, 112, 111, 114, 116, 49

Check out the the following code example on how to decode developer fields including these standard Suunto -fields:

Code example

SuuntoPlus Developer Fields

SuuntoPlus apps run on the watch while recording a workout and generate output values for the workout. There can be multiple SuuntoPlus apps running during a workout and each app may generate multiple output values.

These output values are exported to FIT files as 32 bit floating point numbers in 'developer fields'.

The SuuntoPlus 'Summary Outputs' are in 'session' message and 'Channels' are in 'record' messages.

Note that if there are multiple 'session' messages (multisport), these fields are left out completely due to incompatibility.

To know all the latest SuuntoPlus features and what they do, please visit suunto.com/suuntoplus.

Check out the code example on how to decode developer fields including the SuuntoPlus -fields!

DeveloperFields

Contains the standard FIT fields:

developer_data_index - Refers to a DeveloperDataId message. (App that generated the field)
field_definition_number - Refers to FieldDescription -message.
value - A single value as 32 bit float.

SuuntoPlus developer fields can be found inside session messages or record messages.

FieldDescription -messages

Contains the standard FIT field description message fields:

developer_data_index - Refers to a DeveloperDataId message. (App that generated the field)
field_definition_number - Id number. This number and developer_data_index are used in developer fields to refer to a specific description message.
field_name - variable name for the output.
units - the unit of measurement as a string.
fit_base_type_id - always float32.

There are also two developer fields inside this message that provide additional information:

suuntoplus_field_label
suuntoplus_field_format

See SUUNTOPLUS METADATA DEVELOPER FIELDS -section below for details on the above fields

DeveloperDataId -messages

Contains the standard FIT fields:

developer_data_index - identifies the message (the application that generated the developer field)
application_id is a 16 byte identifier.

SuuntoPlus application_ids always start with the bytes:

-34, 19, -42, -88, -103, -61, -63, -99

The last 8 bytes are an ASCII encoded application specific id.

Examples

1. Strava Relative Effort

DeveloperDataId -message:

developer_data_index: 2
application_id: -34, 19, -42, -88, -103, -61, -63, -99, 122, 122, 115, 116, 114, 97, 48, 49

FieldDescription -message:

developer_data_index: 2
field_definition_number: 0
field_name: "relative_effort"
units: "" (this field doesnt have any information as the Relative effort value doesn't have a unit)
fit_base_type_id: Float32
suuntoplus_field_label: "Relative Effort" (developer field)
suuntoplus_field_format: "Count_Fourdigits" (developer field)

DeveloperField in Session:

developer_data_index: 2
field_definition_number: 0
value: 50.0

2. TrainingPeaks Normalized Power

DeveloperDataId -message:

developer_data_index: 3
application_id: -34, 19, -42, -88, -103, -61, -63, -99, 122, 122, 116, 114, 112, 114, 48, 49

FieldDescription -message:

developer_data_index: 3
field_definition_number: 1
field_name: "np"
units: "watts"
fit_base_type_id: Float32
suuntoplus_field_label: "Normalized Power" (developer field)
suuntoplus_field_format: "Power_Fourdigits" (developer field)

DeveloperField in Session:

developer_data_index: 3
field_definition_number: 1
value: 230.0

3. Fluids (hypothetical example)

Hypothetical example of SuuntoPlus feature which would track how much one consumed sports drinks during the workout.

This would be shown in Suunto watch during and after workout as "Fluids 2.3 L"

DeveloperDataId -message:

developer_data_index: 4
application_id: -34, 19, -42, -88, -103, -61, -63, -99, 122, 122, 102, 108, 117, 105, 100, 115

FieldDescription -message:

developer_data_index: 4
field_definition_number: 0
field_name: "fluids_result"
units: "L"
fit_base_type_id: Float32
suuntoplus_field_label: "Fluids" (developer field)
suuntoplus_field_format: "Onedecimal" (developer field)

DeveloperField in Session:

developer_data_index: 4
field_definition_number: 0
value: 2.3

SuuntoPlus Metadata Developer Fields

The developer fields are:

session.suuntoplus_plugin_owner_id - String[], 1 - 10 strings, 1 - 64 characters each. The client ids who uploaded the Suuntoplus plugin (Guides) that were used during the workout.
session.suuntoplus_plugin_external_id - String[], 1 - 10 strings, 1 - 64 characters each. The external ids of the Suuntoplus plugin (Guides) that were used during the workout.
{suuntoplus field FieldDescription -message}.suuntoplus_field_label - a human readable label for a Suuntoplus field.
{suuntoplus field FieldDescription -message}.suuntoplus_field_format - a string identifying how the field should be formatted. See here for details.

The application id of the related DeveloperDataId -message is:

83, 117, 117, 110, 116, 111, 70, 105, 116, 69, 120, 112, 111, 114, 116, 49

Example of owner and external IDs

DeveloperDataId -message:

developer_data_index: 0
application_id: 83, 117, 117, 110, 116, 111, 70, 105, 116, 69, 120, 112, 111, 114, 116, 49

FieldDescription -messages:

developer_data_index: 0
field_definition_number: 2
field_name: "suuntoplus_plugin_owner_id"
units: null
fit_base_type_id: String

developer_data_index: 0
field_definition_number: 3
field_name: "suuntoplus_plugin_external_id"
units: null
fit_base_type_id: String

DeveloperFields in Session:

developer_data_index: 0
field_definition_number: 2
value: "54e90a8c-422a-4e06-a9b3-5eee1b57db85"

developer_data_index: 0
field_definition_number: 3
value: "61436b0c8a885ea1f4ed5351"

Identifying if a your Suuntoplus Guide was used during a workout

When creating a guide, set a value to the 'externalId' field.
Find your 'client id' from OAuth settings in user profile. See https://apizone.suunto.com/how-to-start.
When parsing a FIT file, find the client id(s) from session.suuntoplus_plugin_owner_id -array and take note of their indices.
Use the found indices to find the external ids from session.suuntoplus_plugin_external_id -array.
Compare the found external ids with the one you've set in Guide 'externalId' field.