API & MCP
Everything a person can do on Ledgerly Heat Pump Estimate, a program or AI agent can do with the same inputs and get the identical result.
HTTP API
POST https://ledgerlyheatpumpestimate.usefulweb.app/api/v1/calculate– run Ledgerly Heat Pump EstimateGET https://ledgerlyheatpumpestimate.usefulweb.app/api/v1/tool– inputs, output schema, examples- OpenAPI 3.1: /openapi.json · /openapi.yaml
- Errors:
application/problem+json;422includes per-fielderrors.
Ledgerly Heat Pump Estimate
Turns your past gas, oil, LPG or pellet use into heat demand, spreads it over the year with the outdoor temperatures (DWD climate normals or your own), and estimates the heat pump’s electricity from a temperature-dependent COP and heating curve. Compares running costs and CO₂ with your boiler, and shows the heat load on the coldest day and the payback of the investment. Part of Ledgerly’s Solar & Heat.
| Field | Type | Default | Description |
|---|---|---|---|
currency | text | "EUR" | Currency |
latitude | number | 52.52 | Latitude (°, south negative) |
longitude | number | 13.405 | Longitude (°, west negative) |
climate | select (auto, manual) | "auto" | Outdoor temperatures |
monthlyTemperatures | text | — | Monthly mean temperatures (°C, 12 values, Jan–Dec) |
elevation | number | — | Height of the house above sea level (m; empty = like the station) |
fuel | select (gas, oil, lpg, pellets) | "gas" | Current heating |
fuelUse | number | 20000 | Fuel used per year (from your bills) |
fuelUnit | select (kwh, m3, litre, kg) | "kwh" | Unit of the fuel use |
boilerEfficiencyPercent | number | 90 | Efficiency of the old boiler (%). Condensing gas boilers about 90–95 %, older boilers 75–85 %. |
hotWaterPercent | number | 15 | Share for hot water (%) |
heatingLimitC | number | 15 | Heating limit temperature (°C). Above this outdoor temperature the house needs no heating. |
designTempC | number | -12 | Coldest design temperature (°C) |
heatPumpType | select (air, ground) | "air" | Heat pump type |
flowTempC | number | 50 | Flow temperature on the coldest day (°C). Underfloor heating 30–35 °C, large radiators 45–55 °C, small old radiators 60–70 °C. |
hotWaterTempC | number | 50 | Hot water temperature (°C) |
carnotEfficiencyPercent | number | 40 | Heat pump quality (% of the ideal Carnot COP). Good current units reach about 40–50 % of the ideal value; 40 % is a cautious default that also covers defrosting. |
fuelPrice | number | — | Fuel price per unit of the fuel use (empty = example price). Example prices when empty: gas 0.11 per kWh, oil 1.00 per litre, LPG 0.80 per litre, pellets 0.35 per kg (per kWh: about a tenth). Enter your own price. |
boilerFixedPerYear | number | 350 | Fixed boiler costs per year (standing charge, service, chimney sweep) |
electricityPrice | number | 0.28 | Heat pump electricity price per kWh |
heatPumpFixedPerYear | number | 200 | Fixed heat pump costs per year (meter, service) |
investment | number | 30000 | Heat pump price incl. installation (0 = skip payback) |
subsidy | number | 0 | Subsidies |
fuelCo2 | number | — | CO₂ of the fuel (kg per kWh; empty = German GEG value) |
electricityCo2 | number | 0.406 | CO₂ of grid power (kg per kWh). Default: German mix 2025 incl. upstream emissions (Umweltbundesamt). |
Example request
Berlin, 20,000 kWh gas, radiators at 50 °C
curl -X POST https://ledgerlyheatpumpestimate.usefulweb.app/api/v1/calculate -H 'content-type: application/json' -d '{"latitude":52.52,"longitude":13.405,"fuel":"gas","fuelUse":20000,"fuelUnit":"kwh","flowTempC":50,"fuelPrice":0.11}'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://ledgerlyheatpumpestimate.usefulweb.app/mcp– protocol revisions 2026-07-28 (stateless) and 2025-11-25 / 2025-06-18 / 2025-03-26 (initialize handshake). - Tools:
ledgerly_heat_pump_estimate - Local stdio connector:
node src/mcp-stdio.ts --tool=ledgerly-heat-pump-estimate
{
"mcpServers": {
"ledgerly-heat-pump-estimate": { "type": "http", "url": "https://ledgerlyheatpumpestimate.usefulweb.app/mcp" }
}
}