Plan Tour Route

---
name: plan-tour-route
locale: caveman-ultra
source_locale: en
source_commit: 82c77053
fence_basis_commit: 82c77053
translator: "Julius Brussee homage — caveman"
translation_date: "2026-04-26"
description: >
  Plan multi-stop tour route: waypoint optimization, drive/walk time est, POI
  discovery via OSM. Covers geocoding, nearest-neighbor + TSP ordering,
  time/distance matrix, itinerary w/ POIs. Use → road trip or walking tour
  multi-dest, optimize visit order, discover sites, compare drive/walk/transit.
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob WebFetch WebSearch
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: travel
  complexity: intermediate
  language: multi
  tags: travel, routing, waypoints, osm, itinerary
---

# Plan Tour Route

Plan + optimize multi-stop tour: time est, distance, POIs along way.

## Use When

- Road trip or walking tour w/ multiple destinations
- Optimize visit order → min total travel time/distance
- Discover restaurants, viewpoints, cultural sites along route
- Day-by-day itinerary w/ realistic time budgets
- Compare driving vs walking vs transit

## In

- **Required**: Waypoint list (place names, addresses, coordinates)
- **Required**: Travel mode (driving, walking, cycling, transit)
- **Optional**: Start + end (if different from first/last waypoint)
- **Optional**: Time constraints (departure, must-arrive-by, opening hours)
- **Optional**: POI categories (food, viewpoints, museums, fuel)
- **Optional**: Route type pref (fastest, shortest, scenic)

## Do

### Step 1: Define Waypoints

Collect + structure all stops.

```text
Waypoint Schema:
┌──────────┬────────────────────────────────────────────┐
│ Field    │ Description                                │
├──────────┼────────────────────────────────────────────┤
│ name     │ Human-readable label for the stop          │
│ address  │ Street address or place name               │
│ lat/lon  │ Coordinates (if known; otherwise geocode)  │
│ duration │ Time to spend at this stop (minutes)       │
│ priority │ Must-visit vs. nice-to-have                │
│ hours    │ Opening/closing times (if applicable)      │
│ notes    │ Parking, accessibility, booking required    │
└──────────┴────────────────────────────────────────────┘
```

Separate fixed-order (hotel start/end) from reorderable.

→ Structured waypoint list w/ min name + address or coordinates each.

If err: ambiguous waypoint ("the castle") → WebSearch to resolve. Coordinates needed but only name → Step 2 geocoding.

### Step 2: Geocode + Validate

Convert waypoints → lat/lon, verify reachable.

```text
Geocoding Sources (in preference order):
1. Nominatim (OpenStreetMap) - free, no key required
   https://nominatim.openstreetmap.org/search?q=QUERY&format=json

2. Overpass API - for POI-type queries
   https://overpass-api.de/api/interpreter

3. Manual coordinates from mapping services
```

Per waypoint:
1. Query geocoding service w/ address or name
2. Verify returned coords in expected region
3. Multiple results → disambiguate (pick correct)
4. Store coords w/ waypoint data

→ Every waypoint has valid lat/lon, all in plausible region (no continent outliers).

If err: no results → try alt spellings, add region/country qualifiers, search nearby landmarks. Remote area w/ poor OSM coverage → WebSearch travel blogs/tourism sites.

### Step 3: Optimize Route Order

Visit sequence → min total travel time/distance.

```text
Optimization Strategies:
┌─────────────────────┬────────────────────────────────────────┐
│ Strategy            │ When to use                            │
├─────────────────────┼────────────────────────────────────────┤
│ Fixed order         │ Stops must be visited in given sequence│
│ Nearest neighbor    │ Quick approximation for 5-15 stops     │
│ TSP solver          │ Optimal ordering for any number        │
│ Time-window aware   │ Stops have opening hours constraints   │
│ Cluster-then-route  │ Stops span multiple days/regions       │
└─────────────────────┴────────────────────────────────────────┘
```

Nearest-neighbor heuristic:
1. Start at origin
2. From current pos, pick unvisited closest by travel time
3. Move + mark visited
4. Repeat until all visited
5. Return to end (if round trip)

Multi-day → cluster by geo proximity first, then optimize within day.

