From c02e23fb3e30ffd4dcbc2693c1aa00e749fadaad Mon Sep 17 00:00:00 2001 From: petergardfjall Date: Sat, 12 Oct 2019 08:24:13 +0200 Subject: [PATCH] README: add format descriptions --- README.md | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0f8d57a..617ce52 100644 --- a/README.md +++ b/README.md @@ -67,21 +67,47 @@ by default, the program downloads all formats for every activity. Use the Supported export formats: - - ``json_summary``: activity summary file (JSON) - - ``json_details``: activity details file (JSON) + - ``gpx``: activity GPX file (XML). - - ``gpx``: activity GPX file (XML) + [GPX](https://en.wikipedia.org/wiki/GPS_Exchange_Format) is an open + format, mainly for storing GPS routes/tracks. It does support extensions + and Garmin appears to annotate the GPS data with, for example, heart-rate + and cadence, when available on your device. - ``tcx``: an activity TCX file (XML). *Note: a ``.tcx`` file may not always be possible to export, for example if an activity was uploaded in gpx format. In that case, Garmin won't try to synthesize a tcx file.* + [TCX](https://en.wikipedia.org/wiki/Training_Center_XML) (Training Center + XML) is Garmin's own XML format. It is, essentially, an extension of GPX + which includes more metrics and divides the GPS track into "laps" as + recorded by your device (with "lap summaries" for each metric). + - ``fit``: activity FIT file (binary format). *Note: a ``.fit`` file may not always be possible to export, for example if an activity was entered manually rather than imported from a Garmin device.* + The [FIT](https://www.thisisant.com/resources/fit/) format is the "raw + data type" stored in your Garmin device and should contain all metrics + your device is capable of tracking (GPS, heart rate, cadence, etc). It's a + binary format, so tools are needed to read its content. + + - ``json_summary``: activity summary file (JSON). + + Provides summary data for an activity. Seems to lack a formal schema and + should not be counted on as a stable data format (it may change at any + time). Only included since it *may* contain additional data that could be + useful for developers of analysis tools. + + - ``json_details``: activity details file (JSON). + + Provides detailed activity data in a JSON format. Seems to lack a formal + schema and should not be counted on as a stable data format (it may change + at any time). Only included since it *may* contain additional data that + could be useful for developers of analysis tools. + All files are written to the same directory (``activities/`` by default). Each activity file is prefixed by its upload timestamp and its activity id.