FIT Record Fields Reference
This document lists all the fields available in FIT Record messages that can be extracted using this decoder.
Overview
Your FIT decoder now supports extracting 96 different fields from FIT Record messages. These fields cover everything from basic activity data to advanced physiological metrics, diving parameters, and e-bike telemetry.
Field Categories
Basic Fields
Always present in records with valid data:
timestamp
(integer) - Record timestamp in FIT time formataltitude
(float) - Altitude in metersdistance
(float) - Cumulative distance in metersheart_rate
(integer) - Heart rate in beats per minute
Position & Navigation
GPS and movement data:
position_lat
(integer) - Latitude in semicircles (divide by 2^31 * 180 for degrees)position_long
(integer) - Longitude in semicircles (divide by 2^31 * 180 for degrees)enhanced_altitude
(float) - High-resolution altitude in metersspeed
(float) - Speed in meters per secondenhanced_speed
(float) - High-resolution speed in m/sgrade
(float) - Grade/slope as percentagevertical_speed
(float) - Vertical speed in m/sgps_accuracy
(integer) - GPS accuracy in meters
Power & Performance
Cycling power and efficiency metrics:
power
(integer) - Instantaneous power in wattsaccumulated_power
(integer) - Total accumulated power in wattsmotor_power
(integer) - E-bike motor power in wattsleft_torque_effectiveness
(float) - Left leg torque effectiveness percentageright_torque_effectiveness
(float) - Right leg torque effectiveness percentageleft_pedal_smoothness
(float) - Left pedal smoothness percentageright_pedal_smoothness
(float) - Right pedal smoothness percentagecombined_pedal_smoothness
(float) - Combined pedal smoothness percentage
Cadence & Cycling
Pedaling and cycling-specific metrics:
cadence
(integer) - Cadence in revolutions per minutecadence256
(float) - High-resolution cadence in RPMfractional_cadence
(float) - Fractional component of cadenceleft_right_balance
(integer) - Power balance between left/right legscycle_length
(float) - Length per stroke/pedal cyclecycle_length16
(float) - 16-bit resolution cycle lengthcycles
(integer) - Number of cycles in this recordtotal_cycles
(integer) - Cumulative total cycles
Running Dynamics
Advanced running form metrics:
vertical_oscillation
(float) - Vertical oscillation in millimetersstance_time
(float) - Ground contact time in millisecondsstance_time_percent
(float) - Stance time as percentage of stridestance_time_balance
(float) - Left/right ground contact balancestep_length
(float) - Step length in millimetersvertical_ratio
(float) - Vertical oscillation to step length ratio
Physiological Data
Body metrics and wellness data:
calories
(integer) - Calories burnedtemperature
(integer) - Ambient temperature in Celsiuscore_temperature
(float) - Core body temperature in Celsiusrespiration_rate
(integer) - Breathing rate in breaths per minuteenhanced_respiration_rate
(float) - High-resolution respiration ratecurrent_stress
(float) - Current stress level
Blood/Oxygen Data
Advanced physiological monitoring:
total_hemoglobin_conc
(float) - Total hemoglobin concentrationtotal_hemoglobin_conc_min
(float) - Minimum hemoglobin concentrationtotal_hemoglobin_conc_max
(float) - Maximum hemoglobin concentrationsaturated_hemoglobin_percent
(float) - Blood oxygen saturation (SpO2) percentagesaturated_hemoglobin_percent_min
(float) - Minimum SpO2 percentagesaturated_hemoglobin_percent_max
(float) - Maximum SpO2 percentage
E-bike Specific
Electric bicycle telemetry:
battery_soc
(float) - Battery state of charge percentageebike_travel_range
(integer) - Estimated remaining rangeebike_battery_level
(integer) - Battery level percentageebike_assist_mode
(integer) - Current assist mode settingebike_assist_level_percent
(integer) - Assist level percentage
Swimming/Water Sports
Aquatic activity metrics:
stroke_type
(integer) - Swimming stroke type (encoded value)resistance
(integer) - Water resistance levelball_speed
(float) - Ball speed for sports applications
Diving
Scuba diving and underwater metrics:
depth
(float) - Water depth in metersabsolute_pressure
(integer) - Absolute pressurenext_stop_depth
(float) - Next decompression stop depthnext_stop_time
(integer) - Time to next decompression stoptime_to_surface
(integer) - Estimated time to surfacendl_time
(integer) - No decompression limit time remainingcns_load
(integer) - CNS oxygen toxicity load percentagen2_load
(integer) - Nitrogen load for decompressionair_time_remaining
(integer) - Remaining air timeascent_rate
(float) - Current ascent ratepo2
(float) - Partial pressure of oxygenpressure_sac
(float) - Surface air consumption rate (pressure)volume_sac
(float) - Surface air consumption rate (volume)rmv
(float) - Respiratory minute volume
Other Fields
Miscellaneous activity data:
activity_type
(integer) - Type of activity being recordeddevice_index
(integer) - Index of recording devicezone
(integer) - Current training zonetime128
(float) - High-resolution timestamp (128Hz)grit
(float) - Grit score (difficulty/intensity metric)flow
(float) - Flow score (performance smoothness)time_from_course
(float) - Time deviation from planned courseleft_pco
(integer) - Left platform center offsetright_pco
(integer) - Right platform center offset
Usage Examples
Basic Usage
# Read and decode FIT file
{:ok, fit_data} = File.read("activity.fit")
records = FitDecoder.decode(fit_data)
# Access basic fields
Enum.each(records, fn record ->
IO.puts("Time: #{record.timestamp}")
IO.puts("Distance: #{record.distance}m")
if Map.has_key?(record, :heart_rate) do
IO.puts("HR: #{record.heart_rate} bpm")
end
end)
Power Analysis
# Extract power data for cycling analysis
power_data = records
|> Enum.filter(&Map.has_key?(&1, :power))
|> Enum.map(fn record ->
%{
timestamp: record.timestamp,
power: record.power,
cadence: Map.get(record, :cadence),
heart_rate: Map.get(record, :heart_rate)
}
end)
avg_power = power_data
|> Enum.map(& &1.power)
|> Enum.sum()
|> div(length(power_data))
IO.puts("Average power: #{avg_power}W")
GPS Tracking
# Extract GPS coordinates
gps_points = records
|> Enum.filter(fn record ->
Map.has_key?(record, :position_lat) && Map.has_key?(record, :position_long)
end)
|> Enum.map(fn record ->
%{
lat: record.position_lat / :math.pow(2, 31) * 180,
lng: record.position_long / :math.pow(2, 31) * 180,
altitude: Map.get(record, :altitude),
timestamp: record.timestamp
}
end)
Running Dynamics
# Analyze running form
running_metrics = records
|> Enum.filter(&Map.has_key?(&1, :vertical_oscillation))
|> Enum.map(fn record ->
%{
vertical_oscillation: record.vertical_oscillation,
stance_time: Map.get(record, :stance_time),
step_length: Map.get(record, :step_length),
vertical_ratio: Map.get(record, :vertical_ratio)
}
end)
Advanced Physiological Data
# Extract comprehensive health metrics
health_data = records
|> Enum.map(fn record ->
%{
timestamp: record.timestamp,
heart_rate: Map.get(record, :heart_rate),
respiration_rate: Map.get(record, :respiration_rate),
spo2: Map.get(record, :saturated_hemoglobin_percent),
stress: Map.get(record, :current_stress),
core_temp: Map.get(record, :core_temperature)
}
|> Enum.filter(fn {_k, v} -> v != nil end)
|> Map.new()
end)
Field Availability
Not all fields will be present in every FIT file. Field availability depends on:
- Device capabilities - Only devices with specific sensors can record certain metrics
- Activity type - Swimming fields won't appear in cycling activities
- Recording settings - Some fields may be disabled to save battery/storage
- FIT file version - Newer fields may not exist in older files
Always check for field presence using Map.has_key?/2
before accessing values.
Data Types
- integer - Whole numbers (timestamps, counts, enums)
- float - Decimal numbers (distances, speeds, percentages)
Invalid/missing values are filtered out during decoding, so fields are only present when they contain valid data.
Converting Common Fields
GPS Coordinates
lat_degrees = record.position_lat / :math.pow(2, 31) * 180
lng_degrees = record.position_long / :math.pow(2, 31) * 180
Timestamps
# FIT timestamps are seconds since 1989-12-31 00:00:00 UTC
fit_epoch = ~U[1989-12-31 00:00:00Z] |> DateTime.to_unix()
actual_time = DateTime.from_unix!(fit_epoch + record.timestamp)
Speed Conversions
# m/s to km/h
speed_kmh = record.speed * 3.6
# m/s to mph
speed_mph = record.speed * 2.237
This comprehensive field support enables detailed analysis of fitness activities, from basic tracking to advanced performance metrics and specialized applications like diving and e-bike monitoring.