Garmin Connect Python API

0.3.2 · active · verified Thu Apr 16

garminconnect is a Python 3 API wrapper for Garmin Connect, enabling programmatic access to a user's health metrics, activity data, workouts, and other fitness information. The library is actively maintained, with frequent updates (current version 0.3.2) to adapt to changes in Garmin's API infrastructure, particularly authentication and Cloudflare bypass mechanisms.

Common errors

```
GarminConnectAuthenticationError: Wrong credentials — please try again.
```
cause The provided username or password is incorrect, or Garmin's security (e.g., Cloudflare) is actively blocking the login attempt.

fix Verify your Garmin Connect username and password. If credentials are correct, ensure `curl_cffi` and `ua-generator` are installed. If you recently upgraded to `garminconnect>=0.3.0`, old session tokens are invalid; a fresh login will create new ones. Consider trying login from a different network if Cloudflare is suspected to be blocking your IP.
```
Exception: No valid tokens found — please log in.
```
cause The library could not find a valid `garmin_tokens.json` file in `~/.garminconnect/` or the existing tokens are expired/invalid, especially after upgrading to a breaking version like 0.3.0.

fix Call `api.login()` explicitly to perform a fresh login. This will generate and save new OAuth tokens to `~/.garminconnect/garmin_tokens.json`. You might need to delete old token files (e.g., `~/.garminconnect/session.json` or `~/.garminconnect/garmin_tokens.json`) if they're corrupted or from a much older version.
```
HTTP status code: 429 - Too Many Requests
```
cause Garmin's API, protected by Cloudflare, has rate-limited your requests due to an excessive number of calls in a short period or other suspicious activity.

fix Implement rate limiting or introduce delays between your API calls. The `garminconnect` library attempts to handle some Cloudflare bypasses; ensure `curl_cffi` and `ua-generator` are installed. If the problem persists, reduce the frequency of your script's interactions or temporarily cease operations.

Warnings

breaking Version 0.3.0 introduced a complete rewrite of the authentication engine, replacing the `garth` dependency with a native SSO flow that mimics the official Garmin Connect app. This change ensures better reliability against Garmin's evolving API and Cloudflare protections.
Fix: Saved tokens from versions prior to 0.3.0 are incompatible. A fresh login (`api.login()`) is required after upgrading. Additionally, install the new mandatory dependencies: `curl_cffi` and `ua-generator`.
gotcha Garmin Connect uses Cloudflare, which can aggressively block programmatic access based on perceived bot activity, IP address reputation, or rate limits, potentially leading to '429 Too Many Requests' or 'Access denied' errors.
Fix: The library (v0.3.0+) implements TLS impersonation strategies and random browser fingerprinting (via `curl_cffi` and `ua-generator`) to mitigate Cloudflare blocking. Ensure these dependencies are installed. If issues persist, reduce API call frequency or try initiating login from a different network/IP. Persistent blocks might require contacting Garmin support.
gotcha Multi-Factor Authentication (MFA) can interrupt the login flow. While the library supports MFA, it requires interaction (a callback function) or providing the MFA code via an environment variable.
Fix: For interactive use, the `login()` method will prompt for an MFA code if required. For automated scripts, you can provide the MFA code using the `GARMIN_MFA_CODE` environment variable for the `prompt_mfa` callback, or implement a custom `prompt_mfa` handler in the `Garmin` constructor.

Install

pip install garminconnect curl_cffi ua-generator Latest Version (0.3.0+)
pip install garminconnect Core Library Only (Pre-0.3.0 and if dependencies handled separately)

Imports

Garmin
```
from garminconnect import Garmin
```

Quickstart

This quickstart demonstrates how to log in to Garmin Connect and retrieve activity data for the current day. It emphasizes using environment variables for sensitive credentials. The library handles token saving and refreshing automatically after the initial login. Make sure to set `GARMIN_USERNAME` and `GARMIN_PASSWORD` in your environment.

import os
import datetime
from garminconnect import Garmin

# Get credentials from environment variables for security
USERNAME = os.environ.get('GARMIN_USERNAME', '')
PASSWORD = os.environ.get('GARMIN_PASSWORD', '')

if not USERNAME or not PASSWORD:
    print("Please set GARMIN_USERNAME and GARMIN_PASSWORD environment variables.")
    exit(1)

api = None
try:
    # Initialize Garmin API with credentials
    # Tokens are automatically saved to ~/.garminconnect/garmin_tokens.json
    api = Garmin(USERNAME, PASSWORD)
    api.login()
    print("Successfully logged in to Garmin Connect.")

    # Example: Get today's activity data
    today = datetime.date.today()
    activities = api.get_activities_by_date(today.isoformat(), today.isoformat())
    
    if activities:
        print(f"Activities for {today.isoformat()}:")
        for activity in activities:
            print(f"  - {activity['activityType']['typeKey']}: {activity['distance']}m, {activity['duration']}s")
    else:
        print(f"No activities found for {today.isoformat()}.")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →