API & MCP
Everything a person can do on Road Trip Fuel and Charging Cost, a program or AI agent can do with the same inputs and get the identical result.
HTTP API
POST https://hearthtripenergycost.usefulweb.site/api/v1/calculate– run Road Trip Fuel and Charging CostGET https://hearthtripenergycost.usefulweb.site/api/v1/tool– inputs, output schema, examples- OpenAPI 3.1: /openapi.json · /openapi.yaml
- Errors:
application/problem+json;422includes per-fielderrors.
Road Trip Fuel and Charging Cost
Enter the legs of a road trip with the price per litre or kWh you expect in each country, your car’s consumption and extras such as tolls, vignettes or ferries. You get the energy and cost per leg, the total, the cost per 100 km and each person’s share to the cent. No routing service is used: enter the kilometres yourself or let two coordinates give an estimate.
| Field | Type | Default | Description |
|---|---|---|---|
energy | select (fuel, electric) | "fuel" | Vehicle |
consumption | number | 6.5 | Consumption per 100 km (litres or kWh) |
lossPercent | number | 0 | Charging losses (%, electric only). Energy you pay for at the charger that does not reach the battery. Enter your own figure if you know it. |
roundTrip | boolean | false | Drive every leg there and back |
legs | table | [{"label":"Munich to the Brenner","country":"Germany and Austria","km":160,"pric | Legs |
extras | table | [] | Tolls, vignettes, ferries, parking (optional) |
people | integer | 2 | Split between (people) |
names | text | — | Names (optional, comma-separated) |
currency | text | "EUR" | Currency code |
from | text | — | Estimate from (latitude, longitude; optional). With “to”, the straight-line distance × 1.46 (European road circuity) fills one leg without kilometres. |
to | text | — | Estimate to (latitude, longitude; optional) |
Example request
Munich to Venice by petrol car, Brennero toll, three people
curl -X POST https://hearthtripenergycost.usefulweb.site/api/v1/calculate -H 'content-type: application/json' -d '{"energy":"fuel","consumption":6.5,"legs":[{"label":"Munich to the Brenner","country":"Germany and Austria","km":160,"price":1.75},{"label":"Brenner to Venice","country":"Italy","km":290,"price":1.85}],"extras":[{"label":"Austrian vignette (10 days)","amount":12.4},{"label":"Brenner motorway toll","amount":11.5}],"people":3,"names":"Alex, Sam, Robin","currency":"EUR"}'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://hearthtripenergycost.usefulweb.site/mcp– protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake). - Tools:
hearth_trip_energy_cost - Local stdio connector:
node src/mcp-stdio.ts --tool=hearth-trip-energy-cost
{
"mcpServers": {
"hearth-trip-energy-cost": { "type": "http", "url": "https://hearthtripenergycost.usefulweb.site/mcp" }
}
}