87 lines
5.4 KiB
Markdown
87 lines
5.4 KiB
Markdown
# Welcome!
|
|
|
|
If you are here, it means you are interested in helping this small project out.
|
|
A hearty welcome and thank you! There are many ways you can contribute:
|
|
|
|
- Offer PR's to fix bugs or implement new features.
|
|
- Give feedback and bug reports regarding the software or the documentation.
|
|
- Setting up an automated toolchain with mock endpoints for the HTTP calls for easier testing
|
|
- Improve our examples, tutorials, and documentation.
|
|
|
|
## Python Versions
|
|
|
|
### Python 2 vs 3
|
|
|
|
At the time of this writing (2021-07) Python 2 has long passed its [sunset](https://python3statement.org/).
|
|
And the effort to still support Python 2 has become too big (see https://github.com/pe-st/garmin-connect-export/issues/64);
|
|
the script now uses features from Python 3 which Python 2 doesn't understand,
|
|
so if you try to run the script with Python 2 you will get complaints about
|
|
invalid syntax or other similar error messages.
|
|
|
|
### Python 3.x Versions
|
|
|
|
The script should be usable for a wide range of users and Python versions.
|
|
|
|
For that reason the script should be compatible with the oldest still [supported
|
|
Python version](https://devguide.python.org/versions/). At the time of this writing
|
|
(July 2022) this is Python 3.7, whose end-of-life is currently scheduled for June 2023.
|
|
|
|
The Github Actions (see `github/workflows/python-app.yml`) thus run all steps twice,
|
|
once with the oldest supported Python version, and once with the newest released version.
|
|
|
|
## Getting started
|
|
|
|
### Pull requests
|
|
|
|
If you are new to GitHub [here](https://help.github.com/categories/collaborating-with-issues-and-pull-requests/)
|
|
is a detailed help source on getting involved with development on GitHub.
|
|
|
|
### Testing
|
|
|
|
There is a small set of unit test, using [pytest](https://docs.pytest.org/en/latest/);
|
|
these tests are executed automatically whenever a commit is pushed or when a pull request is updated.
|
|
|
|
I found that the free [PyCharm Community](https://www.jetbrains.com/pycharm/download/) is well suited for running the
|
|
tests.
|
|
|
|
Unfortunately there are no mocks yet for simulating Garmin Connect during development, so for real tests you'll have to
|
|
run the script against your own Garmin account.
|
|
|
|
## REST endpoints
|
|
|
|
As this script doesn't use the paid API, the endpoints to use are known by reverse engineering browser sessions. And as
|
|
the Garmin Connect website changes over time, chances are that this script gets broken.
|
|
|
|
Small history of the endpoints used by `gcexport.py` to get a list of activities:
|
|
|
|
- [activity-search-service-1.0](https://connect.garmin.com/proxy/activity-search-service-1.0/json/activities):
|
|
initial endpoint used since 2015, worked at least until January 2018
|
|
- [activity-search-service-1.2](https://connect.garmin.com/proxy/activity-search-service-1.2/json/activities):
|
|
endpoint introduced in `gcexport.py` in August 2016. In March 2018 this still works, but doesn't allow you to fetch
|
|
more than 20 activities, even split over multiple calls (when doing three consecutive calls with 1,19,19 as `limit`
|
|
parameter, the third one fails with HTTP error 500).
|
|
In August 2018 it stopped working altogether. The JSON returned by this endpoint however was quite rich
|
|
(see example `activity-search-service-1.2.json` in the `json` folder).
|
|
- [Profile page](https://connect.garmin.com/modern/profile) and
|
|
[User Stats page](https://connect.garmin.com/modern/proxy/userstats-service/statistics/user_name)
|
|
were introduced in August 2018 when activity-search-service-1.2 stopped working. Their purpose in this script is
|
|
solely to get the number of activities which I didn't find elsewhere.
|
|
- [activitylist-service](https://connect.garmin.com/modern/proxy/activitylist-service/activities/search/activities):
|
|
endpoint introduced in `gcexport.py` in March 2018. The JSON returned by this endpoint is very different from the
|
|
activity-search-service-1.2 one (also here see the example in the `json` folder), e.g.
|
|
- it is concise and offers no redundant information (e.g. only speed, not speed and pace)
|
|
- the units are not explicitly given and must be deducted (e.g. the speed unit is m/s)
|
|
- there is less information, e.g. there is only one set of elevation values (not both corrected and uncorrected), and other values like minimum heart rate are missing.
|
|
- some other information is available only as an ID (e.g. `timeZoneId` or `deviceId`), and more complete information
|
|
is available by further REST calls (one for each activity and additional ones for device information)
|
|
|
|
Endpoints to get information about a specific activity:
|
|
|
|
- [activity-service](https://connect.garmin.com/modern/proxy/activity-service/activity/nnnn): A kind of summary of the activity, most values are present in their canonical format.
|
|
- [activity-service-1.3 details](https://connect.garmin.com/modern/proxy/activity-service-1.3/json/activityDetails/nnnn): A detailed list of measurements, with a list of the metrics available for each measurement.
|
|
|
|
### Limitations of Data Provided by Current Endpoints and Choices Made
|
|
|
|
- The timezones provided are just the names (e.g. for Central European Time CET you can get either "Europe/Paris" or "(GMT+01:00) Central European Time"), but not the exact offset. Note that the "GMT+01:00" part of the name is hardcoded, so in summer (daylight savings time) Garmin Connect still uses +01:00 in the name even if the offset then is +02:00. To get the offset you need to calculate the difference between the startTimeLocal and the startTimeGMT.
|
|
|