Investment Return API: The Complete Guide

Need to calculate investment returns in your fintech application? This guide covers everything you need to know about return calculation via API, including ROI, CAGR, and other performance metrics with implementation examples.

Return Metrics Explained

Investment return is the gain or loss on an investment over a period, expressed as a percentage of the initial investment. Different metrics serve different purposes: simple ROI for quick comparisons, CAGR for annualized performance, and IRR for cash flow analysis.

Understanding these metrics helps investors compare opportunities, evaluate portfolio performance, and make data-driven decisions.

Types of Return Calculations

Common return calculations for investments:

Simple ROI (Return on Investment)

Basic return calculation: (Final Value - Initial Value) / Initial Value. Quick and intuitive but doesn't account for time.

CAGR (Compound Annual Growth Rate)

Annualized return that smooths out volatility. Essential for comparing investments over different time periods.

Annualized Return

Similar to CAGR, converts total return to yearly equivalent for standardized comparison.

Time-Weighted Return

Removes the effect of cash flows (deposits/withdrawals). Used for evaluating portfolio manager performance.

Using the Investment Return API

TinyFn provides a simple endpoint to calculate investment returns:

GET https://api.tinyfn.io/v1/finance/roi?initial=10000&final=15000&years=3
Headers: X-API-Key: your-api-key

{
  "initial_value": 10000,
  "final_value": 15000,
  "years": 3,
  "gain": 5000,
  "returns": {
    "simple_roi": 50.0,
    "cagr": 14.47,
    "annualized": 14.47,
    "total_return": 50.0
  },
  "multiplier": 1.5,
  "double_time_years": 5.13
}

Parameters

Code Examples

JavaScript / Node.js

const response = await fetch(
  'https://api.tinyfn.io/v1/finance/roi?initial=10000&final=15000&years=3',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const data = await response.json();
console.log(`CAGR: ${data.returns.cagr}%`); // CAGR: 14.47%

Python

import requests

response = requests.get(
    'https://api.tinyfn.io/v1/finance/roi',
    params={'initial': 10000, 'final': 15000, 'years': 3},
    headers={'X-API-Key': 'your-api-key'}
)
data = response.json()
print(f"ROI: {data['returns']['simple_roi']}%, CAGR: {data['returns']['cagr']}%")

cURL

curl "https://api.tinyfn.io/v1/finance/roi?initial=10000&final=15000&years=3" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Portfolio Trackers: Display investment performance over time
• Robo-Advisors: Calculate and display portfolio returns
• Investment Platforms: Compare fund or stock performance
• Financial Reports: Generate performance summaries
• Real Estate Apps: Calculate property investment returns

Best Practices

1. Use CAGR for comparison: Annualized returns allow fair comparison
2. Include dividends: Total return includes both appreciation and income
3. Consider inflation: Real returns matter more than nominal returns
4. Show multiple metrics: Different metrics serve different purposes