garminconnect
The Garmin Connect API library comes with two examples:
example.py - Simple getting-started example showing authentication, token storage, and basic API callsdemo.py - Comprehensive demo providing access to 100+ API methods organized into 11 categories for easy navigationNote: The demo menu is generated dynamically; exact options may change between releases.
$ ./demo.py
🏃♂️ Full-blown Garmin Connect API Demo - Main Menu
==================================================
Select a category:
[1] 👤 User & Profile
[2] 📊 Daily Health & Activity
[3] 🔬 Advanced Health Metrics
[4] 📈 Historical Data & Trends
[5] 🏃 Activities & Workouts
[6] ⚖️ Body Composition & Weight
[7] 🏆 Goals & Achievements
[8] ⌚ Device & Technical
[9] 🎽 Gear & Equipment
[0] 💧 Hydration & Wellness
[a] 🔧 System & Export
[q] Exit program
Make your selection:
A comprehensive Python3 API wrapper for Garmin Connect, providing access to health, fitness, and device data.
This library enables developers to programmatically access Garmin Connect data including:
Compatible with all Garmin Connect accounts. See https://connect.garmin.com/
Install from PyPI:
python3 -m pip install --upgrade pip
python3 -m pip install garminconnect
python3 -m venv .venv --copies
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install pdm
pdm install --group :example
# Run the simple example
python3 ./example.py
# Run the comprehensive demo
python3 ./demo.py
Set up a development environment for contributing:
Note: This project uses PDM for modern Python dependency management and task automation. All development tasks are configured as PDM scripts in
pyproject.toml. The Python interpreter is automatically configured to use.venv/bin/pythonwhen you create the virtual environment.
Environment Setup:
⚠️ Important: On externally-managed Python environments (like Debian/Ubuntu), you must create a virtual environment before installing PDM to avoid system package conflicts.
# 1. Create and activate a virtual environment
python3 -m venv .venv --copies
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# 2. Install PDM (Python Dependency Manager)
pip install pdm
# 3. Install all development dependencies
pdm install --group :all
# 4. Install optional tools for enhanced development experience
pip install "black[jupyter]" codespell pre-commit
# 5. Setup pre-commit hooks (optional)
pre-commit install --install-hooks
Alternative for System-wide PDM Installation:
# Install PDM via pipx (recommended for system-wide tools)
python3 -m pip install --user pipx
pipx install pdm
# Then proceed with project setup
pdm install --group :all
Available Development Commands:
pdm run format # Auto-format code (isort, black, ruff --fix)
pdm run lint # Check code quality (isort, ruff, black, mypy)
pdm run codespell # Check spelling errors (install codespell if needed)
pdm run test # Run test suite
pdm run testcov # Run tests with coverage report
pdm run all # Run all checks
pdm run clean # Clean build artifacts and cache files
pdm run build # Build package for distribution
pdm run publish # Build and publish to PyPI
View all available commands:
pdm run --list # Display all available PDM scripts
Code Quality Workflow:
# Before making changes
pdm run lint # Check current code quality
# After making changes
pdm run format # Auto-format your code
pdm run lint # Verify code quality
pdm run codespell # Check spelling
pdm run test # Run tests to ensure nothing broke
Run these commands before submitting PRs to ensure code quality standards.
The library uses the same OAuth authentication as the official Garmin Connect app via Garth.
Key Features:
Advanced Configuration:
# Optional: Custom OAuth consumer (before login)
import os
import garth
garth.sso.OAUTH_CONSUMER = {
'key': os.getenv('GARTH_OAUTH_KEY', '<YOUR_KEY>'),
'secret': os.getenv('GARTH_OAUTH_SECRET', '<YOUR_SECRET>'),
}
# Note: Set these env vars securely; placeholders are non-sensitive.
Token Storage:
Tokens are automatically saved to ~/.garminconnect directory for persistent authentication.
For security, ensure restrictive permissions:
chmod 700 ~/.garminconnect
chmod 600 ~/.garminconnect/* 2>/dev/null || true
Run the test suite to verify functionality:
Prerequisites:
Create tokens in ~/.garminconnect by running the example program.
# Install development dependencies
pdm install --group :all
Run Tests:
pdm run test # Run all tests
pdm run testcov # Run tests with coverage report
Optional: keep test tokens isolated
export GARMINTOKENS="$(mktemp -d)"
python3 ./example.py # create fresh tokens for tests
pdm run test
Note: Tests automatically use ~/.garminconnect as the default token file location. You can override this by setting the GARMINTOKENS environment variable. Run example.py first to generate authentication tokens for testing.
For Developers: Tests use VCR cassettes to record/replay HTTP interactions. If tests fail with authentication errors, ensure valid tokens exist in ~/.garminconnect
For package maintainers:
Setup PyPI credentials:
pip install twine
# Edit with your preferred editor, or create via here-doc:
# cat > ~/.pypirc <<'EOF'
# [pypi]
# username = __token__
# password = <PyPI_API_TOKEN>
# EOF
[pypi]
username = __token__
password = <PyPI_API_TOKEN>
Recommended: use environment variables and restrict file perms
chmod 600 ~/.pypirc
export TWINE_USERNAME="__token__"
export TWINE_PASSWORD="<PyPI_API_TOKEN>"
Publish new version:
pdm run publish # Build and publish to PyPI
Alternative publishing steps:
pdm run build # Build package only
pdm publish # Publish pre-built package
We welcome contributions! Here's how you can help:
Before Contributing:
pdm install --group :all)pdm run format && pdm run lint)pdm run test)Development Workflow:
# 1. Setup environment (with virtual environment)
python3 -m venv .venv --copies
source .venv/bin/activate
pip install pdm
pdm install --group :all
# 2. Make your changes
# ... edit code ...
# 3. Quality checks
pdm run format # Auto-format code
pdm run lint # Check code quality
pdm run test # Run tests
# 4. Submit PR
git commit -m "Your changes"
git push origin your-branch
Explore the API interactively with our reference notebook.
from garminconnect import Garmin
import os
# Initialize and login
client = Garmin(
os.getenv("GARMIN_EMAIL", "<YOUR_EMAIL>"),
os.getenv("GARMIN_PASSWORD", "<YOUR_PASSWORD>")
)
client.login()
# Get today's stats
from datetime import date
_today = date.today().strftime('%Y-%m-%d')
stats = client.get_stats(_today)
# Get heart rate data
hr_data = client.get_heart_rates(_today)
print(f"Resting HR: {hr_data.get('restingHeartRate', 'n/a')}")
tests/ directorySpecial thanks to all contributors who have helped improve this project:
This project thrives thanks to community involvement and feedback.
If you find this library useful for your projects, please consider supporting its continued development and maintenance:
Why Support?
Every contribution, no matter the size, makes a difference and is greatly appreciated! 🙏
FAQs
Python 3 API wrapper for Garmin Connect
We found that garminconnect demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Socket identified 80 fake candidates targeting engineering roles, including suspected North Korean operators, exposing the new reality of hiring as a security function.
Application Security
/Research
/Security News
Socket detected multiple compromised CrowdStrike npm packages, continuing the "Shai-Hulud" supply chain attack that has now impacted nearly 500 packages.
Research
/Security News
Malicious update to @ctrl/tinycolor on npm is part of a supply-chain attack hitting 40+ packages across maintainers