garth-ng 2.0.0a1

Garmin SSO auth + Connect Python client (maintained fork of matin/garth)

garth-ng

Garmin SSO auth + Connect Python client — maintained fork of matin/garth

About this fork

garth-ng is a maintained continuation of the original garth library by Matin Tamizi. The original project was deprecated after Garmin changed their auth flow. This fork restores compatibility and continues active development. The package name changed to garth-ng but the import stays import garth — same as Pillow keeping from PIL import Image.

Migrating from garth

Both packages install into the same site-packages/garth/ directory. You must uninstall the original first:

pip uninstall garth
pip install garth-ng

Your code stays unchanged. import garth works exactly as before.

Installation

pip install garth-ng

uv add garth-ng

The garth CLI requires typer — install the CLI extra:

pip install 'garth-ng[cli]'

Quick Start

Login and save session

import garth
from getpass import getpass

garth.configure(storage=garth.FileTokenStorage("~/.garth"))
garth.login(input("Email: "), getpass("Password: "))

MFA is handled automatically with a terminal prompt. Pass a custom handler if you need one:

garth.login(email, password, prompt_mfa=lambda: input("MFA code: "))

Resume a saved session

import garth

garth.configure(storage=garth.FileTokenStorage("~/.garth"))
print(garth.client.username)

Auto-load from environment

export GARTH_HOME=~/.garth

import garth

print(garth.client.username)  # loaded automatically

Or use a base64 token (useful in CI/containers):

export GARTH_TOKEN="eyJvYXV0aF90b2tlbi..."

Generate a token with the CLI:

garth login

For China region:

garth --domain garmin.cn login

Direct API calls

sleep = garth.connectapi(
    f"/wellness-service/wellness/dailySleepData/{garth.client.username}",
    params={"date": "2023-07-05", "nonSleepBufferMinutes": 60},
)

Stats and data

# Daily steps for the last 7 days
garth.DailySteps.list(period=7)

# Stress levels
garth.DailyStress.list("2023-07-23", 2)

# Weekly HRV
garth.DailyHRV.list(period=7)

# Sleep quality
garth.DailySleep.list(period=7)

Available stat types: DailySteps, WeeklySteps, DailyStress, WeeklyStress, DailyHRV, DailySleep, DailyHydration, DailyIntensityMinutes, WeeklyIntensityMinutes, DailyTrainingStatus, WeeklyTrainingStatus, MonthlyTrainingStatus

Available data types: SleepData, HRVData, WeightData, DailyHeartRate, BodyBatteryData, DailyBodyBatteryStress, DailySleepData, DailySummary, Activity, FitnessActivity, GarminScoresData, TrainingReadinessData, MorningTrainingReadinessData, BloodPressure, NutritionLog, NutritionSettings, NutritionStatus, PersonalRecord, PersonalRecordType, WeightGoal, StepsGoal

Activity includes sub-endpoint methods: details(), rounds(), exercise_sets(), hr_time_in_zones(), map_details(), workouts(), activity_types()

# Blood pressure
garth.BloodPressure.get("2024-01-15")
garth.BloodPressure.create(systolic=120, diastolic=80, pulse=72)

# Personal records
garth.PersonalRecord.list()
garth.PersonalRecord.for_activity(12345678901)

# Nutrition
garth.NutritionLog.get("2024-01-15")
garth.NutritionSettings.get()
garth.NutritionStatus.get()

# Goals
garth.WeightGoal.get()
garth.StepsGoal.get()

# Weight management
garth.WeightData.latest()
garth.WeightData.create(weight=75.5)

# Sleep logging
from datetime import datetime
garth.SleepData.create(
    sleep_start=datetime(2024, 1, 15, 23, 0),
    sleep_end=datetime(2024, 1, 16, 7, 0),
)

Upload an activity

with open("activity.fit", "rb") as f:
    garth.upload(f)

Configuration

garth.configure(domain="garmin.cn")        # China region
garth.configure(timeout=30)                # Request timeout (seconds)
garth.configure(retries=5, backoff_factor=1.0)  # Retry behavior
garth.configure(proxies={"https": "http://localhost:8888"}, ssl_verify=False)  # Proxy

License

MIT. Original library by Matin Tamizi. Fork maintained by CyberFossa.