Garmin Health API Analysis

SCRUM-84, Option B — Complete technical analysis for removing Strava dependency

1. Executive Summary

The Garmin Connect Developer Program provides official APIs for accessing cycling activity data including GPS tracks, speed, heart rate, power, cadence, and elevation — all fields that Strava's club endpoint lacks. The program is free, approval takes 2 business days, and production keys have no rate limits. This is the recommended path for Garmin users in the club.

Recommendation: Apply to Garmin Developer Program

Free, fast approval, complete data access, push-based architecture. Covers the majority of DCC members who use Garmin devices.

2. Data Field Comparison

Field	Strava Club API	Garmin Activity API	Impact
Distance	Yes (meters)	Yes (meters)	Equivalent
Duration	Yes (moving_time)	Yes (seconds)	Equivalent
Elevation	Yes (total gain)	Yes (ascent + descent)	Garmin has descent too
Activity Type	Yes (type, sport_type)	Yes (activityType)	Equivalent
Start Date/Time	No	Yes (startTimeInSeconds + offset)	Fixes SCRUM-69 — no more fingerprint workaround
Average Speed	No	Yes (averageSpeedInMetersPerSecond)	Fixes SCRUM-63 — device-measured, not calculated
GPS Track	No	Yes (full route via FIT file)	Enables real route-based POIs (SCRUM-83)
Heart Rate	No	Yes (avg, max, zones with durations)	New: effort/intensity analytics
Power	No	Yes (avg, max, by zone)	New: power-based coaching
Cadence	No	Yes (avg, max RPM)	New: pedalling efficiency analysis
Temperature	No	Yes (ambient from device)	New: real weather, not estimated
FIT File Download	No	Yes (raw binary file)	Complete second-by-second data
Athlete Name	Yes	Yes (from OAuth profile)	Equivalent
Rate Limits	100/15min, 1000/day	None (production key)	Unlimited refreshes

3. Architecture: Push-Based Webhook

Garmin Device
records ride

→

Garmin Connect
sync via Bluetooth/WiFi

→

Garmin Cloud
sends Ping POST

→

Cloudflare Worker
/garmin-webhook

→

Worker fetches
activity details + FIT

→

KV Cache
aggregated stats

How the Ping/Pull Architecture Works

User completes a ride and syncs their Garmin device
Garmin processes the activity and sends an HTTPS POST Ping notification to our webhook URL
Our Worker receives the ping containing the user ID and activity ID
Worker fetches the activity details (summary + FIT file) from Garmin's API
Worker parses the data, extracts all metrics (GPS, speed, HR, power, cadence, elevation)
Worker aggregates into club stats and stores in KV — same format as current /club-data response
iOS app fetches from /club-data as before — no app changes needed for basic stats

4. Partner Application Process

Step	Details	Timeline
1. Apply	Submit application at `developer.garmin.com/gc-developer-program`. Requires business name, use case description, expected user count.	30 minutes
2. Review	Garmin reviews the application. Most approvals within 2 business days.	1-2 days
3. Credentials	Receive Consumer Key + Consumer Secret. Access to evaluation environment + full API docs.	Immediate after approval
4. Integration	Build OAuth flow, webhook handler, FIT parser. Test with 2+ real Garmin accounts.	1-2 weeks dev work
5. Verification	Pass Partner Verification Tool: (a) only call summary endpoints after Ping, (b) webhook responds HTTP 200, (c) data from 2+ real accounts.	1-2 days testing
6. Production Key	Receive production key with no rate limits. Go live.	Immediate after verification

Total timeline: ~2-3 weeks from application to production.

5. Authentication Flow (OAuth 2.0)

User Authorisation (One-Time)

User taps "Connect Garmin" in the DCC app
App opens Garmin's OAuth page in a browser: https://connect.garmin.com/oauthConfirm
User logs in to Garmin Connect and grants permission
Garmin redirects back to the app with an authorisation code
Worker exchanges the code for an access token (valid 3 months) + refresh token
Tokens stored in KV per user. Auto-refresh when expired — no user action needed.
From this point, all rides sync automatically via webhook. User never touches it again.

6. Implementation Plan

Phase	Work	Effort	Files
Phase 1	Apply to Garmin Developer Program	30 min	None (web form)
Phase 2	Add `POST /garmin-webhook` endpoint to Worker. Handle Ping notifications, fetch activity details, parse into club data format.	2-3 days	cloudflare-club-data-worker.js
Phase 3	Add FIT file parser to Worker (binary format). Extract GPS track, speed, HR, power, cadence per data point.	2-3 days	New: fit-parser.js or use garmin-fit-parser npm
Phase 4	Add "Connect Garmin" button in iOS app. OAuth flow via ASWebAuthenticationSession. Store tokens via Worker.	1-2 days	New: GarminAuthView.swift
Phase 5	Merge Garmin data with existing Strava data in /club-data response. Both sources feed the same stats.	1-2 days	cloudflare-club-data-worker.js
Phase 6	Partner Verification Tool + production key	1-2 days	Testing only

Total effort: ~2 weeks of development + 2 days for Garmin approval.

7. Privacy & GDPR

Requirements

Explicit consent — Users must actively opt in to share Garmin data with DCC. No pre-ticked boxes.
Granular permissions — Only request "Activity Export" permission, not full health data.
Revoke anytime — Users can disconnect Garmin from the DCC app at any time. Must call Garmin's disconnect endpoint.
Data subject rights — Support access, rectify, erase, object, restrict, and export requests.
Privacy policy update — Must include link to Garmin Connect Privacy Policy and explain what data is collected.
Data retention — Define how long Garmin activity data is stored (recommend: same as current 60-day KV TTL).

8. Risk Assessment

Risk	Likelihood	Impact	Mitigation
Garmin rejects application	Low	High	Application is free and straightforward. Cycling club use case is standard.
FIT parsing complexity	Medium	Medium	Use established npm package (garmin-fit-parser). FIT SDK is well-documented.
User adoption friction	Medium	Medium	One-time OAuth. After that, fully automatic. Strava stays as fallback.
Garmin API changes	Low	Medium	Official API with versioning. More stable than Strava's undocumented club endpoint.
GDPR compliance burden	Medium	Low	Standard consent flow. Same pattern as existing Strava OAuth (but we use club code now).

9. What This Unlocks

Features enabled by Garmin data that are impossible with Strava

Accurate ride dates — No more fingerprint workaround. Rides assigned to the correct day.
GPS route mapping — Plot actual routes on a map. Show bike shops and cafes ON the route, not "near me".
Heart rate zones — Know how hard each ride was. Zone 2 endurance vs Zone 5 sprints.
Power analysis — FTP estimation, TSS (Training Stress Score), power-to-weight ratio.
Cadence coaching — Optimal pedalling efficiency tips based on actual RPM data.
Real weather — Device temperature sensor gives actual conditions, not estimates.
True route matching — Compare riders on the same GPS route, not just similar distance/elevation.
Unlimited data refreshes — No rate limits on production key.
Members without Strava — Garmin-only users can participate in the club.

10. Recommendation

Proceed with Official Garmin API

Apply today. Free, 2-day approval, 2 weeks to integrate. Keeps Strava as fallback. Unlocks GPS, HR, power, cadence — transforming the app from a stats viewer into a proper training platform.