API & MCP

Everything a person can do on Detour Budget Planner, a program or AI agent can do with the same inputs and get the identical result.

HTTP API

POST https://hearthdetourbudget.usefulweb.app/api/v1/calculate – run Detour Budget Planner
GET https://hearthdetourbudget.usefulweb.app/api/v1/tool – inputs, output schema, examples
OpenAPI 3.1: /openapi.json · /openapi.yaml
Errors: application/problem+json; 422 includes per-field errors.

Detour Budget Planner

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.

Inputs of Detour Budget Planner
Field	Type	Default	Description
`startLat`	number	48.89	Start latitude
`startLon`	number	8.7	Start longitude
`endLat`	number	48.78	Destination latitude
`endLon`	number	9.18	Destination longitude
`mode`	select (car, bike, foot)	"car"	Travel mode
`circuityPreset`	select (ballou-europe, boscoe-us, europe-long, custom)	"ballou-europe"	Road circuity factor (estimate)
`circuity`	number	1.3	Your own circuity factor (used with “Your own factor”)
`speed`	number	0	Average speed in km/h (0 = 60 car, 15 bike, 5 on foot)
`costPerKm`	number	0.3	Cost per extra kilometre (your currency)
`budget`	number	45	Extra time including visit (minutes)
`departure`	time	"09:00"	Departure time
`maxStops`	number	1	Maximum stops in suggested itinerary
`stops`	table	[{"name":"Proposed break","lat":48.85,"lon":8.95,"stay":15},{"name":"Museum visi	Candidate stops
`network`	textarea	—	Optional road network for precise distances: OSM XML, GeoJSON with OSM tags or GPX text

Example request

Try an example

curl -X POST https://hearthdetourbudget.usefulweb.app/api/v1/calculate -H 'content-type: application/json' -d '{}'

Every result contains

inputs (normalised, defaults applied), summary, result (validated against the published schema), units, assumptions, sources, warnings, computedAt and links.

MCP (Model Context Protocol)

Streamable HTTP endpoint: https://hearthdetourbudget.usefulweb.app/mcp – protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake).
Tools: hearth_detour_budget
Local stdio connector: node src/mcp-stdio.ts --tool=hearth-detour-budget

{
  "mcpServers": {
    "hearth-detour-budget": { "type": "http", "url": "https://hearthdetourbudget.usefulweb.app/mcp" }
  }
}