Skip to main content

Garmin Connect activity exporter and backup tool

Project description

Build badge PyPi release PyPI - Python Version PyPI - License

About

garminexport is both a library and a tool for downloading/backing up Garmin Connect activities to a local disk.

The main utility script is called garmin-backup and performs incremental backups of your Garmin account to a local directory. The first time garmin-backup is run, it will download all activities. After that, it will do incremental backups of your account. That is, the script will only download activities that haven't already been downloaded to the backup directory.

Installation

garminexport is available on PyPi and can be installed with pip.

Vanilla installation

WARNING

GarminConnect employs Cloudflare's bot protection to prevent scripted access to their services. Therefore a vanilla installation is no longer likely to work. Instead, try the Browser-impersonating installation below.

To only install garminexport and required dependencies run:

pip install garminexport

Browser-impersonating installation

To install garminexport with support to circumvent Cloudflare's bot protection you should install the module with the impersonate_browser extra like so:

pip install garminexport[impersonate_browser]

This replaces the default requests library with curl_cffi for HTTP session handling.

When curl_cffi is used, the GARMINEXPORT_IMPERSONATE_BROWSER environment variable can be used to control which browser is impersonated (default is chrome110, see full list).

Usage

Prerequisites

To be of any use you need to register an account at Garmin Connect and populate it with some activities.

As a command-line tool (garmin-backup)

The backup program is run as follows (use the --help flag for a full list of available options):

garmin-backup --backup-dir=activities <username or email>

Once started, the program will prompt you for your account password and then log in to your Garmin Connect account to download activities to the specified backup directory on your machine. The program will only download activities that aren't already in the backup directory.

Activities can be exported in any of the formats outlined below. Note that by default, the program downloads all formats for every activity. Use the --format option to narrow the selection.

Supported export formats:

  • gpx: activity GPX file (XML).

    GPX 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 (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 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.

garminexport also contains a few smaller utility programs:

  • garmin-get-activity: download a single Garmin Connect activity. Run with --helpfor more details.
  • garmin-upload-activity: uplad a single Garmin Connect activity file (.fit, .gpx, or .tcx). Run with --helpfor more details.

As a library

To build your own tools around the Garmin Connect API you can import the garminclient module. It handles authentication to establish a secure session with Garmin Connect. For example use, have a look at the command-line tools under garminexport/cli.

For example, in your setup.py, setup.cfg, pyproject.toml (PEP 631) add something like:

install_requires=[
    'garminexport',
    # also installs 'impersonate_browser as a dependency
    # 'garminexport[impersonate_browser]',
    ...
]

Note: if you happen to have cloudscraper on your PACKAGEPATH GarminClient will make use of it whenever it needs to make an HTTP request.

Contribute

To start working on the code, create a virtual environment (an isolated development environment) and install the required dependencies like so:

# create virtualenv and populate it with library dependencies
make dev-init

# activate virtualenv
source .venv/bin/activate

# test
make test

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

garminexport-0.5.0.tar.gz (27.3 kB view details)

Uploaded Source

Built Distribution

garminexport-0.5.0-py2.py3-none-any.whl (27.0 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file garminexport-0.5.0.tar.gz.

File metadata

  • Download URL: garminexport-0.5.0.tar.gz
  • Upload date:
  • Size: 27.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.9.2

File hashes

Hashes for garminexport-0.5.0.tar.gz
Algorithm Hash digest
SHA256 ceb4531dafb1f8588d222e6bf450c1891ae80a154851386bb78f849aa0b164d5
MD5 f556af6dda7d07e65a339b860f3aa5a1
BLAKE2b-256 92886b704d6e4c3d5e01719991fdd936e1d864227e1df3bb480cede5e1366068

See more details on using hashes here.

File details

Details for the file garminexport-0.5.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for garminexport-0.5.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 da7c6ae995ac545c42ab5c4ba517c6acca282ab460c5674ded1f43f26cfca05f
MD5 87feb13a25991851bb285bc3b8143bc4
BLAKE2b-256 9cc6485df41a2ff46a16e81bc5182501873334df149f761c9b2bd9d264073083

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page