OpenBB Fama-French Provider Extension

This package adds the openbb-famafrench provider and router extension to the Open Data Platform by OpenBB.

It implements the Kenneth R. French Data Library, maintained and hosted at Dartmouth College, exposing research factors, research portfolios, and breakpoints as OpenBB Platform endpoints.

Installation

Install from PyPI with:

pip install openbb-famafrench

Then build the Python static assets by running:

openbb-build

Quick Start

The fastest way to get started is by connecting to the OpenBB Workspace as a custom backend.

Start Server

openbb-api

This starts the FastAPI server over localhost on port 6900.

Add to Workspace

See the documentation here for more details. The extension ships an apps.json describing a ready-made dashboard for exploring the Fama-French datasets.

Implementation Details

Kenneth French publishes returns and breakpoints as compressed CSV/DAT files. This extension downloads the requested dataset on demand, parses the multi-table file layout, and maps each table to the appropriate OpenBB standard model. Downloads are cached in-memory for the life of the process, so repeated requests for the same dataset do not re-fetch.

Every response carries the source file's own description in the extra["results_metadata"] field of the results object, including the dataset description, frequency, and the portfolio or factor formations contained in the file:

factors.extra["results_metadata"]

{
    "description": "### \n\nThis file was created using the 202504 CRSP database. ...",
    "frequency": "monthly",
    "formations": ["Mkt-RF", "SMB", "HML", "RF"],
}

Datasets

• Factors — the 3-Factor and 5-Factor models, plus Momentum and short/long-term reversal factors, for eight regions (america, north_america, europe, japan, asia_pacific_ex_japan, developed, developed_ex_us, emerging). Availability of a factor, and of a frequency for that factor, varies by region.
• US & Regional portfolios — research portfolios formed on size, book-to-market, operating profitability, investment, and industry, retrievable by value, equal, number_of_firms, or firm_size measures.
• Country & International index portfolios — value/growth portfolios formed on four valuation ratios, available in USD, local currency, or as ratios.
• Breakpoints — the NYSE breakpoints (every fifth percentile) used to construct the research portfolios.

Coverage

Endpoints

from openbb import obb

obb.famafrench
# /famafrench
#     breakpoints
#     country_portfolio_returns
#     factor_choices            <- utility endpoint serving choices to OpenBB Workspace widgets
#     factors
#     international_index_returns
#     regional_portfolio_returns
#     us_portfolio_returns

• obb.famafrench.factors — Fama-French research factors by region, factor, and frequency
• obb.famafrench.us_portfolio_returns — US research portfolio returns
• obb.famafrench.regional_portfolio_returns — regional research portfolio returns
• obb.famafrench.country_portfolio_returns — per-country value/growth portfolio returns
• obb.famafrench.international_index_returns — international index portfolio returns
• obb.famafrench.breakpoints — NYSE breakpoints used to form the research portfolios
• obb.famafrench.factor_choices — utility endpoint that populates OpenBB Workspace widget dropdowns (excluded from the OpenAPI schema)

Example

from openbb import obb

# The 3-Factor model for the US, monthly (defaults).
factors = obb.famafrench.factors()

# By region and factor.
momentum = obb.famafrench.factors(factor="momentum", region="europe")

# US research portfolios formed on size, equal-weighted, annual.
portfolios = obb.famafrench.us_portfolio_returns(
    portfolio="portfolios_formed_on_me",
    measure="equal",
    frequency="annual",
)

# Per-country value/growth portfolios.
japan = obb.famafrench.country_portfolio_returns(country="japan", measure="local")

# NYSE breakpoints.
breakpoints = obb.famafrench.breakpoints(breakpoint_type="op", start_date="1998-01-01")

Refer to each endpoint's docstring for detailed descriptions of the methodology.