FIT file description

About FIT file format

FIT file is the data format Suunto provides the data from the API. The file consists majority of the data measured with Suunto products. The file contains following key elements:

  • SESSION FIELDS
  • SAMPLES (GRAPH DATA)
  • GPS TRACK
  • LAP DATA
  • POOL LENGTHS
  • EVENTS
  • PRODUCT
  • ZONES
  • MULTISPORTS
  • DEVELOPER FIELDS

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.


FIT FILE CONTENTS DESCRIPTIONS

With different fields available from different Suunto products, look at the device capability list to see what type of measurements suunto products have


ACTIVITY


SESSION

ActivityID

  • session.sport
  • session.sub_sport
  • This is the type of sport / activity. See the following Acitivity ID list with sports in Suunto products, suunto App, Movescount and how these are mapped to the FIT file ACTIVITY ID

AscentAltitude

  • session.total_ascent
  • What: Ascent Altitude is the elevation that was measured during the activity. This is cumulative value of the total ascent created during the activity.
  • How is measured:
    • 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

AvgCadence

  • session.avg_cadence
  • What: 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.
  • How is measured:
    • 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.

AvgHR

  • session.avg_heart_rate
  • What: AvgHR is the average number of heart beats measured during the activity
  • How is measured:
    • 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

AvgSpeed

  • session.avg_speed
  • AvgSpeed is the average of the speed measured during activity
  • How is measured:
    • 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

AvgTemp

  • session.avg_temperature
  • AvgTemp is the average temperature measured during the activity
  • How is measured:
    • Temperature capability is in Suunto watches that have barometric sensor

AvgPower

  • session.avg_power
  • AvgPower is the average power measured during the cycling or running session.
  • How is measured:
    • 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.

DescentAltitude

  • session.total_descent
  • What: Descent Altitude is the decline that was measured during the activity. This is cumulative value of the total decline created during the activity.
  • How is measured:
    • 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

Distance

  • session.total_distance
  • What: Distance is the distance measured during the activity. The distance is measured with
  • 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

Duration

  • session.total_timer_time
  • What: Duration is the duration measured during the activity.
  • 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.

Energy

  • session.total_calories
  • What: Energy consumption evaluated based on measured heart rate, work volume from speed, power values.
  • How is measured:
    • Depends of the users weight, gender and other personal parameters. The energy values are different between various apps/services

HighAltitude

  • session.max_altitude
  • What: Highest altitude reached during the workout.
  • How is measured:
    • 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

LowAltitude

  • session.min_altitude
  • What: Lowest altitude reached during the workout.
  • How is measured:
    • 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

MaxCadence

  • session.max_cadence
  • What: Maximum cadence is the cadence reached during the workout
  • How is measured:
    • Cadence is measured based on watch activity senor or external speed sensors in cycling or running

MaxSpeed

  • session.max_speed
  • What: MaxSpeed is the maximum of the speed reached during the activity
  • How is measured:
    • 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

MaxTemp

  • session.max_temperature
  • What:MaxTemp is the maximum temperature reached during the activity
  • How is measured:
    • 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.

MaxPower

  • session.max_power
  • MaxPower is the maximum power measured during the cycling or running session
  • How is measured:
    • 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

MinHR

  • session.min_heart_rate
  • What: MinHR is the lowest heart rate measured during the activity
  • How is measured:
    • 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

PeakHR

  • session.max_heart_rate
  • What: PeakHR is the maximun heart rate reached during the activity
  • How is measured:
    • Peak heart rate is highest value heart rate value measured during activity

PeakTrainingEffect

  • session.total_training_effect
  • What: PeakTrainingEffect is the value defining the impact of the training session
  • How is measured:
    • 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

UTCStartTime

  • session.start_time
  • What: The local start time in UTC format

Pool Lengths

  • 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_lengtht Number of pool lengths swum.

SAMPLE DATA (GRAPHS)

IBIData

  • hrv.time (timestamp)
  • 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.

Track

  • record.position_lat
  • record.position_lon
  • The track information in latitude and longntude
  • 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

  • record.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

  • record.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 storead 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

  • record.cadence
  • Cadence values are stored from external sensor
  • The cadence values are stored each second or every 10 seconds

Distance

  • record.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.

EnergyConsumption

  • record.calories
  • The calory values are stored each second or every 10 seconds

HeartRate

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

Power

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

LAP DATA

Lap times

  • lap.timestamp - timestamp when lap ended.
  • lap.total_elapsed_time - duration of lap including pauses.
  • lap.total_timer_time - duration of lap excluding pauses.

