API Introduction - Trading Analysis Dashboard

Overview

The Trading Analysis Dashboard exposes a RESTful API for accessing trading data, portfolio holdings, and performance metrics programmatically. The API powers the web interface and can be used to build custom integrations or automation tools.

Live Application

Visit the Trading Analysis Dashboard at performance.miningwood.com

Base URL

https://performance.miningwood.com

For local development:

http://localhost:5000

Authentication

All API endpoints require authentication via Google OAuth 2.0. The API uses session-based authentication with HTTP-only cookies set after successful OAuth login.

See the Authentication guide for details on the OAuth flow and session management.

API Categories

Trading Data

Access monthly trading data, P&L reports, and individual trade details

Symbols

Get symbol lists, trading statistics, and detailed performance data

Calendar

View daily trading activity, export reports, and market metrics

Portfolio

Manage portfolio holdings and trigger price updates

Data Import

Upload CSV files and view import history

Timeframe Analysis

Query trading performance across custom date ranges

Authentication

OAuth endpoints and session management

Health Checks

Monitor application health and readiness

Response Format

All API responses return JSON with a consistent structure:

Success Response

{
  "success": true,
  "data": { ... },
  "data_source": "postgresql"
}

Error Response

{
  "success": false,
  "error": "Error message description"
}

Common Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`error`	string	Error message (only present on failure)
`data_source`	string	Database source (typically “postgresql”)
`redirect_to_login`	boolean	Whether client should redirect to login (for 401 errors)

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Meaning	When Used
`200`	OK	Successful request
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Authentication required
`403`	Forbidden	User not authorized
`404`	Not Found	Resource not found
`500`	Internal Server Error	Server-side error

Rate Limiting

The API does not currently implement rate limiting, but the Finnhub price refresh endpoint is subject to Finnhub’s API rate limits (60 requests/minute for free tier).

Data Types

Date Formats

Months: YYYY-MM format (e.g., "2024-08")
Dates: YYYY-MM-DD format (e.g., "2024-08-15")
Timestamps: ISO 8601 format (e.g., "2024-08-15T14:30:00Z")

Numeric Values

Prices: Decimal with 2-4 decimal places
Shares: Integer or decimal (supports fractional shares)
P&L Values: Decimal with 2 decimal places (can be negative)
Percentages: Decimal (e.g., 0.1523 for 15.23%)

Example Usage

Fetch Available Trading Months

curl -X GET https://performance.miningwood.com/api/months \
  -H "Cookie: session=your_session_cookie"

Get Portfolio Holdings

curl -X GET https://performance.miningwood.com/api/portfolio/holdings \
  -H "Cookie: session=your_session_cookie"

Analyze Custom Timeframe

curl -X GET "https://performance.miningwood.com/api/timeframe?start_date=2024-01-01&end_date=2024-06-30" \
  -H "Cookie: session=your_session_cookie"

Client Libraries

The API can be accessed using any HTTP client library:

const response = await fetch('/api/months', {
  credentials: 'include' // Include cookies
});
const data = await response.json();

import requests

session = requests.Session()
response = session.get('https://performance.miningwood.com/api/months')
data = response.json()

curl -X GET https://performance.miningwood.com/api/months \
  --cookie-jar cookies.txt \
  --cookie cookies.txt

Data Models

Trade Object

{
  "symbol": "AAPL",
  "buy_date": "2024-01-15",
  "sell_date": "2024-03-20",
  "buy_price": 150.25,
  "sell_price": 165.80,
  "volume": 100,
  "profit_loss": 1555.00,
  "return_percentage": 10.35
}

Holding Object

{
  "id": 123,
  "symbol": "MSFT",
  "type": "stock",
  "shares": 50,
  "average_cost": 320.50,
  "current_price": 345.20,
  "market_value": 17260.00,
  "gain_loss": 1235.00,
  "gain_loss_percentage": 7.70,
  "last_updated": "2024-08-15T14:30:00Z"
}

Month Summary Object

{
  "month": "2024-08",
  "total_trades": 15,
  "winning_trades": 10,
  "win_rate": 66.67,
  "trading_pl": 1250.75,
  "dividend_income": 125.50,
  "total_return_with_dividends": 1376.25
}

Error Handling

Always check the success field before processing response data:

const response = await fetch('/api/months');
const data = await response.json();

if (!data.success) {
  console.error('API Error:', data.error);
  
  if (data.redirect_to_login) {
    window.location.href = '/auth/login';
  }
  return;
}

// Process data.months

Next Steps

Health Checks

Application monitoring and health endpoints

Authentication

Learn about OAuth flow and session management

Trading Data

Explore trading data endpoints

Symbols

Symbol lists and performance data

Portfolio API

Manage portfolio holdings

Calendar

Daily activity and export reports

Data Import

Upload and track CSV imports

Timeframe Analysis

Query custom date ranges

​Overview

Live Application

​Base URL

​Authentication

​API Categories

Trading Data

Symbols

Calendar

Portfolio

Data Import

Timeframe Analysis

Authentication

Health Checks

​Response Format

​Success Response

​Error Response

​Common Response Fields

​HTTP Status Codes

​Rate Limiting

​Data Types

​Date Formats

​Numeric Values

​Example Usage

​Fetch Available Trading Months

​Get Portfolio Holdings

​Analyze Custom Timeframe

​Client Libraries

​Data Models

​Trade Object

​Holding Object

​Month Summary Object

​Error Handling

​Next Steps

Health Checks

Authentication

Trading Data

Symbols

Portfolio API

Calendar

Data Import

Timeframe Analysis

Overview

Base URL

Authentication

API Categories

Response Format

Success Response

Error Response

Common Response Fields

HTTP Status Codes

Rate Limiting

Data Types

Date Formats

Numeric Values

Example Usage

Fetch Available Trading Months

Get Portfolio Holdings

Analyze Custom Timeframe

Client Libraries

Data Models

Trade Object

Holding Object

Month Summary Object

Error Handling

Next Steps