Skip to content

API_DOCUMENTATION.md

Latest commit

 

History

History
121 lines (110 loc) · 2.63 KB

API_DOCUMENTATION.md

File metadata and controls

121 lines (110 loc) · 2.63 KB

API Documentation

Base URL: http://localhost:8000

Endpoints

1. Health Check

Used to verify if the API is running.

  • URL: /health
  • Method: GET
  • Response: 
    {
  "status": "ok"
}

2. Get Stock Data

Fetch 5 years of historical OHLCV data for a specific ticker.

  • URL: /api/v1/stocks/{ticker}
  • Method: GET
  • Path Parameters:
    • ticker: Stock symbol (e.g., AAPL, MSFT). Case-insensitive.
  • Success Response (200): 
    {
  "ticker": "AAPL",
  "data": [
    {
      "date": "2021-01-26",
      "open": 143.6,
      "high": 144.3,
      "low": 141.37,
      "close": 143.16,
      "adj_close": 139.36,
      "volume": 98390600
    },
    ...
  ]
}
  • Error Response (404):
    • If ticker is invalid or no data found.
    {
  "detail": "No data found for ticker INVALID"
}

3. Get Portfolio Analytics

Fetch the equal-weighted portfolio performance, including time series and aggregate metrics.

  • URL: /api/v1/portfolio
  • Method: GET
  • Success Response (200): 
    {
  "portfolio_value": [
    {
      "date": "2021-01-26",
      "value": 10000.0
    },
    {
      "date": "2021-01-27",
      "value": 9799.98
    },
    ...
  ],
  "asset_contributions": {
    "AAPL": {
      "weight": 0.25,
      "return_pct": 83.45
    },
    "MSFT": {
      "weight": 0.25,
      "return_pct": 111.75
    },
    "GOOGL": {
      "weight": 0.25,
      "return_pct": 253.03
    },
    "AMZN": {
      "weight": 0.25,
      "return_pct": 43.91
    }
  },
  "metrics": {
    "total_return_pct": 123.04,
    "cagr": 17.4,
    "volatility": 0.247,
    "max_drawdown": -0.389,
    "sharpe_ratio": 0.775
  }
}
  • Error Response (502):
    • If backend fails to fetch data or calculate metrics.
    {
  "detail": "Portfolio calculation failed: ..."
}

Types

Portfolio Metrics

Field Type Description
total_return_pct float Total return percentage over the period.
cagr float Compound Annual Growth Rate (%).
volatility float Annualized volatility (standard deviation of daily returns).
max_drawdown float Maximum observed loss from a peak to a trough.
sharpe_ratio float Risk-adjusted return (assuming risk-free rate = 0).

Asset Contribution

Field Type Description
weight float Initial weight of the asset (0.25).
return_pct float Total return percentage for this specific asset.