Documentation
Understand how Celvari models EV vs ICE total cost of ownership, or integrate our TCO engine into your own application via the REST API.
Quickstart
Enter your vehicles and driving profile, get a TCO comparison in under 5 minutes.
Read moreTCO Model
How we calculate total cost of ownership from fuel, maintenance, insurance, registration and resale value, with every source and assumption listed.
Read moreSavings Range and Simulation
The savings range measured from historical fuel-price windows, and the separate Monte Carlo and battery tools, whose spreads are our choices.
Read moreIncentive Engine
The federal clean vehicle credit status, read from the IRS page. State programs are not listed.
Read moreBreak-Even Analysis
The year when cumulative EV cost drops below the cumulative cost of the gas vehicle, with sensitivity analysis on each input.
Read moreCharging Cost Model
Annual electricity use, the home and public mix, and an optional off-peak share, at the rates you send.
Read moreAPI Endpoints
/v1/calculate/v1/vehicles/:year/:make/v1/rates/:zip/v1/incentives/:state/v1/signup/v1/login/v1/account/v1/checkoutAuthentication
All API requests require an API key passed via the X-API-Key header.
curl https://celvari-api.smarttechinvest.com/v1/rates/90210 \ -H "X-API-Key: cel_your_api_key_here"
Total Cost of Ownership Model
For each vehicle, we compute the total cost of ownership as:
Yearly fuel cost is your annual miles divided by the vehicle's efficiency, times the price of the fuel, the same arithmetic as the EPA fuel economy label. Efficiency comes from the EPA ratings (fueleconomy.gov) for the three newest model years in the file; electricity and gasoline prices are the U.S. Energy Information Administration's figures for your state. The costs are summed in nominal dollars with no discounting, which is the zero-discount case of the life-cycle cost formula in NIST Handbook 135 (Equation 5-1).
Prices grow year to year at the ten-year rates of the BLS consumer price indexes for gasoline, electricity and all items, carried forward. Maintenance per mile comes from the AAA Your Driving Costs study (medium sedan, electric and gas), scaled to your miles. Depreciation is our own estimate: no free source for resale values exists, so it is labeled as an estimate and you can override it.
Purchase price and insurance are yours to enter. When you leave one out, the results page uses an example value and lists it under the headline, so you can see what was assumed.
Savings Range and Simulation
The headline comparison comes with a savings range measured from history. We take every historical window of your ownership length (up to nine years) in the stored gasoline and electricity price indexes, grow the two fuel prices by the rates each window actually saw, re-run the cost arithmetic, and report the 10th to 90th percentile of the savings. The range shows how far fuel prices alone could move the answer. It is not a forecast, and it holds every other input where you set it.
The Monte Carlo endpoint of the API (POST /api/v1/montecarlo) is a separate tool. It varies gas and electricity growth, depreciation, maintenance and price levels around your assumptions with spreads we chose, not measured ones, and the response says so. Its distribution is only as good as those choices.
Battery degradation (POST /api/v1/battery) is also an authored model with stated constants, not a fit to a published study.
Incentives
The IRS states that the New Clean Vehicle Credit is not available for vehicles acquired after September 30, 2025. We read that page about once a week; if our stored copy is older than ten days or the read failed, the federal answer is unavailable instead of a number. A vehicle counts as acquired on the date a binding written contract was signed and a payment made, so a purchase committed on or before that date can still qualify even if delivery came later; for those, the incentives endpoint applies the credit rules as coded (price caps and income limits).
State and utility programs are not listed. The Department of Energy publishes them in its laws and incentives database, which needs a registered key, and we found no public file we could fetch without one. See afdc.energy.gov/laws for the current programs in your state.
Break-Even Analysis
The break-even calculation finds the ownership year where cumulative EV costs cross below cumulative gas-vehicle costs, using the same prices, growth rates and maintenance defaults as the total cost comparison. It extends up to 15 years to find the crossover, and reports none if the EV never catches up.
The sensitivity endpoint (POST /api/v1/sensitivity) moves each input up and down by 20% (or a fraction you choose) one at a time and ranks them by how much the savings change, so you can see which assumption matters most.
Charging Cost Model
Annual electricity use is your miles divided by miles per kWh. The charging endpoint (POST /api/v1/charging) splits it between home and public charging by the share you give, prices each at the rates you send, and can apply an off-peak rate to a share of home charging. It also reports the MPG a gas vehicle would need to cost the same per mile, when you send a gas price.
The calculator uses your state's average residential electricity price from the Energy Information Administration. It does not look up your utility's rate plan, and the home-charger installed cost and the public-charging rate it uses when you pick those options are example values, listed on your results.