refactor: single /metrics endpoint, remove /route and /heart_rate

Everything is served via /workouts/{index}/metrics — route and HR
are included in the response. Log now shows both metric and GPS counts.
Updated README, mock server, and tests.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: brtkwr

HealthKitExporter/HTTPServer.swift

@@ -128,21 +128,11 @@ final class HTTPServer: ObservableObject {
             return
         }
 
-        if let index = parseWorkoutSubpath(path: path, suffix: "heart_rate") {
-            await handleGetHeartRate(connection: connection, index: index)
-            return
-        }
-
         if let index = parseWorkoutSubpath(path: path, suffix: "metrics") {
             await handleGetMetrics(connection: connection, index: index)
             return
         }
 
-        if let index = parseWorkoutSubpath(path: path, suffix: "route") {
-            await handleGetRoute(connection: connection, index: index)
-            return
-        }
-
         sendResponse(connection: connection, status: 404, body: "{\"error\": \"Not found\"}")
     }
 
@@ -187,42 +177,6 @@ final class HTTPServer: ObservableObject {
         }
     }
 
-    @MainActor
-    private func handleGetHeartRate(connection: NWConnection, index: Int) async {
-        guard let manager = healthKitManager else {
-            sendResponse(
-                connection: connection, status: 500,
-                body: "{\"error\": \"HealthKit not available\"}")
-            return
-        }
-
-        do {
-            if cachedWorkouts == nil {
-                cachedWorkouts = try await manager.fetchWorkouts()
-            }
-
-            guard let workouts = cachedWorkouts, index >= 0, index < workouts.count else {
-                sendResponse(
-                    connection: connection, status: 404,
-                    body: "{\"error\": \"Workout not found at index \(index)\"}")
-                return
-            }
-
-            let workout = workouts[index]
-            let hrType = HKQuantityType.quantityType(forIdentifier: .heartRate)!
-            let hrUnit = HKUnit.count().unitDivided(by: .minute())
-            let hrData = try await manager.fetchQuantitySeries(
-                for: workout, quantityType: hrType, unit: hrUnit)
-            log("/workouts/\(index)/heart_rate", status: 200, detail: "\(hrData.count) points")
-            sendJSONResponse(connection: connection, object: hrData)
-        } catch {
-            log("/workouts/\(index)/heart_rate", status: 500, detail: error.localizedDescription)
-            sendResponse(
-                connection: connection, status: 500,
-                body: "{\"error\": \"\(error.localizedDescription)\"}")
-        }
-    }
-
     @MainActor
     private func handleGetMetrics(connection: NWConnection, index: Int) async {
         guard let manager = healthKitManager else {
@@ -245,8 +199,9 @@ final class HTTPServer: ObservableObject {
             }
 
             let metrics = try await manager.fetchAllMetrics(for: workouts[index])
-            let totalPoints = (metrics.values.compactMap { ($0 as? [[String: Any]])?.count }.reduce(0, +))
-            log("/workouts/\(index)/metrics", status: 200, detail: "\(totalPoints) points")
+            let routeCount = (metrics["route"] as? [[String: Any]])?.count ?? 0
+            let metricCount = metrics.values.compactMap { ($0 as? [[String: Any]])?.count }.reduce(0, +) - routeCount
+            log("/workouts/\(index)/metrics", status: 200, detail: "\(metricCount) metrics, \(routeCount) GPS")
             sendJSONResponse(connection: connection, object: metrics)
         } catch {
             log("/workouts/\(index)/metrics", status: 500, detail: error.localizedDescription)
@@ -256,37 +211,6 @@ final class HTTPServer: ObservableObject {
         }
     }
 
-    @MainActor
-    private func handleGetRoute(connection: NWConnection, index: Int) async {
-        guard let manager = healthKitManager else {
-            sendResponse(
-                connection: connection, status: 500,
-                body: "{\"error\": \"HealthKit not available\"}")
-            return
-        }
-
-        do {
-            if cachedWorkouts == nil {
-                cachedWorkouts = try await manager.fetchWorkouts()
-            }
-
-            guard let workouts = cachedWorkouts, index >= 0, index < workouts.count else {
-                sendResponse(
-                    connection: connection, status: 404,
-                    body: "{\"error\": \"Workout not found at index \(index)\"}")
-                return
-            }
-
-            let route = try await manager.fetchRoute(for: workouts[index])
-            log("/workouts/\(index)/route", status: 200, detail: "\(route.count) points")
-            sendJSONResponse(connection: connection, object: route)
-        } catch {
-            sendResponse(
-                connection: connection, status: 500,
-                body: "{\"error\": \"\(error.localizedDescription)\"}")
-        }
-    }
-
     // MARK: - Response helpers
 
     private func sendJSONResponse(connection: NWConnection, object: Any) {

README.md

@@ -1,153 +1,118 @@
-# Apple Health to Garmin Converter
+# Apple Health to Garmin
 
-Convert Apple Watch workouts from Apple Health export to **FIT** or **TCX** format for importing to Garmin Connect, Strava, TrainingPeaks, and other fitness platforms.
+Convert Apple Watch workouts to Garmin's FIT format with full-resolution heart rate, running power, stride length, vertical oscillation, and ground contact time.
 
-## Features
+Apple's "Export All Health Data" aggregates workout heart rate into low-resolution chunks. This tool bypasses that by reading HealthKit directly on the iPhone via a small sideloaded app, then converting the full-resolution data to FIT files for Garmin Connect.
 
-- Converts to FIT (recommended) or TCX format
-- Preserves per-second heart rate, GPS routes, and workout statistics
-- FIT output includes running power, stride length, vertical oscillation, and ground contact time
-- Organises workouts by year/month
-- Supports running, walking, cycling, hiking, swimming, and other workout types
+## How it works
 
-## Requirements
-
-- Python 3.11+
-- [uv](https://docs.astral.sh/uv/) (for FIT format — manages dependencies automatically)
-- Apple Health export data
-
-## How to Export Apple Health Data
+1. **iOS app** serves workout data from HealthKit over a local HTTP server
+2. **Fetch script** pulls all workouts (metrics + GPS) from the phone to your Mac
+3. **Converter** produces FIT files ready for Garmin Connect
 
-1. Open the **Apple Health** app on your iPhone
-2. Tap your **profile picture** (top right corner)
-3. Scroll down and tap **"Export All Health Data"**
-4. Tap **"Export"** to confirm
-5. **AirDrop or email** the ZIP to your Mac
-6. Extract the ZIP — you'll get a folder containing:
-   - `export.xml` — main health data including workout statistics and per-second metrics
-   - `workout-routes/` — GPX files with GPS trackpoints for each workout
-
-## Usage
+## Requirements
 
-### FIT format (recommended)
+- iPhone with Apple Health data
+- Mac with [Xcode](https://apps.apple.com/app/xcode/id497799835) (for sideloading the iOS app)
+- [uv](https://docs.astral.sh/uv/) (Python package manager)
 
-FIT is Garmin's native binary format and preserves the most data — heart rate, running power, stride length, vertical oscillation, and ground contact time.
+## Quick start
 
 ```bash
 git clone https://github.com/brtkwr/apple-to-garmin.git
 cd apple-to-garmin
-uv run convert_to_fit.py /path/to/apple_health_export
 ```
 
-Filter by activity type:
-```bash
-uv run convert_to_fit.py /path/to/export --activity running
-```
+### 1. Install the iOS app
+
+1. Open `HealthKitExporter.xcodeproj` in Xcode
+2. Set your development team in **Signing & Capabilities**
+3. Connect your iPhone via USB and hit **Run**
+4. On your iPhone: **Settings > General > VPN & Device Management** → trust the developer certificate
+
+### 2. Fetch workouts from the phone
+
+Open the app on your iPhone, tap **Start**, then from your Mac:
 
-Specify output directory:
 ```bash
-uv run convert_to_fit.py /path/to/export --output /path/to/fit/files
+python3 fetch_healthkit.py <iphone-ip>
 ```
 
-### TCX format (zero dependencies)
+This pulls all Apple Watch workouts with full-resolution metrics and GPS routes into `healthkit_export/`. Keep the phone screen on while fetching — HealthKit data is inaccessible when the screen is locked.
 
-TCX is an XML-based format that works everywhere but only supports heart rate, GPS, altitude, distance, and calories. No running dynamics.
+### 3. Convert to FIT
 
 ```bash
-python3 convert_to_tcx.py /path/to/apple_health_export
+uv run convert_healthkit_to_fit.py healthkit_export
 ```
 
-## Output Structure
-
-```text
-fit_files/                          # or tcx_files/
-├── 2024/
-│   ├── 01/
-│   │   ├── 2024-01-02_183050_Running.fit
-│   │   └── 2024-01-06_090528_Running.fit
-│   └── 02/
-│       └── 2024-02-20_182954_Running.fit
-└── 2025/
-    └── ...
-```
+FIT files are written to `fit_files/`, organised by year and month.
 
-TCX output also includes a `no_heart_rate/` subfolder for workouts without HR data.
+Filter by activity type:
 
-## What Gets Converted
+```bash
+uv run convert_healthkit_to_fit.py healthkit_export --activity running
+```
 
-| Data | FIT | TCX |
-|------|-----|-----|
-| GPS coordinates | ✅ | ✅ |
-| Heart rate (per-second) | ✅ | ✅ |
-| Distance | ✅ | ✅ |
-| Calories | ✅ | ✅ |
-| Altitude | ✅ | ✅ |
-| Running power | ✅ | ❌ |
-| Stride length | ✅ | ❌ |
-| Vertical oscillation | ✅ | ❌ |
-| Ground contact time | ✅ | ❌ |
-| Running speed | ✅ | ❌ |
+### 4. Import to Garmin Connect
 
-## Heart Rate Data
+1. Go to [Garmin Connect](https://connect.garmin.com)
+2. Click **"+"** → Import Data
+3. Upload your FIT files (can select multiple)
 
-### From the XML export
+## What gets exported
 
-Apple Health exports contain `HKQuantityTypeIdentifierHeartRate` records in `export.xml`. The FIT converter emits each HR reading at its original timestamp as a separate record alongside the GPS stream — no interpolation, highest resolution available from the export.
+| Data                 | Included |
+| -------------------- | -------- |
+| GPS coordinates      | Yes      |
+| Heart rate           | Yes      |
+| Distance             | Yes      |
+| Calories             | Yes      |
+| Altitude             | Yes      |
+| Running power        | Yes      |
+| Stride length        | Yes      |
+| Vertical oscillation | Yes      |
+| Ground contact time  | Yes      |
+| Running speed        | Yes      |
 
-### Known limitation: low-resolution HR during workouts
+## Why not use Apple's XML export?
 
-Apple's "Export All Health Data" feature aggregates workout heart rate into ~15 minute chunks. A 65-minute run might only have 23 HR records in the export, while apps like Strava (which sync via HealthKit's API directly) show a smooth per-second curve. This is a [known issue](https://discussions.apple.com/thread/253843222).
+Apple's "Export All Health Data" stores workout heart rate as aggregated records spanning ~15 minute windows. A 65-minute run might only have 23 HR data points in the export. The same workout viewed on Strava (which reads HealthKit directly) shows 513 data points.
 
-The per-second data exists on the iPhone via `HKQuantitySeriesSampleQuery`, but Apple doesn't include it in the XML export.
+This is a [known limitation](https://discussions.apple.com/thread/253843222) of Apple's XML export. The full-resolution data exists on the phone via `HKQuantitySeriesSampleQuery` — this tool accesses it.
 
-### HealthKit Exporter iOS app
+## API endpoints
 
-The `HealthKitExporter/` directory contains a SwiftUI iOS app that reads full-resolution HR and running dynamics directly from HealthKit and serves them as JSON over a local HTTP server. This bypasses the XML export limitation.
+The iOS app serves JSON on port 8080:
 
-To use it:
+| Endpoint                        | Description                           |
+| ------------------------------- | ------------------------------------- |
+| `GET /workouts`                 | List all workouts with metadata       |
+| `GET /workouts/{index}/metrics` | All metrics + GPS route for a workout |
 
-1. Open `HealthKitExporter.xcodeproj` in Xcode
-2. Set your development team in Signing & Capabilities
-3. Build and run on your iPhone
-4. The app shows the device IP and port — hit the endpoints from your Mac:
+## Development
 
-```bash
-# List all workouts
-curl http://<iphone-ip>:8080/workouts
+### Mock server
 
-# Get per-second HR for a specific workout
-curl http://<iphone-ip>:8080/workouts/0/heart_rate
+For local development and testing without a phone:
 
-# Get all metrics (HR, power, speed, stride, VO, GCT)
-curl http://<iphone-ip>:8080/workouts/0/metrics
+```bash
+python3 mock_server.py
 ```
 
-Requires Xcode and a free Apple Developer account (app expires after 7 days, re-install from Xcode as needed).
-
-## Importing to Garmin Connect
+Serves sample workouts on `http://localhost:8080` with the same API as the iOS app.
 
-1. Go to [Garmin Connect](https://connect.garmin.com)
-2. Click the **"+"** button → Import Data
-3. Upload your FIT or TCX files (can select multiple)
-4. Wait for processing — workouts will appear in your timeline
-
-## Testing
+### Tests
 
 ```bash
 uv run pytest -v
 ```
 
-Tests run automatically on GitHub Actions for Python 3.11-3.13.
-
-## Troubleshooting
+44 tests, 91% coverage. Tests use the mock server — no phone required.
 
-**"Found 0 Apple Watch workouts"**
-- Make sure you've exported from the Apple Health app (not Apple Watch app)
-- Verify the export folder contains `export.xml` and `workout-routes/`
+### CI
 
-**"No heart rate data"**
-- Early Apple Watch workouts may not have recorded heart rate
-- TCX converter saves these separately in `no_heart_rate/`
+Tests run on GitHub Actions for Python 3.11–3.14. Coverage is reported on PRs. iOS build can be triggered manually via workflow dispatch.
 
 ## License
 

mock_server.py

@@ -168,16 +168,6 @@ def do_GET(self):
                 self._send_json({"error": f"Workout not found at index {idx}"}, 404)
             return
 
-        match = re.match(r"^/workouts/(\d+)/route$", self.path)
-        if match:
-            idx = int(match.group(1))
-            if 0 <= idx < len(self.workouts or []):
-                metrics = generate_sample_metrics(self.workouts[idx])
-                self._send_json(metrics.get("route", []))
-            else:
-                self._send_json({"error": f"Workout not found at index {idx}"}, 404)
-            return
-
         self._send_json({"error": "Not found"}, 404)
 
     def _send_json(self, data, status=200):
@@ -221,7 +211,7 @@ def main():
     print("Endpoints:")
     print("  GET /workouts")
     print("  GET /workouts/{index}/metrics")
-    print("  GET /workouts/{index}/route")
+    print("  GET /workouts/{index}/heart_rate")
     try:
         server.serve_forever()
     except KeyboardInterrupt:

test_fetch_healthkit.py

@@ -125,12 +125,6 @@ def test_metrics_endpoint_invalid_index(self):
             self._fetch("/workouts/999/metrics")
         self.assertEqual(ctx.exception.code, 404)
 
-    def test_route_endpoint(self):
-        data = self._fetch("/workouts/0/route")
-        self.assertIsInstance(data, list)
-        self.assertGreater(len(data), 0)
-        self.assertIn("latitude", data[0])
-
     def test_404_for_unknown_path(self):
         import urllib.error
         with self.assertRaises(urllib.error.HTTPError) as ctx: