activity-parser

Parser for loading FIT, TCX and GPX activity files into Pandas DataFrames.

Provides a parser object for reading (optionally gzipped) FIT, TCX, and GPX activity files and converting them into Pandas DataFrames. During import, field names extracted from activity files are normalized into a canonical set of output column names with consistent units to allow for standardized downstream data processing.

Installation

pip install activity-parser

Usage

Create a new instance of the ActivityParser class to be reused for subsequent parsing of activity files:

import activity_parser
parser = activity_parser.ActivityParser()

Parse FIT, TCX and GPX files into normalized DataFrames:

records, laps, activity = parser.parse('path/to/fit_file.fit')
records, laps, activity = parser.parse('path/to/gpx_file.gpx')
records, laps, activity = parser.parse('path/to/tcx_file.tcx')

Each file is assumed to contain a single activity. Multiple activities/tracks (chained FIT files, multi-activity TCX, multi-track GPX) have their records/laps merged into one set of results. In those cases, the returned Activity summary reflects only the first activity/session in the file.

Output data

records and laps are each a DataFrame of normalized data, e.g.:

                           distance  speed  cadence  heart_rate
time
2026-01-05 08:00:00+00:00      0.00   36.0       80         100
2026-01-05 08:00:01+00:00      0.01   36.0       81         101

A few notes on column handling:

• Column names and units are standardized across source formats for known field types.
• Unknown fields are omitted by default; customize columns via record_columns, lap_columns, and include_all_columns on ActivityParser — see its docstring for details.
• Not every column appears in every file: parse() only includes columns actually present.

Records

Not all fields are available in all source formats. Fields marked with (*) are exporter-dependent.

Laps

GPX files have no lap data, so laps is always an empty DataFrame for GPX. Fields marked with (*) are exporter-dependent.

Activity

activity is an Activity dataclass instance: a small file-level summary. Fields are None when the source format/file doesn't record them. Values are transcribed from the file, never computed/derived from records or laps.

(*) GPX's start_time comes from metadata/time, which is technically the file's export time rather than the activity's start.

Parser notes

FIT files

FIT parsing wraps fitdecode, which decodes against Garmin's public FIT SDK profile. Field values and types come from that profile, and units are converted via fitdecode's StandardUnitsDataProcessor.

This package transforms certain FIT fields beyond the processing done by fitdecode:

• Some fields have lower- and higher-precision versions; by default, parse() returns only the higher-precision value, under the base field's name.
• Other fields store sub-integer precision in a separate field, which parse() adds into the base field.
• FIT's pedal power balance is a single bit-packed byte (a side flag plus a percentage); parse() decodes it into left_balance/right_balance.

Messages/fields fitdecode can't resolve against the profile (e.g. proprietary extensions) are kept as raw values under unknown_<n> names.

TCX & GPX files

TCX and GPX files are parsed natively in this package. The parser supports the following schema versions and extensions:

Unrecognized elements and attributes are exported as string columns named with their XML namespace in Clark notation.