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.
3.5 KiB
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)
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)
{
"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)
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)
{
"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
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
curl -X GET http://localhost:8000/api/analysis/f1e2d3c4-b5a6-9876-5432-10fedcba9876/summary
Response Example (200 OK)
{
"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"
}
}