---
title: "Estimate the total cost of owning a vehicle"
method: GET
path: "/cost-of-ownership"
tags: ["Market"]
---

# Estimate the total cost of owning a vehicle

`GET /cost-of-ownership`

What a car costs to run over a holding period: depreciation, fuel, insurance, maintenance, and taxes and fees, totalled and broken down per component and per year.

**Read the breakdown, not just the total.** Every component carries its own `confidence`. `measured` means a published dataset covers this exact vehicle — EEA or EPA consumption for the model/year/kW band, an official fuel-price series, a depreciation curve fitted across live comparable listings. `estimated` means authored constants or data stretched to fit the cohort. Collapsing the response into a single number throws away the only signal that separates the two, and the components differ in quality within a single answer.

**Money values are integers in `assumptions.currency`**, with the single exception of `totals.perKm`, which carries 3 decimals. `assumptions` states what the figures were computed against — the car's current market value, the annual distance, the horizon — so a caller can reproduce or re-scale them.

**Country differences are real, not cosmetic.** CZ/SK/PL price MTPL (third-party liability) insurance on an engine-power band and carry no annual passenger-car road tax; US figures follow the Edmunds True Cost to Own convention and include roughly 6% sales tax on the car's value, with liability-only insurance. US tax and fee figures are national expected values across 50 state regimes — useful for comparing cars, not a bill for any one state.

Nothing is prorated for a partial year: `years` buys whole years, and year 1 carries the one-off charges (US sales tax, registration). A 404 means a whole component could not be estimated, and names which one in `missing` — an expected outcome for a rare car or a drivetrain with no local price series, not an error to retry unchanged.

## Query parameters

- `make` string, required
- `model` string, required
- `year` integer, required
- `country` 'CZ' | 'SK' | 'PL' | 'US', required
- `fuel` 'petrol' | 'diesel' | 'electric' | 'hybrid' | 'phev' | 'lpg'
- `kw` integer
- `kmPerYear` integer
- `years` integer
- `currency` 'EUR' | 'CZK' | 'PLN' | 'USD'

## Response `200`

Cost of ownership over the requested horizon, with a per-component and per-year breakdown.