→ Ordered waypoint sequence, no excessive backtracking. Total distance within 20% of theoretical optimum for <10 stops.

If err: nearest-neighbor obvious backtracking (later stops closer to earlier) → reverse route or 2-opt: swap pairs, keep if shortens. Time-window constraints → verify arrival w/in opening hours.

### Step 4: Calc Times + Distances

Compute travel time + distance per leg.

```text
Time Estimation Methods:
┌──────────────┬────────────┬────────────────────────────────┐
│ Mode         │ Avg Speed  │ Notes                          │
├──────────────┼────────────┼────────────────────────────────┤
│ Highway      │ 100 km/h   │ Varies by country/road type    │
│ Rural road   │ 60 km/h    │ Add 20% for winding roads      │
│ City driving │ 30 km/h    │ Add time for parking            │
│ Walking      │ 4.5 km/h   │ Flat terrain; reduce for hills │
│ Cycling      │ 15 km/h    │ Touring pace with luggage      │
│ Hiking       │ 3-4 km/h   │ Use Munter formula for accuracy│
└──────────────┴────────────┴────────────────────────────────┘
```

Per consecutive pair:
1. Straight-line (haversine) distance baseline
2. Detour factor (1.3 roads, 1.4 urban, 1.2 highways)
3. Travel time from adjusted distance + mode speed
4. Buffer: 10% driving, 15% transit
5. Sum legs + dwell times → total tour duration

→ Time/distance matrix, running cumulative time covering travel + dwell. Total realistic (within available daylight for walking).

If err: estimates unrealistic (2 hrs for 10 km city drive) → check detour factor. Mountain roads → 1.6-2.0. Transit → WebSearch actual timetables.

### Step 5: Generate Itinerary w/ POIs

Compile route → complete itinerary w/ discovered POIs.

```text
POI Discovery (Overpass API query pattern):
  [out:json];
  (
    node["tourism"="viewpoint"](around:RADIUS,LAT,LON);
    node["amenity"="restaurant"](around:RADIUS,LAT,LON);
    node["amenity"="cafe"](around:RADIUS,LAT,LON);
  );
  out body;

Recommended search radius:
- Along route corridor: 500 m for walking, 2 km for driving
- At waypoints: 1 km radius
```

Build itinerary doc:
1. Header: tour name, dates, total distance, total time
2. Per day (multi-day):
   - Day summary (start, end, total km, hrs)
   - Per leg: departure, mode, distance, duration
   - Per stop: arrival, dwell, desc, nearby POIs
3. Logistics: parking, fuel, rest, emergency contacts
4. Map ref (link to OSM or GPX export)

→ Complete time-budgeted itinerary w/ realistic schedules, POI suggestions, practical logistics.

If err: POI queries → too many → filter by rating/relevance. Itinerary exceeds time → mark low-pri optional or add days. No POIs in remote → note + suggest local research on arrival.

## Check

- [ ] All waypoints geocoded w/ valid coords
- [ ] Route order min backtracking
- [ ] Travel times realistic for mode
- [ ] Dwell times accounted
- [ ] Total tour duration fits time window
- [ ] POIs relevant + near route
- [ ] Opening hours of time-sensitive stops respected
- [ ] Itinerary has practical logistics (parking, fuel, rest)

## Traps

- **Ignore opening hours**: Optimize only by distance → arrive after museum closes. Check time-window constraints.
- **Underestimate urban**: City driving + parking → double expected time. Add buffers for urban stops.
- **Over-pack itinerary**: Every minute filled → no room for delays/spontaneous. Build 30-60 min slack per half-day.
- **Straight-line fallacy**: Haversine severely underestimates road distance, especially mountainous/coastal. Always apply detour factor.
- **Forget return logistics**: One-way routes → plan for rental return, train, pickup.
- **Seasonal closures**: Mountain passes, ferries, scenic routes → seasonal closures. Verify access dates.

## →

- `create-spatial-visualization` — render planned route on interactive map
- `generate-tour-report` — compile itinerary → formatted Quarto report
- `plan-hiking-tour` — specialized planning for hiking segments
- `assess-trail-conditions` — check conditions for walking/hiking legs