Routesmith

Enrich and manage your Komoot planned tours with intelligent deduplication, AI-powered renaming, and automatic POI enrichment from OpenStreetMap.

Features

Turn generic "Planned Route" into rich, organized GPX files.

• 🗺️ Bulk download all your Komoot planned tours as GPX files
• 🔍 Smart deduplication - automatically find and remove duplicate routes you've saved multiple times
• 📍 POI enrichment - add useful waypoints (water, toilets, bike repair, viewpoints, castles) from OpenStreetMap, with AI-generated descriptions
• 🤖 Intelligent renaming - replace "Planowana trasa" with descriptive names like "Kraków - Tarnów via Niepołomice" using reverse geocoding and AI
• 🧹 Sync cleanup - changes apply to both Komoot and your local files
• 👀 Safe by default - preview everything with --dry-run before making changes

Example Output

╭─────────────────────────────────────────╮
│ KOMOOT AUTHENTICATION                   │
╰─────────────────────────────────────────╯

ℹ Found stored credentials, attempting login...
✓ Authentication successful!

ℹ Fetching planned tours from Komoot...
✓ Found 53 planned tours

╭─────────────────────────────────────────╮
│ DOWNLOADING GPX FILES                   │
╰─────────────────────────────────────────╯

Downloading GPX files... ━━━━━━━━━━━━━━━━ 100%
✓ Downloaded 5 new, skipped 48 existing

╭─────────────────────────────────────────╮
│ FINDING DUPLICATES                      │
╰─────────────────────────────────────────╯

Comparing routes... ━━━━━━━━━━━━━━━━━━━━ 100%
  Duplicate: Old Route ≈ New Route
ℹ Total comparisons: 1,378
✓ Found 2 duplicate groups

╭─────────────────────────────────────────╮
│ ENRICHING GPX FILES WITH POIS           │
╰─────────────────────────────────────────╯

Enriching with POIs... ━━━━━━━━━━━━━━━━━ 100%
  ✓ Kraków - Tarnów via Niepołomice: 45 POIs added
  ✓ Sunday Morning Loop: 12 POIs added

✓ Enriched 50 GPX files with 1,234 POIs

╭─────────────────────────────────────────╮
│ AI-POWERED ROUTE RENAMING               │
╰─────────────────────────────────────────╯

Renaming routes... ━━━━━━━━━━━━━━━━━━━━━ 100%

Planowana trasa
  ID: 12345678 | Distance: 45.2 km
  Type: Loop
  Current:   Planowana trasa
  Suggested: Kraków - Niepołomice Loop via Bieńczyce
  ✓ Renamed successfully

✓ Done!

Getting Started

Requirements

• Python 3.10+
• Komoot account
• OpenAI-compatible API key (required for POI descriptions and route renaming)

Installation

git clone https://github.com/edgard/routesmith.git
cd routesmith
pip install -r requirements.txt

Quick Start

# Set your API key (required)
export OPENAI_API_KEY="sk-..."

# Preview changes without executing (recommended for first run)
python routesmith.py --dry-run

# Run all steps: download, dedupe, enrich, rename
python routesmith.py

Usage

Commands

Command	Description
routesmith.py	Run all steps (same as sync)
routesmith.py sync	Run all steps: download, dedupe, enrich, rename
routesmith.py download	Download GPX files only
routesmith.py dedupe	Find and delete duplicates only
routesmith.py enrich	Add POIs to GPX files only
routesmith.py rename	AI-powered renaming only

Options

Option	Description
--dry-run	Preview changes without executing
--yes, -y	Skip confirmation prompts
--limit N, -n N	Process only first N routes
--force	Re-process already processed routes
--debug	Enable verbose output for troubleshooting

Environment Variables

# Required
export OPENAI_API_KEY="sk-..."

# Optional (defaults shown)
export OPENAI_API_BASE="https://api.openai.com/v1"
export OPENAI_MODEL="gpt-5-mini"

Compatible with: OpenAI, Anthropic Claude (via compatibility layer), Ollama, LM Studio, vLLM, or any OpenAI-compatible endpoint.

How It Works

Processing Pipeline

1. Authenticate - Login to Komoot
2. Fetch tours - Get all planned tours metadata
3. Download GPX - Cache GPX files locally (skips existing)
4. Deduplicate - Find and remove duplicates
5. Enrich POIs - Add OpenStreetMap waypoints with AI descriptions
6. AI Rename - Generate descriptive names using geocoding + POI data

Duplicate Detection

Routes are duplicates if they match ALL criteria:

• Start/end points within 1% of route length (100-300m)
• Point counts within 25%
• Sample points (8-20) mostly match within 1.5% threshold

The oldest route (lowest ID) is always kept.

POI Enrichment

Adds waypoints from OpenStreetMap:

Utilitarian: Drinking water, toilets, bike repair, bike shops, shelters

Points of Interest: Castles, viewpoints, museums, waterfalls, peaks, archaeological sites, memorials

POI count and search radius scale with route distance. AI generates brief descriptions explaining what makes each POI notable.

AI-Powered Renaming

Uses reverse geocoding (Nominatim) and an LLM to generate descriptive names:

• Place names in native spelling (e.g., "Kraków" not "Krakow")
• Format: Start - End via Notable or Start - Notable Loop
• Maximum 50 characters, no emojis

Updates: Komoot title, GPX <name> tag, and local filename.

Data Storage

~/.local/share/routesmith/
├── credentials.json    # Komoot login (plain text)
└── tours.json          # Tour metadata with tracking

routes/                 # In working directory
├── komoot_123456.gpx   # Original downloads
└── krakow_loop_123456.gpx  # After renaming

Security: Credentials are stored in plain text (Komoot doesn't provide OAuth). Set appropriate permissions: chmod 700 ~/.local/share/routesmith

Troubleshooting

Debug Mode

Use --debug to enable verbose output:

python routesmith.py --debug

Shows: API requests/responses, query sizes, token usage, full tracebacks.

Common Issues

Authentication failed

• Delete ~/.local/share/routesmith/credentials.json and re-enter credentials

No duplicates found

• Duplicate detection is precise; routes must be nearly identical
• Routes with different start/end points won't match

No POIs found

• Route may be in a remote area with few mapped POIs
• Check Overpass API status

AI renaming fails

• Verify OPENAI_API_KEY is set correctly
• Check API rate limits/quota

Known Limitations

1. Unofficial Komoot API - May break if Komoot changes their API
2. Sequential processing - Routes processed one at a time with rate limiting
3. Plain text credentials - Komoot doesn't provide OAuth
4. OSM data quality - POI completeness varies by region
5. API costs - AI features make API calls; use --limit to test

Contributing

Contributions welcome! Ideas:

1. Add new POI categories (ALL_POI_CATEGORIES)
2. Tune duplicate detection thresholds
3. Improve AI prompts
4. Add support for other platforms (Strava, Ride with GPS)

Please open an issue first to discuss major changes.

Dependencies

• kompy - Komoot API
• gpxpy - GPX parsing
• haversine - GPS calculations
• openai - AI API
• requests + requests-ratelimiter - HTTP
• rich - Terminal UI
• typer - CLI framework

License

MIT License - See LICENSE for details.

Disclaimer

This tool is not affiliated with Komoot or OpenStreetMap. It uses Komoot's unofficial API which may break at any time. Credentials are stored locally in plain text. Use at your own risk.