{"id":"growth-cagr-compute","version":"1.0.0","description":"CAGR from start and end values or a total return over years or dates, with a sub-year warning.","supported_operations":["compound annual growth rate","CAGR calculator","annualized return from start and end value","average annual growth rate over years","annualize a total return","growth rate between two dates per year","Excel RRI function equivalent","revenue growth per year over five years"],"unsupported_operations":["total percent change without annualizing (use a percent-change tool)","time-weighted or money-weighted return of flows with contributions (use cashflow-xirr)","converting between nominal and effective rates","growth of a series with more than two observations (no regression or averaging)"],"semantics":["Growth input, exactly one of two forms: (a) start_value (decimal greater than 0) together with end_value (decimal at least 0); or (b) total_return (decimal at least -1, the total change as a fraction, for example 0.9 for +90 percent). Giving both forms, neither, only one of start_value and end_value, or total_return together with either value is invalid_input. The growth ratio is R = end_value / start_value, or R = 1 + total_return.","Time input, exactly one of two forms: (a) years (decimal greater than 0 and at most 1000); or (b) start_date and end_date (ISO calendar dates YYYY-MM-DD, year 1900 to 2200, start_date strictly before end_date, otherwise invalid_input) with the optional basis (default act-365f; basis together with years is invalid_input). Giving both forms, neither, or only one of the two dates is invalid_input.","Years from dates: with D the exact number of calendar days from start_date to end_date, act-365f gives D/365; act-365.25 gives D/365.25; act-act-isda gives the sum over the days x with start_date <= x < end_date of 1/366 when the calendar year of x is a leap year and 1/365 otherwise (ISDA 2006 Definitions 4.16(b)). Years are an exact rational value; the rounded years output is never fed back into the calculation.","CAGR = R^(1/years) - 1, with R = 0 giving exactly -1. total_return in the output is R - 1 (the input value in form (b)). years in the output is the exact years value. All three are rounded once to rate_scale (0 to 12, default 10) with the rounding mode, so years given as 0.4 with rate_scale 0 prints 0.","sub_year is true when the exact years value is less than 1 (for example 181 days on act-365f, or 365 days on act-365.25, which is 0.99932 years). The value is still returned. GIPS 2020 does not allow a firm to present returns annualized for a period shorter than one year, so a caller should treat a sub_year result as an extrapolation and not as a reportable annualized return.","Exact path: R^(1/years) is computed with an error below 1e-33 relative to max(1, |value|) and the CAGR and the total return are each rounded half-even to 30 fractional digits before the final rounding, so exact results such as 4^(1/2) - 1 = 1 are recovered exactly. If the CAGR magnitude would reach 1e20 the result is not_computable (details.reason overflow).","A decimal string longer than 64 UTF-8 bytes is limit_exceeded, checked before parsing. Percent values are not accepted: 0.2386 means 23.86 percent.","Every rounded output is rounded exactly once from the unrounded value using the rounding mode: half-up (ties away from zero, the default), half-even, half-down (ties toward zero), up (away from zero), down (toward zero), ceiling, floor. Amount outputs print exactly scale fractional digits and rate-like outputs exactly rate_scale fractional digits; a result that rounds to zero prints without a minus sign (never '-0.00').","Decimal string fields (amounts, rates) must match ^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$ with at most 20 integer digits and at most 20 fractional digits; a JSON number, exponent form, leading plus, surrounding spaces, percent sign, missing integer part or trailing dot is invalid_input. Rates are decimal fractions (0.065 means 6.5 percent; \"6.5\" means 650 percent). A decimal string longer than 64 UTF-8 bytes is limit_exceeded, checked before parsing.","Disclaimer: arithmetic calculation only; not financial, tax, legal, or investment advice."],"limits":{"max_string_bytes":64,"max_years":1000},"pricing":{"status":"unpriced","charge_usd":null},"input_schema":{"type":"object","additionalProperties":false,"required":[],"properties":{"start_value":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"end_value":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"total_return":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"years":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"start_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10},"end_date":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","maxLength":10},"basis":{"type":"string","enum":["act-365f","act-365.25","act-act-isda"]},"rate_scale":{"type":"integer","minimum":0,"maximum":12},"rounding":{"type":"string","enum":["half-up","half-even","half-down","up","down","ceiling","floor"]}}},"output_schema":{"type":"object","additionalProperties":false,"required":["cagr","total_return","years","sub_year"],"properties":{"cagr":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"total_return":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"years":{"type":"string","pattern":"^-?(0|[1-9][0-9]*)(\\.[0-9]+)?$","maxLength":64},"sub_year":{"type":"boolean"}}},"examples":[{"input":{"start_value":"10000","end_value":"19000","years":"3","rate_scale":4},"output":{"cagr":"0.2386","total_return":"0.9000","years":"3.0000","sub_year":false}},{"input":{"start_value":"100","end_value":"110","start_date":"2020-01-01","end_date":"2021-01-01","basis":"act-act-isda"},"output":{"cagr":"0.1000000000","total_return":"0.1000000000","years":"1.0000000000","sub_year":false}}],"execute_url":"/v1/tools/growth-cagr-compute/versions/1.0.0/execute"}