{ "openapi": "3.1.1", "info": { "title": "Ledgerly Home Battery Simulator API", "version": "1.0.0", "summary": "Is a home battery worth it? Hour-by-hour year with your load, several battery sizes compared.", "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://ledgerlybatterysim.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Is a home battery worth it? Hour-by-hour year with your load, several battery sizes compared.", "description": "Simulates a year hour by hour: solar power from the offline yield model (or your monthly figures), your consumption from a smart-meter export, hourly values or a simple household profile, and a battery with its capacity, power and losses. Compares several sizes by self-consumption, self-sufficiency, grid import, export, cycles and the money each one saves. Part of Ledgerly’s Solar \u0026 Heat.\n\nMethodology:\n- 8,760 hourly steps (365 days). Solar power per month comes from the offline yield model or your 12 monthly figures, shaped by the sun’s path for your tilt and orientation; each day is sunny, mixed or dull, drawn from a seeded sequence in which a class often lasts several days, and every month keeps its total.\n- Consumption: smart-meter readings (any interval, averaged per month and clock hour), 24 / 288 / 8,760 hourly values, or Ledgerly’s simple household profile; the yearly total rescales it.\n- Each hour solar power first covers the load, the surplus charges the battery (limited by capacity and power), and the battery covers later demand; round-trip losses are split evenly between charging and discharging. The battery starts empty on 1 January.\n- Self-consumption = solar power used in the house (directly or via the battery) ÷ solar power; self-sufficiency = consumption not bought from the grid ÷ consumption. The worth of a battery = grid power saved × price − export lost × feed-in payment, against the same system without a battery.\n\nHourly steps smooth out short load peaks, so real self-consumption is usually a few points lower. Battery installation is electrical work for a qualified installer following local codes (e.g. VDE, NEC).", "tags": [ "apps" ], "x-mcp-tool": "ledgerly_battery_sim", "x-owner-app": "ledgerly", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerlyBatterySimInput" }, "examples": { "example1": { "summary": "8 kWp in Berlin, 4,000 kWh, 8 kWh battery", "value": { "latitude": 52.52, "longitude": 13.405, "peakPowerKw": 8, "annualLoadKwh": 4000, "batteryKwh": 8 } }, "example2": { "summary": "Small system, 5 kWp east-west, 3,000 kWh, 5 kWh", "value": { "latitude": 51.34, "longitude": 12.37, "peakPowerKw": 5, "tilt": 15, "azimuth": -90, "layout": "east-west", "annualLoadKwh": 3000, "batteryKwh": 5, "compareCapacities": "0, 3, 5, 8" } }, "example3": { "summary": "Monthly PVGIS yield and a 24-hour profile", "value": { "latitude": 48.14, "longitude": 11.58, "peakPowerKw": 6, "pvMonthlyKwh": "160, 270, 450, 600, 660, 660, 650, 600, 510, 350, 190, 140", "loadProfile": "0.3 0.25 0.25 0.25 0.25 0.3 0.5 0.6 0.4 0.3 0.3 0.4 0.5 0.4 0.3 0.3 0.4 0.6 0.8 0.9 0.8 0.6 0.5 0.4", "batteryKwh": 6, "annualLoadKwh": 3500 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerlyBatterySimResult" } } } }, "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" } } } } } }, "LedgerlyBatterySimInput": { "type": "object", "additionalProperties": false, "properties": { "currency": { "title": "Currency", "type": "string", "maxLength": 3, "default": "EUR" }, "latitude": { "title": "Latitude (°, south negative)", "type": "number", "minimum": -66, "maximum": 66, "default": 52.52 }, "longitude": { "title": "Longitude (°, west negative)", "type": "number", "minimum": -180, "maximum": 180, "default": 13.405 }, "peakPowerKw": { "title": "Peak power of the PV system (kWp)", "type": "number", "minimum": 0.1, "maximum": 1000, "default": 8 }, "tilt": { "title": "Tilt (° from horizontal)", "type": "number", "minimum": 0, "maximum": 90, "default": 35 }, "azimuth": { "title": "Orientation (° from south: east −90, west 90)", "type": "number", "minimum": -180, "maximum": 180, "default": 0 }, "layout": { "title": "Panel layout", "type": "string", "enum": [ "single", "east-west" ], "default": "single" }, "utcOffset": { "title": "Time zone (hours from UTC, standard time)", "type": "number", "minimum": -12, "maximum": 14, "default": 1 }, "pvMonthlyKwh": { "title": "PV yield per month (kWh, 12 values; empty = offline estimate)", "description": "Paste the monthly figures from the yield calculation or PVGIS; the daily curve still comes from the sun’s path.", "type": "string", "maxLength": 400, "default": "" }, "annualLoadKwh": { "title": "Electricity use per year (kWh; empty = from the profile)", "description": "With the built-in profile an empty value means 4,000 kWh. With your own profile it rescales the profile to this total.", "type": "number", "minimum": 0, "maximum": 10000000 }, "loadProfile": { "title": "Your load profile: 24, 288 or 8,760 hourly kWh values, or smart-meter readings", "description": "Empty = Ledgerly’s simple household profile. Meter readings: one line per reading with date, time and kWh.", "type": "string", "maxLength": 400000, "default": "" }, "batteryKwh": { "title": "Usable battery capacity (kWh)", "type": "number", "minimum": 0, "maximum": 1000, "default": 8 }, "compareCapacities": { "title": "Also compare these capacities (kWh)", "type": "string", "maxLength": 200, "default": "0, 5, 10, 15" }, "batteryPowerKw": { "title": "Battery charge and discharge power (kW)", "type": "number", "minimum": 0.1, "maximum": 1000, "default": 4 }, "roundTripEfficiencyPercent": { "title": "Round-trip efficiency (%)", "type": "number", "minimum": 50, "maximum": 100, "default": 90 }, "exportLimitKw": { "title": "Feed-in limit (kW, 0 = none)", "type": "number", "minimum": 0, "maximum": 1000, "default": 0 }, "electricityPrice": { "title": "Electricity price per kWh", "type": "number", "minimum": 0, "maximum": 10, "default": 0.35 }, "feedInTariff": { "title": "Feed-in payment per kWh", "type": "number", "minimum": 0, "maximum": 10, "default": 0.078 }, "seed": { "title": "Weather sequence (seed)", "description": "Sunny, mixed and dull days are drawn from this seed; the same seed always gives the same year.", "type": "integer", "minimum": 1, "maximum": 999999, "default": 1 } }, "required": [] }, "LedgerlyBatterySimResult": { "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": [ "currency", "pvSource", "loadSource", "meterDays", "pvKwh", "loadKwh", "selected", "capacities", "billWithoutPv", "billWithPv", "juneDay", "decemberDay" ], "properties": { "currency": { "type": "string" }, "pvSource": { "type": "string", "enum": [ "monthly-input", "offline-estimate" ] }, "loadSource": { "type": "string", "enum": [ "built-in", "day", "months", "year", "meter" ] }, "meterDays": { "type": [ "integer", "null" ] }, "pvKwh": { "type": "number" }, "loadKwh": { "type": "number" }, "selected": { "type": "object", "additionalProperties": false, "required": [ "capacityKwh", "directUseKwh", "fromBatteryKwh", "gridImportKwh", "exportKwh", "selfConsumptionPercent", "autarkyPercent", "fullCycles", "savingsPerYear", "months" ], "properties": { "capacityKwh": { "type": "number" }, "directUseKwh": { "type": "number" }, "fromBatteryKwh": { "type": "number" }, "gridImportKwh": { "type": "number" }, "exportKwh": { "type": "number" }, "selfConsumptionPercent": { "type": "number" }, "autarkyPercent": { "type": "number" }, "fullCycles": { "type": "number" }, "savingsPerYear": { "type": "number" }, "months": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "month", "pvKwh", "loadKwh", "selfUsedKwh", "gridImportKwh", "exportKwh" ], "properties": { "month": { "type": "integer" }, "pvKwh": { "type": "number" }, "loadKwh": { "type": "number" }, "selfUsedKwh": { "type": "number" }, "gridImportKwh": { "type": "number" }, "exportKwh": { "type": "number" } } } } } }, "capacities": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "capacityKwh", "selfConsumptionPercent", "autarkyPercent", "gridImportKwh", "exportKwh", "fullCycles", "savingsPerYear" ], "properties": { "capacityKwh": { "type": "number" }, "selfConsumptionPercent": { "type": "number" }, "autarkyPercent": { "type": "number" }, "gridImportKwh": { "type": "number" }, "exportKwh": { "type": "number" }, "fullCycles": { "type": "number" }, "savingsPerYear": { "type": "number" } } } }, "billWithoutPv": { "type": "number" }, "billWithPv": { "type": "number" }, "juneDay": { "type": "object", "additionalProperties": false, "required": [ "pv", "load", "soc" ], "properties": { "pv": { "type": "array", "items": { "type": "number" } }, "load": { "type": "array", "items": { "type": "number" } }, "soc": { "type": "array", "items": { "type": "number" } } } }, "decemberDay": { "type": "object", "additionalProperties": false, "required": [ "pv", "load", "soc" ], "properties": { "pv": { "type": "array", "items": { "type": "number" } }, "load": { "type": "array", "items": { "type": "number" } }, "soc": { "type": "array", "items": { "type": "number" } } } } } }, "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" } } } } } } } }