{"id":7252,"library":"garminconnect","title":"Garmin Connect Python API","description":"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.","status":"active","version":"0.3.2","language":"en","source_language":"en","source_url":"https://github.com/cyberjunky/python-garminconnect","tags":["Garmin","fitness","health","wearable","API","activity","workout","data-retrieval"],"install":[{"cmd":"pip install garminconnect curl_cffi ua-generator","lang":"bash","label":"Latest Version (0.3.0+)"},{"cmd":"pip install garminconnect","lang":"bash","label":"Core Library Only (Pre-0.3.0 and if dependencies handled separately)"}],"dependencies":[{"reason":"Required for Cloudflare bypass and TLS impersonation strategies introduced in v0.3.0 to robustly handle Garmin's security measures.","package":"curl_cffi","optional":false},{"reason":"Required for random browser fingerprinting, introduced in v0.3.0, to improve authentication success rates and mimic legitimate browser traffic.","package":"ua-generator","optional":false}],"imports":[{"symbol":"Garmin","correct":"from garminconnect import Garmin"}],"quickstart":{"code":"import os\nimport datetime\nfrom garminconnect import Garmin\n\n# Get credentials from environment variables for security\nUSERNAME = os.environ.get('GARMIN_USERNAME', '')\nPASSWORD = os.environ.get('GARMIN_PASSWORD', '')\n\nif not USERNAME or not PASSWORD:\n    print(\"Please set GARMIN_USERNAME and GARMIN_PASSWORD environment variables.\")\n    exit(1)\n\napi = None\ntry:\n    # Initialize Garmin API with credentials\n    # Tokens are automatically saved to ~/.garminconnect/garmin_tokens.json\n    api = Garmin(USERNAME, PASSWORD)\n    api.login()\n    print(\"Successfully logged in to Garmin Connect.\")\n\n    # Example: Get today's activity data\n    today = datetime.date.today()\n    activities = api.get_activities_by_date(today.isoformat(), today.isoformat())\n    \n    if activities:\n        print(f\"Activities for {today.isoformat()}:\")\n        for activity in activities:\n            print(f\"  - {activity['activityType']['typeKey']}: {activity['distance']}m, {activity['duration']}s\")\n    else:\n        print(f\"No activities found for {today.isoformat()}.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":">=0.3.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"The provided username or password is incorrect, or Garmin's security (e.g., Cloudflare) is actively blocking the login attempt.","error":"GarminConnectAuthenticationError: Wrong credentials — please try again."},{"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.","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.","error":"Exception: No valid tokens found — please log in."},{"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.","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.","error":"HTTP status code: 429 - Too Many Requests"}]}