Stocks API

Manage stock snapshots and retrieve market data from EODHD API

Last Updated

16 Oct 2025 - Current Implementation

Overview

The Stocks API provides endpoints for creating and managing stock data snapshots. Each snapshot represents a point-in-time capture of:

End-of-Day (EOD) Pricing - Historical OHLCV price data
Fundamentals - Financial statements, ratios, and key metrics
Company News - Latest news articles
Technical Indicators - Pre-calculated indicators

Snapshot Architecture

Understanding Snapshots

QuantCoderFS uses a snapshot-based architecture to track stock data over time:

Snapshot ID Format: YYYYMMDD_HHMMSS (e.g., 20251016_143022)
Multiple Snapshots: Each ticker can have multiple snapshots taken at different times
Independent Data: Each snapshot contains its own EOD data, fundamentals, news, and analysis
File Storage: Data is stored in /stocks/{ticker}/{snapshot_id}/
Versioning: Track how market conditions and analysis change over time

Legacy Format: The old project_id format (ticker_timestamp) is still supported but deprecated.

Core Endpoints

POST /api/stocks/create

Create a new stock snapshot and fetch data from EODHD API.

Request Body

{
  "ticker": "AAPL.US",
  "lookback_years": 1,
  "period": "1d",
  "limit": 250
}

Request Parameters

Field	Type	Required	Description
`ticker`	string	Yes	Stock ticker symbol (e.g., "AAPL.US")
`lookback_years`	integer	No	Years of historical data (default: 1)
`period`	string	No	Granularity: '1m', '5m', '1h', '1d', '1w', '1M' (default: '1d')
`limit`	integer	No	Number of candles to fetch (default: 250)

Example Request (cURL)

curl -X POST "http://localhost:8004/api/stocks/create" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "AAPL.US",
    "lookback_years": 1,
    "period": "1d",
    "limit": 250
  }'

Example Request (Python)

import requests

response = requests.post(
    "http://localhost:8004/api/stocks/create",
    json={
        "ticker": "AAPL.US",
        "lookback_years": 1,
        "period": "1d",
        "limit": 250
    }
)

data = response.json()
print(f"Snapshot ID: {data['snapshot_id']}")

Response (201 Created)

{
  "ticker": "AAPL.US",
  "snapshot_id": "20251016_143022",
  "stock": {
    "ticker": "AAPL.US",
    "eod_data": {
      "code": "AAPL.US",
      "data": [
        {
          "code": "AAPL.US",
          "exchange_short_name": "NASDAQ",
          "data": [
            {
              "date": "2025-10-15",
              "open": 184.20,
              "high": 186.50,
              "low": 183.80,
              "close": 185.45,
              "adjusted_close": 185.45,
              "volume": 52341000
            }
          ]
        }
      ]
    },
    "fundamentals": {
      "General": {
        "Code": "AAPL",
        "Type": "Common Stock",
        "Name": "Apple Inc",
        "Exchange": "NASDAQ",
        "Sector": "Technology",
        "Industry": "Consumer Electronics"
      },
      "Highlights": {
        "MarketCapitalization": 2850000000000,
        "PERatio": 28.5,
        "DividendYield": 0.0052
      }
    },
    "news": {
      "articles": [
        {
          "date": "2025-10-15",
          "title": "Apple Announces New Product Line",
          "content": "...",
          "sentiment": {
            "polarity": 0.65,
            "neg": 0.1,
            "neu": 0.3,
            "pos": 0.6
          }
        }
      ]
    }
  }
}

GET /api/stocks/tickers

List all tickers that have stock data.

Example Request

curl "http://localhost:8004/api/stocks/tickers"

Response (200 OK)

["AAPL.US", "MSFT.US", "GOOGL.US", "TSLA.US"]

GET /api/stocks/{ticker}/snapshots

List all snapshots for a specific ticker.

Example Request

curl "http://localhost:8004/api/stocks/AAPL.US/snapshots"

Response (200 OK)

[
  {
    "snapshot_id": "20251016_143022",
    "created_at": "2025-10-16T14:30:22Z",
    "size_mb": 2.5,
    "has_eod": true,
    "has_fundamentals": true,
    "has_news": true
  },
  {
    "snapshot_id": "20251015_091500",
    "created_at": "2025-10-15T09:15:00Z",
    "size_mb": 2.4,
    "has_eod": true,
    "has_fundamentals": true,
    "has_news": true
  }
]

GET /api/stocks/{ticker}/snapshots/{snapshot_id}

Load a specific snapshot with all data.

Path Parameters

ticker string required

Stock ticker symbol (e.g., "AAPL.US")
snapshot_id string required

Snapshot ID (format: YYYYMMDD_HHMMSS)

Example Request

curl "http://localhost:8004/api/stocks/AAPL.US/snapshots/20251016_143022"

