garmin-training-toolkit-sdk 0.1.3

A robust, type-safe Python SDK for Garmin Connect data extraction.

Garmin Training Toolkit SDK

A robust, type-safe Python SDK for extracting biometric data and telemetry from Garmin Connect.

Purpose

This toolkit is designed as a raw data connector. It handles authentication, rate limiting, and data extraction from Garmin's unofficial APIs, returning clean, typed Pydantic models. It is built to be consumed by external Data Pipelines (like a Data Lakehouse) or AI systems (like LangGraph).

Note: This repository is strictly an SDK. It does not contain AI logic, training plan generators, or an API server (FastAPI).

Installation

This project uses uv for dependency management.

# In your consumer project (if using uv):
uv add git+https://github.com/restrok/garmin-training-toolkit-sdk.git#subdirectory=garmin_training_toolkit_sdk

Or for local development within this repository:

cd garmin_training_toolkit_sdk
uv sync

Quick Start

1. Authentication

Garmin uses session tokens. To log in and cache your session locally:

# Runs a headless browser to authenticate and save tokens
python3 garmin.py auth

2. Extracting Data (Python Example)

import json
from garmin_training_toolkit_sdk.utils import get_authenticated_client, find_token_file
from garmin_training_toolkit_sdk.extractors import get_activities, get_activity_telemetry

# 1. Connect
token_file = find_token_file()
client = get_authenticated_client(token_file)

# 2. Extract Activity Summary (Pydantic model)
activities = get_activities(client, "2026-04-10", "2026-04-20")
latest = activities[0]
print(f"Latest run: {latest.name} ({latest.distance_m} meters)")

# 3. Extract Detailed Telemetry (Second-by-second data)
telemetry = get_activity_telemetry(client, latest.id)
print(f"Total ticks: {telemetry.metric_count}")

# Pydantic makes serialization easy
print(json.dumps(telemetry.ticks[0].model_dump(), indent=2))

Available Extractors

All extractors return typed Pydantic models ensuring data reliability.

• get_activities(client, start_date, end_date)
• get_activity_telemetry(client, activity_id) -> Second-by-second telemetry (GPS, HR, Power, etc).
• get_hrv_data(client, start_date, end_date)
• get_sleep_data(client, start_date, end_date)
• get_readiness_data(client, date)
• get_body_battery(client, date)
• get_stress_data(client, date)
• get_training_status(client, date)

Included Modules

While the core focus is extraction, the SDK also bundles:

• garmin_training_toolkit_sdk.uploaders: Logic for uploading custom workout plans back to Garmin.
• garmin_training_toolkit_sdk.weather: A local SQLite-backed weather module (OpenMeteo) to enrich activity data with historical weather context.