Cost of Ownership

curl -X GET \
  "https://api.carapi.dev/v1/cost-of-ownership?make=skoda&model=octavia&year=2019&country=CZ&kw=110&token=YOUR_API_KEY"

const params = new URLSearchParams({
  token: 'YOUR_API_KEY',
  make: 'skoda',
  model: 'octavia',
  year: '2019',
  country: 'CZ',
  fuel: 'diesel',
  kw: '110',
  kmPerYear: '20000',
  years: '3',
  currency: 'CZK'
});

const response = await fetch(
  `https://api.carapi.dev/v1/cost-of-ownership?${params.toString()}`
);
const data = await response.json();

const { currency } = data.assumptions;
console.log(`${data.totals.perMonth} ${currency}/month over ${data.assumptions.years} years`);

// Show the components, not just the total — each carries its own confidence.
for (const [name, part] of Object.entries(data.breakdown)) {
  console.log(`  ${name}: ${part.total} ${currency} (${part.confidence})`);
}

import requests

response = requests.get(
    "https://api.carapi.dev/v1/cost-of-ownership",
    params={
        "token": "YOUR_API_KEY",
        "make": "toyota",
        "model": "camry",
        "year": 2021,
        "country": "US",
        "kmPerYear": 19300,
        "years": 5,
    },
)
data = response.json()

print(f"{data['totals']['total']} {data['assumptions']['currency']} over 5 years")
for name, part in data["breakdown"].items():
    print(f"  {name:15} {part['total']:>7} ({part['confidence']})")

{
  "vehicle": {
    "make": "Skoda",
    "model": "Octavia",
    "year": 2019,
    "fuel": "diesel",
    "kw": 110,
    "requested": { "make": "skoda", "model": "octavia" }
  },
  "country": "CZ",
  "assumptions": {
    "kmPerYear": 15000,
    "years": 5,
    "currentValue": 12800,
    "currency": "EUR",
    "fuelPriceFlat": true
  },
  "totals": { "total": 18092, "perYear": 3618, "perMonth": 302, "perKm": 0.241 },
  "breakdown": {
    "depreciation": {
      "total": 6400,
      "confidence": "measured",
      "method": "market-cross-section",
      "valueBasis": "median",
      "notes": ["Fitted across 1,180 CZ listings of this model aged 4-13 years."]
    },
    "fuel": {
      "total": 5112,
      "confidence": "measured",
      "consumptionL100km": 4.8,
      "consumptionKwh100km": null,
      "provider": "eea",
      "fuelKey": "diesel",
      "modelYearUsed": 2019,
      "kwBand": [100, 120],
      "sampleSize": 42,
      "pricePerUnit": 1.42,
      "priceUnit": "litre",
      "priceCurrency": "EUR",
      "notes": ["Type-approval consumption; real-world use typically runs 10-20% higher."]
    },
    "insurance": {
      "total": 2100,
      "confidence": "estimated",
      "annualPremium": 420,
      "kwBand": [92, 120],
      "notes": ["A comprehensive policy typically runs 2-3x this."]
    },
    "maintenance": {
      "total": 3900,
      "confidence": "estimated",
      "notes": ["Servicing, wear parts and tyres, rising with age. Excludes accident repairs."]
    },
    "taxesAndFees": {
      "total": 580,
      "confidence": "estimated",
      "items": [
        { "label": "Motorway vignette", "total": 460, "recurring": true },
        { "label": "Technical + emissions inspection", "total": 120, "recurring": true }
      ],
      "notes": ["Passenger cars have paid no annual road tax in CZ since 2022."]
    }
  },
  "perYear": [
    { "year": 1, "calendarYear": 2026, "vehicleAge": 7, "depreciation": 1700, "fuel": 1022, "insurance": 420, "maintenance": 620, "taxesAndFees": 116, "total": 3878 },
    { "year": 2, "calendarYear": 2027, "vehicleAge": 8, "depreciation": 1450, "fuel": 1022, "insurance": 420, "maintenance": 700, "taxesAndFees": 116, "total": 3708 },
    { "year": 3, "calendarYear": 2028, "vehicleAge": 9, "depreciation": 1250, "fuel": 1023, "insurance": 420, "maintenance": 780, "taxesAndFees": 116, "total": 3589 },
    { "year": 4, "calendarYear": 2029, "vehicleAge": 10, "depreciation": 1050, "fuel": 1022, "insurance": 420, "maintenance": 880, "taxesAndFees": 116, "total": 3488 },
    { "year": 5, "calendarYear": 2030, "vehicleAge": 11, "depreciation": 950, "fuel": 1023, "insurance": 420, "maintenance": 920, "taxesAndFees": 116, "total": 3429 }
  ]
}

{
  "vehicle": { "make": "Toyota", "model": "Camry", "year": 2021, "fuel": "petrol", "kw": 151, "requested": { "make": "toyota", "model": "camry" } },
  "country": "US",
  "assumptions": { "kmPerYear": 19300, "years": 5, "currentValue": 21500, "currency": "USD", "fuelPriceFlat": true },
  "totals": { "total": 27490, "perYear": 5498, "perMonth": 458, "perKm": 0.285 },
  "breakdown": {
    "insurance": {
      "total": 3900,
      "confidence": "estimated",
      "annualPremium": 780,
      "kwBand": null,
      "notes": ["US premiums are not power-rated, so kw does not affect this component."]
    },
    "taxesAndFees": {
      "total": 2090,
      "confidence": "estimated",
      "items": [
        { "label": "Sales tax on vehicle value (~6%)", "total": 1290, "recurring": false },
        { "label": "Registration and title", "total": 800, "recurring": true }
      ],
      "notes": [
        "National expected values across 50 state regimes — not a bill for any one state.",
        "Sales tax falls entirely in year 1, following the Edmunds True Cost to Own convention."
      ]
    }
  }
}

{
  "error": "Insufficient data to estimate cost of ownership for this vehicle",
  "missing": "consumption",
  "hint": "No EEA consumption record for this model, year and kW band. Omit kw, or try an adjacent model year."
}