{ "openapi": "3.1.1", "info": { "title": "Loan Amortization Calculator API", "version": "1.0.0", "summary": "Annuity, linear or interest-only loans: schedule, extra payments, fixed-rate balance, APR.", "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://loanamortizationcalculator.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Annuity, linear or interest-only loans: schedule, extra payments, fixed-rate balance, APR.", "description": "Calculates the payment and the complete amortization schedule of an annuity, linear (constant principal) or interest-only loan, including one-off and recurring extra payments, the remaining balance at the end of a fixed-rate period, the effective annual rate and the APR with up-front fees. Download the schedule as CSV.\n\nMethodology:\n- Rate per period i = nominal annual rate ÷ payments per year (the usual convention for German and most European loans).\n- Annuity payment A = L·i ÷ (1 − (1 + i)^−n), rounded to the cent; with an initial repayment rate t instead: A = L × (rate + t) ÷ payments per year, and the term follows from A.\n- Each period: interest = balance × i (rounded to the cent); principal = A − interest (annuity), L ÷ n (linear) or 0 until the last payment (interest-only). The last scheduled payment clears any remaining cents.\n- Extra payments reduce the balance on top of the regular payment. Annuity loans keep the payment and finish earlier; linear and interest-only loans keep their principal plan and pay less interest.\n- Remaining balance at the end of the fixed-rate period = balance after the last payment inside that period.\n- Effective annual rate (no fees) = (1 + i)^m − 1. APR: the rate X solving Σ payment_l × (1 + X)^(−t_l) = loan − up-front fees, with t_l measured in years of 12 standard months, as in the equation of the PAngV annex (EU Consumer Credit Directive). This is an approximation: real offers count exact days, may add account fees or insurance, and lenders round to two decimals.", "tags": [ "calculators" ], "x-mcp-tool": "loan_amortization_calculator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanAmortizationCalculatorInput" }, "examples": { "example1": { "summary": "Mortgage 300,000 at 3.8%, 2% initial repayment, 10-year fixed rate", "value": { "principal": 300000, "currency": "EUR", "ratePercent": 3.8, "loanType": "annuity", "initialRepaymentPercent": 2, "frequency": "monthly", "startDate": "2026-11-01", "fixedRateYears": 10, "upfrontFees": 0, "recurringExtra": 5000, "recurringEvery": 12, "recurringFrom": 12 } }, "example2": { "summary": "Car loan 20,000, 5 years at 6.9% with 400 fees", "value": { "principal": 20000, "currency": "USD", "ratePercent": 6.9, "loanType": "annuity", "termYears": 5, "frequency": "monthly", "upfrontFees": 400 } }, "example3": { "summary": "Linear loan 120,000 over 10 years, quarterly", "value": { "principal": 120000, "ratePercent": 4, "loanType": "linear", "termYears": 10, "frequency": "quarterly", "startDate": "2027-01-01", "extraPayments": [ { "period": 8, "amount": 10000 } ] } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoanAmortizationCalculatorResult" } } } }, "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" } } } } } }, "LoanAmortizationCalculatorInput": { "type": "object", "additionalProperties": false, "properties": { "principal": { "title": "Loan amount", "type": "number", "minimum": 1, "maximum": 10000000000, "default": 200000 }, "currency": { "title": "Currency", "description": "Shown in results only; no conversion.", "type": "string", "maxLength": 8, "default": "EUR" }, "ratePercent": { "title": "Nominal interest rate", "description": "Borrowing rate (Sollzins). The rate per period is this ÷ payments per year.", "type": "number", "minimum": 0, "maximum": 100, "default": 3.5, "x-unit": "% per year" }, "loanType": { "title": "Repayment type", "type": "string", "enum": [ "annuity", "linear", "interest-only" ], "default": "annuity" }, "termYears": { "title": "Term", "type": "number", "minimum": 0.25, "maximum": 100, "default": 25, "x-unit": "years" }, "initialRepaymentPercent": { "title": "Initial repayment rate (annuity only)", "description": "Optional, common in Germany (anfängliche Tilgung): payment per year = loan × (interest rate + this rate). The term then follows from the payment and the Term field is ignored.", "type": "number", "minimum": 0.01, "maximum": 100, "x-unit": "% per year" }, "frequency": { "title": "Payments", "type": "string", "enum": [ "monthly", "quarterly", "annually" ], "default": "monthly" }, "startDate": { "title": "Payout date", "description": "Optional. The first payment is due one period later; dates are added to the schedule.", "type": "string", "format": "date" }, "fixedRateYears": { "title": "Fixed-rate period", "description": "Optional (Zinsbindung): shows the balance still owed when the fixed rate ends.", "type": "number", "minimum": 0.25, "maximum": 100, "x-unit": "years" }, "upfrontFees": { "title": "Up-front fees", "description": "Processing or broker fees paid at payout. They raise the APR, not the nominal rate.", "type": "number", "minimum": 0, "default": 0 }, "extraPayments": { "title": "One-off extra payments", "description": "Paid together with the regular payment number you enter (e.g. 12 = end of the first year for monthly payments).", "type": "array", "maxItems": 30, "items": { "type": "object", "additionalProperties": false, "properties": { "period": { "title": "Payment number", "type": "integer", "minimum": 1, "maximum": 1200 }, "amount": { "title": "Extra amount", "type": "number", "minimum": 0 } }, "required": [ "period", "amount" ] } }, "recurringExtra": { "title": "Recurring extra payment", "description": "Optional, e.g. an annual special repayment (Sondertilgung).", "type": "number", "minimum": 0, "default": 0 }, "recurringEvery": { "title": "Recurring extra: every", "type": "integer", "minimum": 1, "maximum": 120, "default": 12, "x-unit": "payments" }, "recurringFrom": { "title": "Recurring extra: first at payment number", "type": "integer", "minimum": 1, "maximum": 1200, "default": 12 }, "recurringUntil": { "title": "Recurring extra: last at payment number", "description": "Optional; empty = until the loan is repaid.", "type": "integer", "minimum": 1, "maximum": 1200 } }, "required": [ "principal" ] }, "LoanAmortizationCalculatorResult": { "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", "loanType", "periodsPerYear", "principal", "nominalRatePercent", "periodicRatePercent", "regularPayment", "numberOfPayments", "termYears", "totalInterest", "totalExtra", "totalPaid", "payoffDate", "effectiveRatePercent", "aprPercent", "fixedRate", "extrasSavings", "schedule" ], "properties": { "currency": { "type": "string" }, "loanType": { "type": "string", "enum": [ "annuity", "linear", "interest-only" ] }, "periodsPerYear": { "type": "integer" }, "principal": { "type": "number" }, "nominalRatePercent": { "type": "number" }, "periodicRatePercent": { "type": "number" }, "regularPayment": { "type": "number", "description": "Annuity: the constant payment; linear and interest-only: the first payment." }, "numberOfPayments": { "type": "integer" }, "termYears": { "type": "number" }, "totalInterest": { "type": "number" }, "totalExtra": { "type": "number" }, "totalPaid": { "type": "number" }, "payoffDate": { "type": [ "string", "null" ] }, "effectiveRatePercent": { "type": "number", "description": "(1 + nominal/m)^m − 1, without fees." }, "aprPercent": { "type": [ "number", "null" ], "description": "Annual rate equating the net payout (loan − fees) with all payments (PAngV/CCD equation, standard months)." }, "fixedRate": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "years", "payments", "balanceAtEnd", "interestPaid", "principalRepaid", "endDate" ], "properties": { "years": { "type": "number" }, "payments": { "type": "integer" }, "balanceAtEnd": { "type": "number" }, "interestPaid": { "type": "number" }, "principalRepaid": { "type": "number" }, "endDate": { "type": [ "string", "null" ] } } }, "extrasSavings": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "interestSaved", "paymentsSaved" ], "properties": { "interestSaved": { "type": "number" }, "paymentsSaved": { "type": "integer" } } }, "schedule": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "period", "date", "payment", "interest", "principal", "extra", "balance" ], "properties": { "period": { "type": "integer" }, "date": { "type": [ "string", "null" ] }, "payment": { "type": "number" }, "interest": { "type": "number" }, "principal": { "type": "number" }, "extra": { "type": "number" }, "balance": { "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" } } } } } } } }