API Documentation

Introduction

FactorsToday provides a robust API for quantitative analysts and developers to integrate our factor models into their existing workflows. Our RESTful API allows you to programmatically access live returns, historical data, and individual stock factor loadings.

Factor Endpoints

GET /api/factor-returns

Returns real-time 1-day performance data for all tracked factors across Basic, Industry, Country, and Custom models.

GET /api/factor-history/:factorId

Retrieves historical time-series data for a specific factor. Returns date and close values in chronological order.

Query params: ?days=N (default: 365)

GET /api/factor-loadings/:factorNameEncoded

Returns stocks and their beta exposures to a specific factor. The factor name must be base64 encoded to handle special characters.

Query params: ?type=all|common|etf|both

GET /api/factor-correlations

Returns the correlation matrix between all factors based on historical returns.

Query params: ?days=N (default: 90), ?mode=standard|all

GET /api/factor-sparklines

Returns daily returns for all factors over a specified period, suitable for rendering sparkline charts.

Query params: ?days=N (default: 30)

GET /api/factor-composition/:factorName

Returns the component stocks/ETFs that make up a custom factor basket, including their weights.

GET /api/factor-equation/:factorNameEncoded

Returns the replication equation for a specific factor, including all component weights (tickers and factors). The factor name must be base64 encoded.

Response: { "factor_name": "...", "equation": { "ticker1": weight, "Factor1": weight, ... } }

GET /api/factors

Returns a list of all available factors with calculated performance metrics (1-day, 1-week, 1-month returns).

Stock Endpoints

GET /api/stocks/search

Searches both stocks and factors by name or ticker. Supports multi-word queries where each word must match. Results are ranked by trading volume.

Query params: ?q=searchterm (required)

GET /api/stocks/popular

Returns the top 100 most popular stocks ranked by market capitalization and trading volume.

Query params: ?type=stockType (optional filter by stock type)

GET /api/stocks/types

Returns a list of all distinct stock types available in the database (e.g., Common Stock, ETF, ADR).

GET /api/stock-history/:ticker

Returns historical price data (date and close) for a specific stock ticker in chronological order.

Query params: ?days=N (default: 252, roughly 1 trading year)

GET /api/stock-info/:ticker

Returns metadata for a specific stock including full name, stock type, and current price.

GET /api/stock-loadings/:ticker

Fetches the most recent factor betas and exposures for a stock ticker. Returns all factor loadings sorted by beta (exposure strength), along with model quality metrics (R² and Adjusted R²).

Query params: ?model=modelName (default: "All Factors")

Available models: Base, Base + Sector, Base + Sector + Industry, All Factors

Response includes: r_squared, adjusted_r_squared, n_active_factors

GET /api/related-stocks/:ticker

Finds stocks with similar factor exposures using cosine similarity. Returns stocks ranked by how closely their factor profile matches the target.

Query params: ?limit=N (default: 10), ?model=modelName (default: "All Factors")

Portfolio & Screener Endpoints

POST /api/portfolio/analyze

Analyzes a portfolio's factor exposures. Accepts an array of holdings with ticker and shares, calculates weighted factor exposures, identifies concentration risks, and suggests hedging strategies.

Body: { "holdings": [{ "ticker": "AAPL", "shares": 100 }, ...] }

Query params: ?model=modelName (default: "All Factors")

GET /api/screener/stocks-by-factor/:factorName

Returns all stocks ranked by their exposure to a specific factor. Useful for finding stocks with high or low sensitivity to particular market factors.

Query params: ?model=modelName (default: "All Factors")

Response includes: ticker, name, exposure (beta), r_squared, adjusted_r_squared

GET /api/screener/stocks

Returns all stocks with their model fit quality metrics (R² and Adjusted R²), without filtering by factor exposure. Useful for finding stocks with high or low factor model fit, or for screening based purely on model quality.

Query params: ?model=modelName (default: "All Factors")

Response includes: ticker, name, stock_type, r_squared, adjusted_r_squared

Factor Models

Stock loadings are calculated against four progressively more comprehensive factor models. Use the model query parameter to select which model to use:

Base Standard macro factors only (Market, Size, Value, Momentum, Quality, etc.)
Base + Sector Adds 11 GICS sector factors (Technology, Financial, Healthcare, etc.)
Base + Sector + Industry Adds ~50 granular industry factors (Semiconductors, Biotechnology, etc.)
All Factors Adds country factors (42) and AI-discovered custom thematic factors (default)

Model Quality Metrics

Stock loading endpoints return R² and Adjusted R² to measure how well the factor model explains a stock's returns:

r_squared Proportion of variance explained by the model (0.0 to 1.0). Higher = better fit.
adjusted_r_squared R² adjusted for model complexity. Penalizes overfitting from too many factors.
n_active_factors Number of factors with non-zero exposure (used in Adjusted R² calculation).

Interpretation: R² < 10% = poor fit, 10-30% = fair fit, > 30% = good fit. Stocks with low R² have more idiosyncratic (stock-specific) risk.

Authentication

For the time being, the FactorsToday API is open and does not require an API key for access. We encourage developers to build and experiment freely with our datasets.

Rate Limits

To ensure stable performance for all users, the API is limited to 10 requests per second per IP address. Exceeding this limit will result in a 429 Too Many Requests response.