--- title: 'API Introduction' description: 'RESTful API for the 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. 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](/api-reference/auth) for details on the OAuth flow and session management. ## API Categories Access monthly trading data, P&L reports, and individual trade details Get symbol lists, trading statistics, and detailed performance data View daily trading activity, export reports, and market metrics Manage portfolio holdings and trigger price updates Upload CSV files and view import history Query trading performance across custom date ranges OAuth endpoints and session management Monitor application health and readiness ## Response Format All API responses return JSON with a consistent structure: ### Success Response ```json { "success": true, "data": { ... }, "data_source": "postgresql" } ``` ### Error Response ```json { "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 ```bash curl -X GET https://performance.miningwood.com/api/months \ -H "Cookie: session=your_session_cookie" ``` ### Get Portfolio Holdings ```bash curl -X GET https://performance.miningwood.com/api/portfolio/holdings \ -H "Cookie: session=your_session_cookie" ``` ### Analyze Custom Timeframe ```bash 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: ```javascript JavaScript (Fetch) const response = await fetch('/api/months', { credentials: 'include' // Include cookies }); const data = await response.json(); ``` ```python Python (requests) import requests session = requests.Session() response = session.get('https://performance.miningwood.com/api/months') data = response.json() ``` ```bash cURL curl -X GET https://performance.miningwood.com/api/months \ --cookie-jar cookies.txt \ --cookie cookies.txt ``` ## Data Models ### Trade Object ```json { "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 ```json { "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 ```json { "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: ```javascript 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 Application monitoring and health endpoints Learn about OAuth flow and session management Explore trading data endpoints Symbol lists and performance data Manage portfolio holdings Daily activity and export reports Upload and track CSV imports Query custom date ranges