{ "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.app" } ], "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, fuel or food per year = consumption ÷ (1 or 100) × usage per year × price per unit.\n- True total = depreciation + loan interest + years × (recurring + maintenance or vet care + insurance + energy, fuel or food 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.35, "consumptionPer": "per-1", "energyUnitPrice": 6, "usagePerYear": 365, "recurring": [ { "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", "description": "Pet: purchase or adoption fee.", "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 or vet care per year", "description": "Car or appliance: servicing and repairs. Pet: vet visits, vaccinations, medication and other health care.", "type": "number", "minimum": 0, "default": 0 }, "insurancePerYear": { "title": "Insurance per year", "description": "Pet: health or liability insurance.", "type": "number", "minimum": 0, "default": 0 }, "energyConsumption": { "title": "Energy, fuel or food consumption", "description": "Car: e.g. 6 (litres per 100 km). Appliance: e.g. 1.2 (kWh per wash cycle). Pet: e.g. 0.35 (kg of food per day).", "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 unit (litre, kWh or kg of food)", "description": "E.g. price per litre of fuel, per kWh or per kg of pet food.", "type": "number", "minimum": 0, "default": 0 }, "usagePerYear": { "title": "Usage per year", "description": "E.g. km per year, wash cycles per year, or 365 feeding days for a pet.", "type": "number", "minimum": 0, "default": 0 }, "recurring": { "title": "Other recurring costs", "description": "Taxes, parking, subscriptions, pet supplies, grooming, 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" } } } } } } } }