Skip to main content

​
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

FieldTypeDescription
successbooleanIndicates if the request was successful
errorstringError message (only present on failure)
data_sourcestringDatabase source (typically “postgresql”)
redirect_to_loginbooleanWhether client should redirect to login (for 401 errors)

​
HTTP Status Codes

The API uses standard HTTP status codes:
CodeMeaningWhen Used
200OKSuccessful request
400Bad RequestInvalid request parameters
401UnauthorizedAuthentication required
403ForbiddenUser not authorized
404Not FoundResource not found
500Internal Server ErrorServer-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();

​
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