Response (200 OK)

{
  "ticker": "AAPL.US",
  "eod_data": { ... },
  "fundamentals": { ... },
  "news": { ... }
}

Error Responses

Status Code	Description
404	Snapshot not found for ticker/snapshot_id
500	Internal server error

Data Management Endpoints

POST /api/stocks/refresh

Incrementally refresh stock data (fetch only missing EOD records, optionally refresh fundamentals/news).

Request Body

{
  "ticker": "AAPL.US",
  "refresh_fundamentals": true,
  "refresh_news": true
}

Response (200 OK)

{
  "ticker": "AAPL.US",
  "eod_records_added": 5,
  "news_articles_added": 12,
  "fundamentals_refreshed": true,
  "errors": [],
  "stock": { ... }
}

File Storage Endpoints

GET /api/stocks/{ticker}/files

List all files available for a stock (directory structure with metadata).

Response (200 OK)

{
  "ticker": "AAPL.US",
  "data_files": [
    {
      "filename": "eod_prices.csv",
      "size_kb": 52.3,
      "modified": 1697456789
    },
    {
      "filename": "fundamentals.json",
      "size_kb": 124.5,
      "modified": 1697456790
    },
    {
      "filename": "news.txt",
      "size_kb": 89.2,
      "modified": 1697456791
    }
  ],
  "snapshots": [
    {
      "snapshot_id": "20251016_143022",
      "size_mb": 2.5
    }
  ]
}

GET /api/stocks/{ticker}/files/eod

Download EOD prices CSV file.

Example Request

curl "http://localhost:8004/api/stocks/AAPL.US/files/eod" \
  --output aapl_eod_prices.csv

Response (200 OK)

Returns CSV file with headers:

date,open,high,low,close,adjusted_close,volume
2024-10-16,184.20,186.50,183.80,185.45,185.45,52341000
...

GET /api/stocks/{ticker}/files/fundamentals

Download fundamentals JSON file.

Example Request

curl "http://localhost:8004/api/stocks/AAPL.US/files/fundamentals" \
  --output aapl_fundamentals.json

GET /api/stocks/{ticker}/files/news

Download news articles TXT file (line-delimited JSON).

Example Request

curl "http://localhost:8004/api/stocks/AAPL.US/files/news" \
  --output aapl_news.txt

GET /api/stocks/{ticker}/files/metadata

Get metadata.json contents.

Response (200 OK)

{
  "ticker": "AAPL.US",
  "created_at": "2025-10-16T14:30:22Z",
  "lookback_years": 1,
  "period": "1d",
  "limit": 250,
  "eod_count": 252,
  "news_count": 50
}

Delete Endpoints

DELETE /api/stocks/{ticker}/snapshots/{snapshot_id}

Delete an entire snapshot (all data, analysis, research).

Example Request

curl -X DELETE \
  "http://localhost:8004/api/stocks/AAPL.US/snapshots/20251016_143022"

Response (200 OK)

{
  "status": "deleted",
  "ticker": "AAPL.US",
  "snapshot_id": "20251016_143022"
}

DELETE /api/stocks/{ticker}

Delete entire ticker directory with all snapshots.

Example Request

curl -X DELETE "http://localhost:8004/api/stocks/AAPL.US"

Response (200 OK)

{
  "status": "deleted",
  "ticker": "AAPL.US"
}

Legacy Endpoints (Deprecated)

Deprecated Endpoints

The following endpoints are maintained for backward compatibility but should not be used in new code:

GET /api/stocks/list - Use GET /api/stocks/tickers instead
GET /api/stocks/load?project_id={ticker}_{timestamp} - Use GET /api/stocks/{ticker}/snapshots/{snapshot_id} instead

Data Models

Stock Model

Field	Type	Description
`ticker`	string	Stock ticker symbol
`eod_data`	EODResult	Historical price data
`fundamentals`	StockFundamentals	Financial statements and ratios
`news`	NewsData	News articles with sentiment

EOD Price Record

Field	Type	Description
`date`	date	Trading date
`open`	float	Opening price
`high`	float	High price
`low`	float	Low price
`close`	float	Closing price
`volume`	integer	Trading volume
`adjusted_close`	float	Adjusted closing price

EODHD API Integration

QuantCoderFS fetches data from EODHD Financial APIs. You need a valid API key configured in Settings. Free tier includes:

20 years of historical EOD data
Fundamental data (financial statements, ratios)
Company news
100 API requests per day (free tier)

Error Responses

Status Code	Description
400	Invalid request (missing ticker, invalid format)
404	Stock/snapshot not found
500	Internal server error or EODHD API error

Next Steps

Signals API - Generate trading signals using stock snapshots
Research API - Generate comprehensive research reports
Settings API - Configure API keys and credentials
Dependencies & Third-Party Services