mirror of
https://github.com/sstent/FitTrack_ReportGenerator.git
synced 2026-01-25 16:41:55 +00:00
sstent
9e0bd322d3
This commit introduces the initial version of the FitTrack Report Generator, a FastAPI application for analyzing workout files. Key features include: - Parsing of FIT, TCX, and GPX workout files. - Analysis of power, heart rate, speed, and elevation data. - Generation of summary reports and charts. - REST API for single and batch workout analysis. The project structure has been set up with a `src` directory for core logic, an `api` directory for the FastAPI application, and a `tests` directory for unit, integration, and contract tests. The development workflow is configured to use Docker and modern Python tooling.
137 lines
3.5 KiB
Markdown
137 lines
3.5 KiB
Markdown
# Quickstart Guide: FitTrack Report Generator API
|
|
|
|
This guide provides a quick overview of how to interact with the FitTrack Report Generator API.
|
|
|
|
## Base URL
|
|
|
|
The base URL for all API endpoints is `/api`.
|
|
|
|
## 1. Analyze a Single Workout File
|
|
|
|
To analyze a single workout file, send a `POST` request to the `/analyze/workout` endpoint with the workout file and optional user/FTP information.
|
|
|
|
### Endpoint
|
|
`POST /api/analyze/workout`
|
|
|
|
### Request Example (using `curl`)
|
|
|
|
```bash
|
|
curl -X POST \
|
|
-H "Content-Type: multipart/form-data" \
|
|
-F "file=@/path/to/your/workout.fit" \
|
|
-F "user_id=a1b2c3d4-e5f6-7890-1234-567890abcdef" \
|
|
-F "ftp_value=250" \
|
|
http://localhost:8000/api/analyze/workout
|
|
```
|
|
|
|
### Response Example (200 OK)
|
|
|
|
```json
|
|
{
|
|
"analysis_id": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
|
|
"user_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
|
|
"file_name": "workout.fit",
|
|
"analysis_date": "2025-10-09T10:30:00Z",
|
|
"status": "completed",
|
|
"metrics": {
|
|
"duration": "01:00:00",
|
|
"distance_km": 25.5,
|
|
"normalized_power_watts": 220,
|
|
"intensity_factor": 0.88,
|
|
"tss": 75
|
|
},
|
|
"report_url": "/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/report",
|
|
"chart_urls": {
|
|
"power_curve": "/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/charts?chart_type=power_curve"
|
|
}
|
|
}
|
|
```
|
|
|
|
## 2. Analyze Multiple Workout Files (Batch)
|
|
|
|
To analyze multiple workout files, compress them into a `.zip` file and send a `POST` request to the `/analyze/batch` endpoint.
|
|
|
|
### Endpoint
|
|
`POST /api/analyze/batch`
|
|
|
|
### Request Example (using `curl`)
|
|
|
|
```bash
|
|
curl -X POST \
|
|
-H "Content-Type: multipart/form-data" \
|
|
-F "zip_file=@/path/to/your/workouts.zip" \
|
|
-F "user_id=a1b2c3d4-e5f6-7890-1234-567890abcdef" \
|
|
http://localhost:8000/api/analyze/batch
|
|
```
|
|
|
|
### Response Example (200 OK)
|
|
|
|
```json
|
|
{
|
|
"batch_id": "g1h2i3j4-k5l6-7890-1234-567890abcdef",
|
|
"status": "processing",
|
|
"total_files": 10
|
|
}
|
|
```
|
|
|
|
## 3. Retrieve Charts for an Analysis
|
|
|
|
To get a specific chart for a previously analyzed workout, send a `GET` request to the `/analysis/{analysis_id}/charts` endpoint.
|
|
|
|
### Endpoint
|
|
`GET /api/analysis/{analysis_id}/charts`
|
|
|
|
### Path Parameters
|
|
- `analysis_id`: The unique ID of the workout analysis.
|
|
|
|
### Query Parameters
|
|
- `chart_type`: The type of chart to retrieve (e.g., `power_curve`, `elevation_profile`, `zone_distribution_power`).
|
|
|
|
### Request Example
|
|
|
|
```bash
|
|
curl -X GET http://localhost:8000/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/charts?chart_type=power_curve
|
|
```
|
|
|
|
### Response
|
|
|
|
Returns a PNG image of the requested chart.
|
|
|
|
## 4. Retrieve Analysis Summary
|
|
|
|
To get a detailed summary of a previously analyzed workout, send a `GET` request to the `/analysis/{analysis_id}/summary` endpoint.
|
|
|
|
### Endpoint
|
|
`GET /api/analysis/{analysis_id}/summary`
|
|
|
|
### Path Parameters
|
|
- `analysis_id`: The unique ID of the workout analysis.
|
|
|
|
### Request Example
|
|
|
|
```bash
|
|
curl -X GET http://localhost:8000/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/summary
|
|
```
|
|
|
|
### Response Example (200 OK)
|
|
|
|
```json
|
|
{
|
|
"analysis_id": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
|
|
"user_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
|
|
"file_name": "workout.fit",
|
|
"analysis_date": "2025-10-09T10:30:00Z",
|
|
"status": "completed",
|
|
"metrics": {
|
|
"duration": "01:00:00",
|
|
"distance_km": 25.5,
|
|
"normalized_power_watts": 220,
|
|
"intensity_factor": 0.88,
|
|
"tss": 75
|
|
},
|
|
"report_url": "/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/report",
|
|
"chart_urls": {
|
|
"power_curve": "/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/charts?chart_type=power_curve"
|
|
}
|
|
}
|
|
``` |