The fitparse API Documentation

The FitFile Object

class fitparse.FitFile(fileish, check_crc=True, data_processor=None)

Interface for reading a .FIT file.

Provided a .FIT file fileish, this is the main interface to parsing a .FIT file and reading its data.

Parameters

• fileish –

  A file path, file-like object, or a string of bytes representing FIT data to be read.

  Note

  Usage Notes

  All of the following work with the fileish parameter:

  # Specifying a file path
  fitfile = FitFile('/path.to/fitfile.fit')
  
  # Providing a file-like object
  file_obj = open('/path.to/fitfile.fit', 'rb')
  fitfile = FitFile(file_obj)
  
  # Providing a raw string of bytes
  file_obj = open('/path.to/fitfile.fit', 'rb')
  raw_fit_data = file_obj.read()
  fitfile = FitFile(raw_fit_data)
  

• check_crc – Set to False if to disable CRC validation while reading the current .FIT file.

• data_processor – Use this parameter to specify an alternate data processor object to use. If one is not provided, an instance of FitFileDataProcessor will be used.

Raises

Creating a FitFile may raise a FitParseError exception. See the note on exceptions.

get_messages(name=None, with_definitions=False, as_dict=False)

TODO: document and implement

parse()

Parse the underlying FIT data completely.

Raises

May raise a FitParseError exception.

Warning

Note on Exceptions While Parsing a .FIT File

In general, any operation on a that FitFile that results in parsing the underlying FIT data may throw a FitParseError exception when invalid data is encountered.

One way to catch these before you start reading going through the messages contained in a FitFile is to call parse() immediately after creating a FitFile object. For example:

import sys
from fitparse import FitFile, FitParseError

try:
    fitfile = FitFile('/path.to/fitfile.fit')
    fitfile.parse()
except FitParseError, e:
    print "Error while parsing .FIT file: %s" % e
    sys.exit(1)

Any file related IO exceptions caught during a read() or close() operation will be raised as usual.

messages

The complete list of DataMessage record objects that are contained in this FitFile. This list is provided as a convenience attribute that wraps get_messages(). It is functionally equivalent to:

class FitFile(object):
    # ...

    @property
    def messages(self):
        return list(self.get_messages())

Raises

Reading this property may raise a FitParseError exception. See the note on exceptions.

profile_version

The profile version of the FIT data read (see ANT FIT SDK for)

protocol_version

The protocol version of the FIT data read (see ANT FIT SDK)

Record Objects

Common Used Record Objects

class fitparse.DataMessage

A list of DataMessage objects are returned by FitFile.get_messages() and FitFile.messages. These are not meant to be created directly.

fields

A list of FieldData objects representing the fields contained in this message.

get(field_name, as_dict=False)

Returns a FieldData for field field_name if it exists, otherwise None. If as_dict is set to True, returns a dict representation of the field (see FieldData.as_dict())

get_value(field_name)

Returns the value of field_name if it exists, otherwise None

get_values()

Return a dict mapping of field names to their values. For example:

>> data_message.get_values()
{
    'altitude': 24.6,
    'cadence': 97,
    'distance': 81.97,
    'grade': None,
    'heart_rate': 153,
    'position_lat': None,
    'position_long': None,
    'power': None,
    'resistance': None,
    'speed': 7.792,
    'temperature': 20,
    'time_from_course': None,
    'timestamp': datetime.datetime(2011, 11, 6, 13, 41, 50)
}

as_dict()

TODO: document me

name

The name of this DataMessage, as defined by its def_mesg.

def_mesg

Note

Generally this attribute is for access to FIT internals only

The DefinitionMessage associated with this DataMessage. These are encountered while parsing FIT data and are declared to define the data contained in a `DataMessage.

mesg_num

The message number of this DataMessage, as defined by its def_mesg.

mesg_type

The MessageType associated with the mesg_num for this DataMessage. If no associated message type is defined in the SDK profile, then this is set to None.

TODO: Document SDK profile and update link