# Detour Budget Planner

> Compare proposed stops by estimated extra distance, time, cost and visit duration. Enter start, destination and candidate stop coordinates. Estimate extra kilometres, minutes and cost from a published road circuity factor, or route on your own OpenStreetMap extract or GPX file. Nothing is sent to a routing service.

Part of usefulweb.app (https://usefulweb.app/). Part of [Hearth](https://hearth.usefulweb.app/) (ownerApp: hearth). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://hearthdetourbudget.usefulweb.app/ (interactive tool at https://hearthdetourbudget.usefulweb.app/tool)
- JSON API: POST https://hearthdetourbudget.usefulweb.app/api/v1/calculate with a JSON object of inputs (schema: https://hearthdetourbudget.usefulweb.app/api/v1/tool)
- OpenAPI: https://hearthdetourbudget.usefulweb.app/openapi.json
- MCP (Streamable HTTP): https://hearthdetourbudget.usefulweb.app/mcp - tool `hearth_detour_budget`

## Inputs
- startLat (number): Start latitude
- startLon (number): Start longitude
- endLat (number): Destination latitude
- endLon (number): Destination longitude
- mode (select): Travel mode
- circuityPreset (select): Road circuity factor (estimate)
- circuity (number): Your own circuity factor (used with “Your own factor”)
- speed (number): Average speed in km/h (0 = 60 car, 15 bike, 5 on foot)
- costPerKm (number): Cost per extra kilometre (your currency)
- budget (number): Extra time including visit (minutes)
- departure (time): Departure time
- maxStops (number): Maximum stops in suggested itinerary
- stops (table): Candidate stops
- network (textarea): Optional road network for precise distances: OSM XML, GeoJSON with OSM tags or GPX text

## Method
- Estimate (default): WGS84 geodesic distance (Karney 2013) between every pair of points, multiplied by a road circuity factor. Published factors: 1.46 for Europe (Ballou, Rahardja & Sakai 2002, Transportation Research Part A 36(9)), 1.42 for the United States (Boscoe, Henry & Zdeb 2012, The Professional Geographer 64(2)) and a median of 1.25 for long road trips between continental European countries (Networks and Spatial Economics 2026). Short trips, rivers, lakes and mountains are often more circuitous; enter your own factor when you know better. The factors were measured on road networks; walking and cycling networks can differ.
- Precise mode (optional): paste or open your own OpenStreetMap extract (OSM XML or GeoJSON with OSM tags) or a GPX file. Cartograph’s road graph and Dijkstra shortest paths give network distances. Cars use public roads and respect one-way streets; bikes and walkers follow Cartograph’s access rules. Each point is joined to the nearest node of a usable way within 1 km by a straight connector. GPX lines are treated as two-way ways. Map data stays with you: no routing, geocoding or map-tile service is contacted.
- Time = distance ÷ average speed (editable; defaults 60 km/h by car, 15 km/h by bike and 5 km/h on foot are assumptions, not measured). Cost = extra kilometres × your cost per kilometre. No live traffic, speed limits, turn restrictions or elevation.
- Compare stops individually, or search all ordered subsets of up to three stops. The suggested itinerary maximizes the number of visits within the budget, then minimizes added time. Optional opening/closing times are your own same-day assumptions; a closing time earlier than opening means the following day. Waiting and visits count toward the extra-time budget.