[](https://img.shields.io/pypi/v/garminexport.svg)
# About
`garminexport` is both a library and a tool for downloading/backing up
[Garmin Connect](http://connect.garmin.com/) 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](https://pypi.org/) and can be installed
with [pip](http://pip.readthedocs.org).
## 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](#browser-impersonating-installation)
> below.
To only install `garminexport` and required dependencies run:
```bash
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](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies)
like so:
```bash
pip install garminexport[impersonate_browser]
```
This replaces the default [requests](https://github.com/psf/requests) library
with [curl_cffi](https://github.com/yifeikong/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](https://github.com/lwthiker/curl-impersonate#supported-browsers)).
# Usage
## Prerequisites
To be of any use you need to register an account at
[Garmin Connect](http://connect.garmin.com/) 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):
```bash
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).
<sub>[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.</sub>
- `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._
<sub>[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).</sub>
- `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._
<sub>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.</sub>
- `json_summary`: activity summary file (JSON).
<sub>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.</sub>
- `json_details`: activity details file (JSON).
<sub>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.</sub>
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
`--help`for more details.
- `garmin-upload-activity`: uplad a single Garmin Connect activity file (`.fit`,
`.gpx`, or `.tcx`). Run with `--help`for 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](garminexport/cli).
For example, in your `setup.py`, `setup.cfg`, `pyproject.toml`
([PEP 631](https://peps.python.org/pep-0631/)) add something like:
```python
install_requires=[
'garminexport',
# also installs 'impersonate_browser as a dependency
# 'garminexport[impersonate_browser]',
...
]
```
Note: if you happen to have
[cloudscraper](https://github.com/VeNoMouS/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
Raw data
{
"_id": null,
"home_page": "https://github.com/petergardfjall/garminexport",
"name": "garminexport",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "garmin,export,backup",
"author": "Peter Gardfj\u00e4ll",
"author_email": "peter.gardfjall.work@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/92/88/6b704d6e4c3d5e01719991fdd936e1d864227e1df3bb480cede5e1366068/garminexport-0.5.0.tar.gz",
"platform": null,
"description": "\n[](https://img.shields.io/pypi/v/garminexport.svg)\n\n\n\n# About\n\n`garminexport` is both a library and a tool for downloading/backing up\n[Garmin Connect](http://connect.garmin.com/) activities to a local disk.\n\nThe main utility script is called `garmin-backup` and performs incremental\nbackups of your Garmin account to a local directory. The first time\n`garmin-backup` is run, it will download _all_ activities. After that, it will\ndo incremental backups of your account. That is, the script will only download\nactivities that haven't already been downloaded to the backup directory.\n\n# Installation\n\n`garminexport` is available on [PyPi](https://pypi.org/) and can be installed\nwith [pip](http://pip.readthedocs.org).\n\n## Vanilla installation\n\n> **WARNING**\n>\n> GarminConnect employs Cloudflare's bot protection to prevent scripted access\n> to their services. Therefore a vanilla installation is no longer likely to\n> work. Instead, try the\n> [Browser-impersonating installation](#browser-impersonating-installation)\n> below.\n\nTo only install `garminexport` and required dependencies run:\n\n```bash\npip install garminexport\n```\n\n## Browser-impersonating installation\n\nTo install `garminexport` with support to circumvent Cloudflare's bot protection\nyou should install the module with the `impersonate_browser`\n[extra](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies)\nlike so:\n\n```bash\npip install garminexport[impersonate_browser]\n```\n\nThis replaces the default [requests](https://github.com/psf/requests) library\nwith [curl_cffi](https://github.com/yifeikong/curl_cffi) for HTTP session\nhandling.\n\nWhen `curl_cffi` is used, the `GARMINEXPORT_IMPERSONATE_BROWSER` environment\nvariable can be used to control which browser is impersonated (default is\n`chrome110`, see\n[full list](https://github.com/lwthiker/curl-impersonate#supported-browsers)).\n\n# Usage\n\n## Prerequisites\n\nTo be of any use you need to register an account at\n[Garmin Connect](http://connect.garmin.com/) and populate it with some\nactivities.\n\n## As a command-line tool (garmin-backup)\n\nThe backup program is run as follows (use the `--help` flag for a full list of\navailable options):\n\n```bash\ngarmin-backup --backup-dir=activities <username or email>\n```\n\nOnce started, the program will prompt you for your account password and then log\nin to your Garmin Connect account to download activities to the specified backup\ndirectory on your machine. The program will only download activities that aren't\nalready in the backup directory.\n\nActivities can be exported in any of the formats outlined below. Note that by\ndefault, the program downloads all formats for every activity. Use the\n`--format` option to narrow the selection.\n\nSupported export formats:\n\n- `gpx`: activity GPX file (XML).\n\n <sub>[GPX](https://en.wikipedia.org/wiki/GPS_Exchange_Format) is an open\n format, mainly for storing GPS routes/tracks. It does support extensions and\n Garmin appears to annotate the GPS data with, for example, heart-rate and\n cadence, when available on your device.</sub>\n\n- `tcx`: an activity TCX file (XML). _Note: a `.tcx` file may not always be\n possible to export, for example if an activity was uploaded in gpx format. In\n that case, Garmin won't try to synthesize a tcx file._\n\n <sub>[TCX](https://en.wikipedia.org/wiki/Training_Center_XML) (Training Center\n XML) is Garmin's own XML format. It is, essentially, an extension of GPX which\n includes more metrics and divides the GPS track into \"laps\" as recorded by\n your device (with \"lap summaries\" for each metric).</sub>\n\n- `fit`: activity FIT file (binary format). _Note: a `.fit` file may not always\n be possible to export, for example if an activity was entered manually rather\n than imported from a Garmin device._\n\n <sub>The [FIT](https://www.thisisant.com/resources/fit/) format is the \"raw\n data type\" stored in your Garmin device and should contain all metrics your\n device is capable of tracking (GPS, heart rate, cadence, etc). It's a binary\n format, so tools are needed to read its content.</sub>\n\n- `json_summary`: activity summary file (JSON).\n\n <sub>Provides summary data for an activity. Seems to lack a formal schema and\n should not be counted on as a stable data format (it may change at any time).\n Only included since it _may_ contain additional data that could be useful for\n developers of analysis tools.</sub>\n\n- `json_details`: activity details file (JSON).\n\n <sub>Provides detailed activity data in a JSON format. Seems to lack a formal\n schema and should not be counted on as a stable data format (it may change at\n any time). Only included since it _may_ contain additional data that could be\n useful for developers of analysis tools.</sub>\n\nAll files are written to the same directory (`activities/` by default). Each\nactivity file is prefixed by its upload timestamp and its activity id.\n\n`garminexport` also contains a few smaller utility programs:\n\n- `garmin-get-activity`: download a single Garmin Connect activity. Run with\n `--help`for more details.\n- `garmin-upload-activity`: uplad a single Garmin Connect activity file (`.fit`,\n `.gpx`, or `.tcx`). Run with `--help`for more details.\n\n## As a library\n\nTo build your own tools around the Garmin Connect API you can import the\n`garminclient` module. It handles authentication to establish a secure session\nwith Garmin Connect. For example use, have a look at the command-line tools\nunder [garminexport/cli](garminexport/cli).\n\nFor example, in your `setup.py`, `setup.cfg`, `pyproject.toml`\n([PEP 631](https://peps.python.org/pep-0631/)) add something like:\n\n```python\ninstall_requires=[\n 'garminexport',\n # also installs 'impersonate_browser as a dependency\n # 'garminexport[impersonate_browser]',\n ...\n]\n```\n\nNote: if you happen to have\n[cloudscraper](https://github.com/VeNoMouS/cloudscraper) on your `PACKAGEPATH`\n`GarminClient` will make use of it whenever it needs to make an HTTP request.\n\n# Contribute\n\nTo start working on the code, create a virtual environment (an isolated\ndevelopment environment) and install the required dependencies like so:\n\n # create virtualenv and populate it with library dependencies\n make dev-init\n\n # activate virtualenv\n source .venv/bin/activate\n\n # test\n make test\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Garmin Connect activity exporter and backup tool",
"version": "0.5.0",
"project_urls": {
"Homepage": "https://github.com/petergardfjall/garminexport",
"Source": "https://github.com/petergardfjall/garminexport.git",
"Tracker": "https://github.com/petergardfjall/garminexport/issues"
},
"split_keywords": [
"garmin",
"export",
"backup"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9cc6485df41a2ff46a16e81bc5182501873334df149f761c9b2bd9d264073083",
"md5": "87feb13a25991851bb285bc3b8143bc4",
"sha256": "da7c6ae995ac545c42ab5c4ba517c6acca282ab460c5674ded1f43f26cfca05f"
},
"downloads": -1,
"filename": "garminexport-0.5.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "87feb13a25991851bb285bc3b8143bc4",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.5",
"size": 26998,
"upload_time": "2023-11-11T13:17:49",
"upload_time_iso_8601": "2023-11-11T13:17:49.124552Z",
"url": "https://files.pythonhosted.org/packages/9c/c6/485df41a2ff46a16e81bc5182501873334df149f761c9b2bd9d264073083/garminexport-0.5.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "92886b704d6e4c3d5e01719991fdd936e1d864227e1df3bb480cede5e1366068",
"md5": "f556af6dda7d07e65a339b860f3aa5a1",
"sha256": "ceb4531dafb1f8588d222e6bf450c1891ae80a154851386bb78f849aa0b164d5"
},
"downloads": -1,
"filename": "garminexport-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "f556af6dda7d07e65a339b860f3aa5a1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 27348,
"upload_time": "2023-11-11T13:17:51",
"upload_time_iso_8601": "2023-11-11T13:17:51.031846Z",
"url": "https://files.pythonhosted.org/packages/92/88/6b704d6e4c3d5e01719991fdd936e1d864227e1df3bb480cede5e1366068/garminexport-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-11 13:17:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "petergardfjall",
"github_project": "garminexport",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "garminexport"
}
JSON