Lap data

  • lap.min_altitude - minimum altitude reached during the lap.
  • lap.avg_altitude - average altitude during the lap.
  • lap.max_altitude - maximum altitude reached during the lap.
  • lap.total_ascent - total ascent in the lap.
  • lap.total_descent - total descent in the lap.
  • lap.avg_cadence - average cadence in the lap.
  • lap.max_cadence - maximum cadence reached during the lap.
  • lap.total_distance - total distance covered during the lap.
  • lap.min_heart_rate - mimium heartrate reached during the lap.
  • lap.avg_heart_rate - average heart rate during the lap.
  • lap.total_calories - total calories during the lap.
  • lap.max_heart_rate - maximum heart rate reached during the lap.
  • lap.avg_power - average power during the lap.
  • lap.max_power - maximum power reached during the lap.
  • lap.avg_speed - average speed during the lap.
  • lap.max_speed - maximum speed reached during the lap.
  • lap.swim_stroke - total number of strokes in lap.
  • lap.avg_temperature - average temperature during the lap.
  • lap.max_temperature - maximum temperature reached during the lap.

Lap Events - Triggers

  • What: 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. Laps are marked as events and triggers with following logic:

    • Manual lap - FIT lap event: LAP, FIT lap trigger: MANUAL.
    • Distance autolap - FIT lap event: LAP, FIT lap trigger: DISTANCE.
    • Duration autolap - FIT lap event: LAP, FIT lap trigger: TIME.
    • Vertical lap (downhills) - FIT lap event: LAP, FIT lap trigger: FITNESS_EQUIPMENT.
    • Interval - FIT lap event: LAP, FIT lap trigger: FITNESS_EQUIPMENT

POOL LENGTHS

  • length.timestamp - Timestamp when lap ended.
  • length.start_time - Timestamp when lap started.
  • length.total_elapsed_time - Duration of pool length including pauses.
  • length.total_timer_time - Duration of pool length excluding pauses.
  • length.length_type - Always ACTIVE.
  • length.event - Always LENGTH.
  • length.event - Always LENGTH.
  • length.event_type - Always STOP.
  • length.avg_speed - Speed in pool length
  • length.swim_stroke - Swimming style during the pool length (FREESTYLE, BACKSTROKE, BREASTSTROKE, BUTTERFLY, DRILL).
  • length.avg_swimming_cadence - Average stroke rate during the pool length.
  • length.total_strokes - Total number of strokes during the pool length..
  • length.total_calories - Total calories during the pool length..

EVENTS

  • event.timestamp - timestamp of the event.
  • event.event - Always TIMER.
  • event.event_type - START at start of workout and end of pauses. STOP at end of workout and start of pauses.

PRODUCT

  • file_id.manufacturer - Company id. This case Suunto is 23.
  • file_id.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
  • file_id.product_name - Product name as a string.

ZONES

  • Each of the below are an 5 element array of seconds, ordered from zone 1 to zone 5.

  • session.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.

  • session.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.
  • session.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.

MULTISPORTS

  • Multisports have many sessions instead of the normal single one. Currently the sessions made from multisports have fewer fields than from single sport:
    • session.start_time
    • session.total_timer_time
    • session.total_elapsed_time
    • session.sport
    • session.sub_sport

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.

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

The developer fields are:

  • length.avg_swolfg - Swolf for each pool lenght. Only in swimming in the pool - Same as session.avg_swolf but for a single pool length.
  • record.epoc - Epoc samples (Graph of the epoc) from the whole workout - Float,range 0 - 1000, one decimal accuracy, unit is l/kg.
  • session.feeling - Integer, range 1-5, values describe feeling from worst (1) to best (5). User gives this after the excercise session at end of the workout.
  • session.description - 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.
  • session.recovery_time - Integer, range 0 - 315360000, unit is seconds. Recovery time illustrates the training load from each workout with a needed time to recover.
  • session.avg_swolf - 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.
  • session.peak_epoc - 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.
  • session.session.estimated_vo2_max - Float, range 0 - 100, one decimal accuracy, unit is ml/min/kg.
  • session.max_depth - Float, range 0 - 13000, 0.2 meter accuracy, unit is meters. Depth of the Dive. How deep did the diver go during the dive.
  • session.dive_number_in_series - Integer, range 0 - 254. How many dives diver has done in the series.
  • session.dive_mode - 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
  • session.surface_time Float, range 0 - 315360000, one decimal accuracy, unit is seconds. Duration the diver has been on the water surface.

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

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

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