{ "openapi": "3.1.1", "info": { "title": "True Cost Calculator API", "version": "1.0.0", "summary": "What a car, pet, appliance, home or gadget really costs per year, month and day.", "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://truecostcalculator.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "What a car, pet, appliance, home or gadget really costs per year, month and day.", "description": "Add the purchase price, financing, expected resale value, recurring costs, maintenance, insurance and energy use. The calculator returns the true total cost of ownership, the cost per year, month and day, the share of each cost bucket, and how many times the sticker price you really pay.\n\nMethodology:\n- Depreciation = purchase price − expected resale value (the money you will not get back).\n- Loan interest is computed from an exact monthly annuity schedule: payment = L·i ÷ (1 − (1 + i)^−n) with i = APR ÷ 12 and n = term in months; only interest falling within the ownership period (years × 12 months) is counted.\n- Recurring costs are annualised: weekly × 365.25/7, monthly × 12, quarterly × 4, yearly × 1; then multiplied by years owned.\n- Energy per year = consumption ÷ (1 or 100) × usage per year × price per energy unit.\n- True total = depreciation + loan interest + years × (recurring + maintenance + insurance + energy per year).\n- Per year = total ÷ years; per month = total ÷ (12 × years); per day = total ÷ (365.25 × years). Sticker multiplier = total ÷ purchase price.", "tags": [ "everyday" ], "x-mcp-tool": "true_cost_calculator", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrueCostCalculatorInput" }, "examples": { "example1": { "summary": "Compact car, financed, 6 years", "value": { "itemType": "car", "itemName": "Compact car", "currency": "EUR", "purchasePrice": 24000, "yearsOwned": 6, "resaleValue": 9000, "loanAmount": 15000, "aprPercent": 5.9, "loanTermMonths": 48, "maintenancePerYear": 600, "insurancePerYear": 750, "energyConsumption": 6, "consumptionPer": "per-100", "energyUnitPrice": 1.75, "usagePerYear": 12000, "recurring": [ { "name": "Vehicle tax", "amount": 120, "frequency": "yearly" }, { "name": "Parking permit", "amount": 30, "frequency": "monthly" } ] } }, "example2": { "summary": "Medium-sized dog, 12 years", "value": { "itemType": "pet", "itemName": "Dog", "currency": "EUR", "purchasePrice": 900, "yearsOwned": 12, "resaleValue": 0, "loanAmount": 0, "aprPercent": 0, "loanTermMonths": 0, "insurancePerYear": 240, "maintenancePerYear": 250, "energyConsumption": 0, "consumptionPer": "per-1", "energyUnitPrice": 0, "usagePerYear": 0, "recurring": [ { "name": "Food", "amount": 15, "frequency": "weekly" }, { "name": "Dog tax", "amount": 100, "frequency": "yearly" }, { "name": "Toys & treats", "amount": 10, "frequency": "monthly" } ] } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrueCostCalculatorResult" } } } }, "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" } } } } } }, "TrueCostCalculatorInput": { "type": "object", "additionalProperties": false, "properties": { "itemType": { "title": "What is it?", "type": "string", "enum": [ "car", "pet", "appliance", "home", "gadget", "other" ], "default": "car" }, "itemName": { "title": "Name", "type": "string", "maxLength": 80, "default": "My purchase" }, "currency": { "title": "Currency", "description": "Shown in results only; no conversion is performed.", "type": "string", "maxLength": 8, "default": "EUR" }, "purchasePrice": { "title": "Purchase (sticker) price", "type": "number", "minimum": 0, "default": 0 }, "yearsOwned": { "title": "Years you will own it", "type": "number", "minimum": 0.1, "maximum": 60, "default": 5, "x-unit": "years" }, "resaleValue": { "title": "Expected resale value at the end", "type": "number", "minimum": 0, "default": 0 }, "loanAmount": { "title": "Loan amount", "description": "Leave 0 if you pay cash.", "type": "number", "minimum": 0, "default": 0 }, "aprPercent": { "title": "Loan APR", "type": "number", "minimum": 0, "maximum": 100, "default": 0, "x-unit": "%/year" }, "loanTermMonths": { "title": "Loan term", "type": "integer", "minimum": 0, "maximum": 600, "default": 0, "x-unit": "months" }, "maintenancePerYear": { "title": "Maintenance / repairs per year", "type": "number", "minimum": 0, "default": 0 }, "insurancePerYear": { "title": "Insurance per year", "type": "number", "minimum": 0, "default": 0 }, "energyConsumption": { "title": "Energy / fuel consumption", "description": "E.g. 6 (litres per 100 km) or 150 (kWh per year of use = 1 usage unit).", "type": "number", "minimum": 0, "default": 0 }, "consumptionPer": { "title": "Consumption is per", "type": "string", "enum": [ "per-100", "per-1" ], "default": "per-100" }, "energyUnitPrice": { "title": "Price per energy unit", "description": "E.g. price per litre or per kWh.", "type": "number", "minimum": 0, "default": 0 }, "usagePerYear": { "title": "Usage per year", "description": "E.g. km per year, wash cycles per year.", "type": "number", "minimum": 0, "default": 0 }, "recurring": { "title": "Other recurring costs", "description": "Taxes, parking, food, subscriptions, fees…", "type": "array", "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "title": "Cost", "type": "string" }, "amount": { "title": "Amount", "type": "number", "minimum": 0 }, "frequency": { "title": "Every", "type": "string", "enum": [ "weekly", "monthly", "quarterly", "yearly" ], "default": "monthly" } }, "required": [ "name", "amount" ] } } }, "required": [ "purchasePrice" ] }, "TrueCostCalculatorResult": { "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": [ "itemName", "itemType", "currency", "yearsOwned", "trueTotal", "perYear", "perMonth", "perDay", "stickerMultiplier", "loan", "buckets", "recurringItems" ], "properties": { "itemName": { "type": "string" }, "itemType": { "type": "string", "enum": [ "car", "pet", "appliance", "home", "gadget", "other" ] }, "currency": { "type": "string" }, "yearsOwned": { "type": "number" }, "trueTotal": { "type": "number", "description": "Sum of all cost buckets over the ownership period." }, "perYear": { "type": "number" }, "perMonth": { "type": "number" }, "perDay": { "type": "number" }, "stickerMultiplier": { "type": [ "number", "null" ], "description": "trueTotal ÷ purchase price; null when the purchase price is 0." }, "loan": { "type": "object", "additionalProperties": false, "required": [ "monthlyPayment", "totalInterestFullTerm", "interestDuringOwnership", "balanceAtEnd" ], "properties": { "monthlyPayment": { "type": "number" }, "totalInterestFullTerm": { "type": "number" }, "interestDuringOwnership": { "type": "number" }, "balanceAtEnd": { "type": "number", "description": "Outstanding principal when you stop owning the item (to be repaid from the sale)." } } }, "buckets": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "bucket", "label", "total", "perYear", "sharePercent" ], "properties": { "bucket": { "type": "string", "enum": [ "depreciation", "financing", "recurring", "maintenance", "insurance", "energy" ] }, "label": { "type": "string" }, "total": { "type": "number" }, "perYear": { "type": "number" }, "sharePercent": { "type": "number" } } } }, "recurringItems": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "perYear", "total" ], "properties": { "name": { "type": "string" }, "perYear": { "type": "number" }, "total": { "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" } } } } } } } }