price-route-optimizer

name	price-route-optimizer
description	Optimize travel costs by exploring alternative routes, nearby airports, and different accommodation neighborhoods. Compare flying direct vs connecting, staying central vs outskirts, and multi-city options. Use when user wants cheapest total trip cost, flexible routing options, or cost-saving alternatives to direct routes.

Price & Route Optimizer

Find the cheapest way to get there and stay there — even if it's not the obvious way.

Capabilities

• Multi-airport search: Compare prices to nearby airports
• Route alternatives: Direct vs 1-stop vs 2-stop flights
• Neighborhood optimization: Central vs outskirts pricing
• Multi-city options: Open-jaw, stopover deals
• Package comparison: Flight+hotel bundles vs separate booking
• Ground transport factor: Include train/bus to/from alternative airports
• Total cost view: Flight + stay + transport + taxes

Quick Usage

python3 scripts/optimize_price.py \
  --origin SIN \
  --destination BKK \
  --city Bangkok \
  --depart 2025-05-15 \
  --return 2025-05-20 \
  --passengers 2 \
  --optimize total

Parameters

Flag	Description	Example
--origin	Primary origin	SIN, KUL
--destination	Primary destination	BKK, NRT
--alt-origins	Nearby airports	JHB,XSP
--alt-destinations	Nearby airports	DMK,CNX
--city	Final destination city	Bangkok
--depart	Departure date	2025-05-15
--return	Return date	2025-05-20
--passengers	Number of travelers	1, 2
--cabin	Class	economy, business
--optimize	Goal	total, flight, stay, balanced
--max-ground-cost	Budget for ground transport	50, 100 (USD)
--neighborhoods	Areas to compare	all, central, budget

Route Options Explored

Flight Routes

1. Direct — A → B (baseline)
2. 1-stop — A → C → B (often cheaper)
3. Self-transfer — A → C (separate ticket C → B)
4. Multi-city — A → B → C → A (open-jaw)

Airport Alternatives

• Primary: Usually largest, most expensive
• Secondary: Budget airlines, often cheaper
• Nearby cities: Fly to different city + ground transport

Accommodation Strategies

• Central: Walkable, transit-connected, expensive
• Transit hubs: Near MRT/BTS stations, mid-price
• Outskirts: Cheap, requires transport
• Hostels/Budget: Shared facilities, lowest cost

Optimization Strategies

Strategy	What it does	Best for
total	Minimize flight + stay + transport	Budget travelers
flight	Cheapest flight only	Flight price sensitive
stay	Cheapest accommodation	Long stays
balanced	Good value at fair price	Most travelers
time	Minimize total travel time	Business travelers

Output: Price-Optimized Options

Top 5 Total Cost Combinations

Each option shows:

• ✈️ Flight route: Origin → Destination (stops)
• 💰 Flight price: Per person, total
• 🏨 Stay area: Neighborhood, price/night
• 💰 Stay total: For entire trip
• 🚗 Ground transport: Airport to city, city to hotel
• 💰 Ground cost: Trains, buses, taxis
• 🧾 Total cost: Everything included
• 📊 Savings vs direct: How much you save
• ⏱️ Time cost: Extra hours vs direct

Smart Suggestions

• "Fly to DMK instead of BKK" — Save $40, add 30 min bus
• "Stay near BTS On Nut" — 50% cheaper, 20 min to center
• "1-stop in KUL" — Save $80, add 3 hours
• "Self-transfer" — Risky but can save 30%+

How It Works

FOR each candidate date range:
    1. READ all airport options (primary + alternatives)
    2. FETCH flight prices for each route
    3. FETCH hotel prices for each neighborhood
    4. FETCH ground transport for each airport
    5. COMBINE all options → Calculate total cost
    6. COMPUTE cost vs duration trade-off
    7. RANK → Best value options

OUTPUT: Top 5 date/route/neighborhood combinations

Integration

Called by SmartTripClaw for each candidate window:

# For each calendar window found
for window in calendar_windows:
    # Find best route/neighborhood for these dates
    best_option = PriceRouteOptimizer.optimize(
        dates=window,
        origin="SIN",
        destination="BKK"
    )
    window['route'] = best_option

Data Sources

• Flights: Amadeus, Skyscanner, Google Flights
• Ground transport: Rome2Rio, 12Go, local transit APIs
• Hotels: Booking.com, Agoda (by neighborhood)
• Route data: FlightConnections, Rome2Rio

See Also

• references/alternative_airports.md — Secondary airports by region
• references/ground_transport.md — Airport transfer costs/times
• references/neighborhood_prices.md — Hotel price maps by city