{ "openapi": "3.1.1", "info": { "title": "Detour Budget Planner API", "version": "1.0.0", "summary": "Compare proposed stops by estimated extra distance, time, cost and visit duration.", "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp." }, "servers": [ { "url": "https://hearthdetourbudget.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Compare proposed stops by estimated extra distance, time, cost and visit duration.", "description": "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.\n\nMethodology:\n- 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 \u0026 Sakai 2002, Transportation Research Part A 36(9)), 1.42 for the United States (Boscoe, Henry \u0026 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.\n- 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.\n- 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.\n- 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.", "tags": [ "apps" ], "x-mcp-tool": "hearth_detour_budget", "x-owner-app": "hearth", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthDetourBudgetInput" }, "examples": { "example1": { "summary": "Try an example", "value": {} } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthDetourBudgetResult" } } } }, "400": { "description": "Malformed JSON body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Invalid input (see errors[]).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/api/v1/tool": { "get": { "operationId": "getToolDefinition", "summary": "Inputs, output schema and examples for this tool", "responses": { "200": { "description": "Tool definition.", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details. 422 responses include per-field `errors`.", "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } }, "HearthDetourBudgetInput": { "type": "object", "additionalProperties": false, "properties": { "startLat": { "title": "Start latitude", "type": "number", "minimum": -90, "maximum": 90, "default": 48.89 }, "startLon": { "title": "Start longitude", "type": "number", "minimum": -180, "maximum": 180, "default": 8.7 }, "endLat": { "title": "Destination latitude", "type": "number", "minimum": -90, "maximum": 90, "default": 48.78 }, "endLon": { "title": "Destination longitude", "type": "number", "minimum": -180, "maximum": 180, "default": 9.18 }, "mode": { "title": "Travel mode", "type": "string", "enum": [ "car", "bike", "foot" ], "default": "car" }, "circuityPreset": { "title": "Road circuity factor (estimate)", "type": "string", "enum": [ "ballou-europe", "boscoe-us", "europe-long", "custom" ], "default": "ballou-europe" }, "circuity": { "title": "Your own circuity factor (used with “Your own factor”)", "type": "number", "minimum": 1, "maximum": 3, "default": 1.3 }, "speed": { "title": "Average speed in km/h (0 = 60 car, 15 bike, 5 on foot)", "type": "number", "minimum": 0, "maximum": 200, "default": 0 }, "costPerKm": { "title": "Cost per extra kilometre (your currency)", "type": "number", "minimum": 0, "maximum": 100, "default": 0.3 }, "budget": { "title": "Extra time including visit (minutes)", "type": "number", "minimum": 0, "maximum": 1440, "default": 45 }, "departure": { "title": "Departure time", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "default": "09:00" }, "maxStops": { "title": "Maximum stops in suggested itinerary", "type": "number", "minimum": 1, "maximum": 3, "default": 1 }, "stops": { "title": "Candidate stops", "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "title": "name", "type": "string", "maxLength": 100000 }, "lat": { "title": "Latitude", "type": "number", "minimum": -1000000000, "maximum": 1000000000 }, "lon": { "title": "Longitude", "type": "number", "minimum": -1000000000, "maximum": 1000000000 }, "stay": { "title": "Visit duration (minutes)", "type": "number", "minimum": -1000000000, "maximum": 1000000000 }, "openTime": { "title": "Opens (optional)", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }, "closeTime": { "title": "Closes (optional)", "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" } }, "required": [ "name", "lat", "lon", "stay" ] }, "default": [ { "name": "Proposed break", "lat": 48.85, "lon": 8.95, "stay": 15 }, { "name": "Museum visit", "lat": 48.8, "lon": 8.85, "stay": 45 } ] }, "network": { "title": "Optional road network for precise distances: OSM XML, GeoJSON with OSM tags or GPX text", "type": "string", "maxLength": 8000000, "default": "" } }, "required": [] }, "HearthDetourBudgetResult": { "type": "object", "additionalProperties": false, "required": [ "schemaVersion", "tool", "computedAt", "inputs", "summary", "result", "units", "assumptions", "sources", "warnings", "presentation", "links" ], "properties": { "schemaVersion": { "type": "string", "const": "1.0" }, "tool": { "type": "object", "additionalProperties": false, "required": [ "id", "name", "version" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "version": { "type": "string" } } }, "computedAt": { "type": "string", "format": "date-time" }, "inputs": { "type": "object", "description": "Normalised inputs actually used, including applied defaults." }, "summary": { "type": "string" }, "result": { "type": "object", "additionalProperties": false, "required": [ "method", "circuity", "circuitySource", "speedKmh", "costPerKm", "baselineMinutes", "baselineKm", "stops", "departure", "itinerary", "itineraryExtraMinutes", "itineraryExtraKm", "itineraryExtraCost", "arrivalTime", "snaps", "networkFormat", "attribution", "warnings" ], "properties": { "method": { "type": "string" }, "circuity": { "type": [ "number", "null" ] }, "circuitySource": { "type": "string" }, "speedKmh": { "type": "number" }, "costPerKm": { "type": "number" }, "baselineMinutes": { "type": "number" }, "baselineKm": { "type": [ "number", "null" ] }, "stops": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "extraMinutes", "extraKm", "extraCost", "stayMinutes", "withinBudget", "arrivalTime", "departureTime", "waitMinutes", "insideOpeningHours" ], "properties": { "name": { "type": "string" }, "extraMinutes": { "type": [ "number", "null" ] }, "extraKm": { "type": [ "number", "null" ] }, "extraCost": { "type": [ "number", "null" ] }, "stayMinutes": { "type": "number" }, "withinBudget": { "type": "boolean" }, "arrivalTime": { "type": "string" }, "departureTime": { "type": "string" }, "waitMinutes": { "type": "number" }, "insideOpeningHours": { "type": "boolean" } } } }, "departure": { "type": "string" }, "itinerary": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "arrivalTime", "departureTime", "stayMinutes", "waitMinutes" ], "properties": { "name": { "type": "string" }, "arrivalTime": { "type": "string" }, "departureTime": { "type": "string" }, "stayMinutes": { "type": "number" }, "waitMinutes": { "type": "number" } } } }, "itineraryExtraMinutes": { "type": [ "number", "null" ] }, "itineraryExtraKm": { "type": [ "number", "null" ] }, "itineraryExtraCost": { "type": [ "number", "null" ] }, "arrivalTime": { "type": "string" }, "snaps": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "point", "metres" ], "properties": { "point": { "type": "string" }, "metres": { "type": "number" } } } }, "networkFormat": { "type": "string" }, "attribution": { "type": "string" }, "warnings": { "type": "array", "items": { "type": "string" } } } }, "units": { "type": "object", "additionalProperties": { "type": "string" } }, "assumptions": { "type": "array", "items": { "type": "string" } }, "sources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "title" ], "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "publisher": { "type": "string" }, "retrievedAt": { "type": "string" }, "note": { "type": "string" } } } }, "warnings": { "type": "array", "items": { "type": "string" } }, "presentation": { "type": "array", "items": { "type": "object" }, "description": "Display blocks used by the human page (same data)." }, "links": { "type": "object", "additionalProperties": false, "required": [ "human", "api", "openapi", "methodology" ], "properties": { "human": { "type": "string", "format": "uri" }, "api": { "type": "string", "format": "uri" }, "openapi": { "type": "string", "format": "uri" }, "methodology": { "type": "string", "format": "uri" } } } } } } } }