curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Return on investment (ROI) API

Gain, ROI percentage and annualized return (CAGR) of an investment.

POST https://api.curatedapi.com/v1/calc/finance/roi

ROI = (amount returned − amount invested) ÷ amount invested. With the holding period in years, also returns the annualized return (compound annual growth rate): (returned ÷ invested)^(1 ÷ years) − 1.

Formula

ROI = (R − I) ÷ I; annualized = (R ÷ I)^(1/years) − 1
  • Amounts are plain numbers in any single currency; no currency conversion is done.

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
amount_invested required decimal (string) Total amount put in. Allowed: > 0 and <= 1000000000000000. Unit: currency.
amount_returned required decimal (string) Total amount received back (sale value plus income). Allowed: >= 0 and <= 1000000000000000. Unit: currency.
years decimal (string) Holding period in years, for the annualized return. Allowed: > 0 and <= 1000. Unit: years.
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
gaindecimal (string)Amount returned minus amount invested. Unit: currency.
roi_percentdecimal (string)Return on investment in percent. Unit: percent.
annualized_roi_percentdecimal (string)Compound annual growth rate in percent. Unit: percent.

Examples

10,000 grows to 14,500 in 3 years

Requestcurl
curl https://api.curatedapi.com/v1/calc/finance/roi \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_invested": "10000",
    "amount_returned": "14500",
    "years": "3"
  }'
200 OKResponse
{
  "calculator": "finance/roi@1",
  "result": {
    "gain": "4500.00",
    "roi_percent": "45.00",
    "annualized_roi_percent": "13.19"
  },
  "exactness": {
    "gain": "exact",
    "roi_percent": "exact",
    "annualized_roi_percent": "rounded"
  },
  "precision": {
    "rounding": "half_even",
    "decimals": 2
  },
  "inputs": {
    "amount_invested": "10000",
    "amount_returned": "14500",
    "years": "3"
  },
  "formula": "ROI = (R − I) ÷ I; annualized = (R ÷ I)^(1/years) − 1",
  "references": [
    {
      "title": "Compound annual growth rate (CAGR)",
      "url": "https://en.wikipedia.org/wiki/Compound_annual_growth_rate"
    }
  ],
  "warnings": []
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.