TrailOne GPX FastAPI Bundle

This service exposes a small REST API for processing GPX trail data. It can validate uploaded files, compute elevation statistics, generate trail waypoints, and return enriched GPX files for download.

What the API provides

The API currently supports:

• health checks
• GPX file analysis
• elevation statistics
• trail waypoint generation
• point-to-point 3D distance calculation

Project layout

trailone_fastapi_bundle/
├── app/
│   ├── api/routes.py
│   ├── core/
│   ├── models/
│   ├── services/
│   └── main.py
├── Dockerfile
├── requirements.txt
└── .env.example

Installation

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run locally

uvicorn app.main:app --reload

The service will be available at:

• http://localhost:8000/docs
• http://localhost:8000/redoc

Configuration

The app uses environment variables with the TRAILONE_ prefix. The main configurable values are:

• TRAILONE_APP_NAME
• TRAILONE_APP_VERSION
• TRAILONE_DEBUG
• TRAILONE_LOG_LEVEL
• TRAILONE_MAX_UPLOAD_SIZE_BYTES
• TRAILONE_MAX_POINTS
• TRAILONE_TEMP_OUTPUT_DIR

Example:

export TRAILONE_MAX_UPLOAD_SIZE_BYTES=20971520
export TRAILONE_MAX_POINTS=200000

API reference

Base URL: http://localhost:8000/v1/gpx

1) Health: live

Checks that the API is responding.

• Method: GET
• Path: /v1/gpx/health/live

Example:

curl http://localhost:8000/v1/gpx/health/live

Example response:

{"status": "ok"}

2) Health: ready

Returns readiness information and service limits.

• Method: GET
• Path: /v1/gpx/health/ready

Example:

curl http://localhost:8000/v1/gpx/health/ready

Example response:

{
  "status": "ready",
  "app_name": "TrailOne GPX API",
  "version": "1.0.0",
  "max_points": 200000
}

3) Analyze GPX

Parses and validates an uploaded GPX file and returns a summary of the route structure plus elevation stats.

• Method: POST
• Path: /v1/gpx/analyze
• Form field: file (multipart upload)

Example:

curl -X POST \
  -F "file=@trail.gpx" \
  http://localhost:8000/v1/gpx/analyze

Example response:

{
  "tracks": 1,
  "segments": 1,
  "total_points": 1200,
  "elevation_statistics": {
    "total_ascent": 842.5,
    "total_descent": 810.2,
    "max_elevation": 1465.0,
    "min_elevation": 320.0,
    "elevation_range": 1145.0
  }
}

4) Elevation analysis

This endpoint is functionally the same as the analyze endpoint and returns the same structure.

• Method: POST
• Path: /v1/gpx/elevation
• Form field: file (multipart upload)

Example:

curl -X POST \
  -F "file=@trail.gpx" \
  http://localhost:8000/v1/gpx/elevation

5) Generate waypoints

Creates a waypoint-enriched GPX file from the uploaded track. It generates markers such as trail head, kilometer markers, halfway point, trail end, highest point, and lowest point.

• Method: POST
• Path: /v1/gpx/generate-waypoints
• Form fields:
  • file: GPX file upload
  • trail_prefix: 3-6 uppercase letters, for example LCST
  • step_size: distance interval in kilometers
  • distance_method: auto, geodesic, or haversine

Example:

curl -X POST \
  -F "file=@trail.gpx" \
  -F "trail_prefix=LCST" \
  -F "step_size=2" \
  -F "distance_method=auto" \
  http://localhost:8000/v1/gpx/generate-waypoints \
  --output lcst_waypoints.gpx

Response behavior:

• Returns the enriched GPX file as a binary download
• Includes these response headers:
  • Content-Disposition
  • X-Waypoints-Generated

Example response header values:

X-Waypoints-Generated: 12

6) Calculate distance between two points

Calculates a 3D distance between two coordinates using the selected method.

• Method: POST
• Path: /v1/gpx/distance
• Body: JSON object

Example request:

curl -X POST http://localhost:8000/v1/gpx/distance \
  -H "Content-Type: application/json" \
  -d '{
    "point1": {
      "latitude": 12.1234,
      "longitude": -86.2345,
      "elevation": 500
    },
    "point2": {
      "latitude": 12.1300,
      "longitude": -86.2400,
      "elevation": 620
    },
    "distance_method": "auto",
    "dataset_size": 1000
  }'

Example response:

{
  "distance_m": 1287.345,
  "distance_km": 1.287345,
  "distance_method_used": "geodesic"
}

Request and response model notes

trail_prefix

Must contain 3-6 uppercase letters.

Example values:

• LCST
• HIK
• MNTN

step_size

The interval in kilometers between generated distance markers.

Example values:

• 1
• 2
• 5

distance_method

Valid values:

• auto
• geodesic
• haversine

When auto is selected, the service chooses haversine for large datasets and geodesic otherwise.

Error handling

The API uses clear HTTP error responses for invalid input or processing problems.

Typical errors include:

• invalid GPX content
• empty or oversized uploads
• missing track or segment data
• invalid coordinate values
• invalid trail prefix or step size

Example error response:

{
  "detail": "Trail prefix must contain 3-6 uppercase letters (example: HIK, LCST)."
}

Example workflow

A typical usage flow is:

1. Upload a GPX file to /v1/gpx/analyze.
2. Review the elevation and route summary.
3. Call /v1/gpx/generate-waypoints with a prefix and step size.
4. Download the returned GPX file and use it in your mapping app.

Production notes

This bundle includes deployment-friendly characteristics compared with the original CLI approach:

• separation of transport, schema, and service layers
• centralized exception handling
• environment-backed settings
• request-size and point-count limits
• byte-oriented GPX parsing for uploaded files
• in-memory GPX generation instead of persistent artifact sprawl
• Docker packaging

Relationship to the original script

The computational core still follows the original GPX waypoint generation approach, but the CLI-specific concerns were removed and replaced with a REST API layer for easier integration and deployment.