- CostOfOwnershipResponse — Total cost of ownership over the requested horizon. All money values are integers in `assumptions.currency`, except `totals.perKm`. Read `breakdown` alongside `totals`: each component carries its own confidence, and they are not equal within a single answer.
  - `vehicle` object, required — The vehicle the figures describe, as the upstream resolved it, plus an echo of what you asked for
    - `make` string, required — Resolved manufacturer, in display form
    - `model` string, required — Resolved model, in display form
    - `year` integer, required — Model year
    - `fuel` string, nullable — Drivetrain used for the fuel component — inferred from the market when you omit `fuel`
    - `kw` integer, nullable — Engine power used to pick the depreciation cohort and the insurance band
    - `requested` object, required — The make and model as you sent them, after case and alias normalization (volkswagen → vw) but before the upstream's own resolution. Match against this, not against `vehicle.make`.
      - `make` string, required — Make as requested
      - `model` string, required — Model as requested
  - `country` string, required — Market the figures describe
  - `assumptions` object, required — What the figures were computed against. Enough to reproduce or re-scale them — halving `kmPerYear` roughly halves the fuel component but leaves insurance untouched.
    - `kmPerYear` integer, required — Annual distance used. Defaults to 15000 (CZ/SK/PL) or 19300 (US).
    - `years` integer, required — Holding period in whole years
    - `currentValue` integer, required — The car's market value today — the base every depreciation and value-based tax figure is computed from
    - `currency` string, required — Currency of every money value in the response
    - `fuelPriceFlat` boolean, required — True when the pump price is held flat over the horizon rather than forecast. It always is today, so a rising-price scenario is the caller's to model.
  - `totals` object, required — The headline figures. `total` is the sum of the five components and of the `perYear` rows.
    - `total` integer, required — Total cost over the whole horizon
    - `perYear` integer, required — Total divided by `assumptions.years`. An average — the real per-year figures in `perYear` are front-loaded by depreciation and one-off charges.
    - `perMonth` integer, required — Total divided by the number of months in the horizon
    - `perKm` number, required — Cost per kilometre — the one value with decimals (3 places)
  - `breakdown` object, required — The five components that make up `totals.total`, each with its own confidence
    - `depreciation` CostDepreciation, required — Value lost over the horizon. Normally the largest single component, and the one most sensitive to `year` and `kw`.
      - `total` integer, required — Value lost over the whole horizon
      - `confidence` 'measured' | 'estimated', required — `measured`: a published dataset covers this exact vehicle. `estimated`: authored constants, or data stretched to fit the cohort. Render it — the two are not interchangeable, and they differ between components of the same answer.
      - `method` string, nullable — `market-cross-section` fits a curve across live comparable listings; `authored-curve` falls back to a modelled curve when the cohort is too thin
      - `valueBasis` string, nullable — Which point of the listing distribution the values were taken from — `median`, or `p25` where asking prices skew high
      - `notes` string[] — Caveats worth surfacing alongside the component
    - `fuel` CostFuel, required — Energy cost over the horizon: consumption for the resolved drivetrain, at a published price held flat. Exactly one of `consumptionL100km` and `consumptionKwh100km` is non-null.
      - `total` integer, required — Fuel or charging cost over the whole horizon
      - `confidence` 'measured' | 'estimated', required — `measured`: a published dataset covers this exact vehicle. `estimated`: authored constants, or data stretched to fit the cohort. Render it — the two are not interchangeable, and they differ between components of the same answer.
      - `consumptionL100km` number, nullable — Litres per 100 km, for a combustion drivetrain. Null for electric.
      - `consumptionKwh100km` number, nullable — kWh per 100 km, for an electric drivetrain. Null otherwise.
      - `provider` string, nullable — Consumption dataset behind the figure — `eea` (Europe) or `epa` (US)
      - `fuelKey` string, nullable — Fuel the figures were computed for, after inference
      - `modelYearUsed` integer, nullable — Model year matched in the consumption dataset — may differ from the requested year when the exact one is absent
      - `kwBand` integer[], nullable — Engine-power band, in kW, the figure was drawn from
      - `sampleSize` integer, nullable — Number of dataset records behind the consumption figure
      - `pricePerUnit` number, nullable — Price per `priceUnit`, in `priceCurrency`
      - `priceUnit` string, nullable — `litre` or `kWh`. Litres even for US, so markets stay comparable.
      - `priceCurrency` string, nullable — Currency the price was published in
      - `notes` string[] — Caveats worth surfacing alongside the component
    - `insurance` CostInsurance, required — Mandatory cover only, and the scope differs by market: MTPL banded on engine power in CZ/SK/PL, liability-only and not power-rated in the US. A comprehensive policy is not modelled.
      - `total` integer, required — Premiums over the whole horizon
      - `confidence` 'measured' | 'estimated', required — `measured`: a published dataset covers this exact vehicle. `estimated`: authored constants, or data stretched to fit the cohort. Render it — the two are not interchangeable, and they differ between components of the same answer.
      - `annualPremium` integer, nullable — Modelled annual premium
      - `kwBand` integer[], nullable — Engine-power band, in kW, the figure was drawn from
      - `notes` string[] — Caveats worth surfacing alongside the component
    - `maintenance` CostMaintenance, required — Servicing, wear parts and tyres, rising with age and distance. Always `estimated` — there is no published per-model service-cost dataset behind it.
      - `total` integer, required — Maintenance over the whole horizon
      - `confidence` 'measured' | 'estimated', required — `measured`: a published dataset covers this exact vehicle. `estimated`: authored constants, or data stretched to fit the cohort. Render it — the two are not interchangeable, and they differ between components of the same answer.
      - `notes` string[] — Caveats worth surfacing alongside the component
    - `taxesAndFees` CostTaxesAndFees, required — Statutory charges, itemised. Composition is market-specific: vignettes and roadworthiness tests in CZ/SK/PL, sales tax plus registration and title in the US.
      - `total` integer, required — Taxes and fees over the whole horizon
      - `confidence` 'measured' | 'estimated', required — `measured`: a published dataset covers this exact vehicle. `estimated`: authored constants, or data stretched to fit the cohort. Render it — the two are not interchangeable, and they differ between components of the same answer.
      - `items` object[], required — The individual charges summing to `total`
        - `label` string, required — Human-readable name of the charge
        - `total` integer, required — This charge over the whole horizon
        - `recurring` boolean, required — True when it is paid every year; false for a one-off that falls in year 1 (US sales tax)
      - `notes` string[] — Caveats worth surfacing alongside the component
  - `perYear` CostOfOwnershipYear[], required — One row per requested year. Not `totals.perYear` repeated: depreciation is steepest early and the one-off charges (US sales tax, registration) land in year 1.
    - `year` integer, required — Ordinal year of ownership, starting at 1
    - `calendarYear` integer, required — Calendar year the row covers
    - `vehicleAge` integer, required — The car's age in that year
    - `depreciation` integer, required — Value lost in this year
    - `fuel` integer, required — Fuel or charging cost in this year
    - `insurance` integer, required — Premiums in this year
    - `maintenance` integer, required — Maintenance in this year
    - `taxesAndFees` integer, required — Taxes and fees in this year — higher in year 1 where a one-off charge applies
    - `total` integer, required — Total for this year

## Other responses

- `400` — Missing make/model/year/country, an unsupported country, fuel type or currency, a fuel type the market does not support (lpg in US), or a numeric parameter out of range. Validated before the upstream call.
- `403` — Invalid or missing API key, suspended account, or inactive subscription
- `404` — A component could not be estimated for this vehicle. `missing` names which one and `hint` says what to change. Expected for rare cars and uncommon drivetrains; the same query is cached, so retrying it unchanged returns the same answer.
- `429` — Monthly quota exhausted or per-minute rate limit exceeded. Quota responses carry resetDate; rate-limit responses carry a Retry-After header.
- `502` — The upstream cost-data service answered with an unexpected status or payload
- `503` — Upstream cost-data service unreachable or timed out

## Changes

- **2026-08-10** `cf1d4e12baca` — 12 info
  - added the non-success response with the status `403`
  - added the non-success response with the status `429`
  - removed the non-success response with the status `401`
  - added the optional property `code` to the response with the `400` status
  - …8 more

[Change history](https://skmtc.dev/carapi/apis/carapi-dev-automotive-data-api/changes/cost-of-ownership/get.md)

---

[API](https://skmtc.dev/carapi/apis/carapi-dev-automotive-data-api.md) · [All operations](https://skmtc.dev/carapi/apis/carapi-dev-automotive-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/carapi/carapi-dev-automotive-data-api/revisions/cf1d4e12baca/schema)