Skip to content

fin-ratios

The most comprehensive open-source financial ratios library.

136+ ratios · 10 institutional-grade scoring models · TypeScript + Python.

npm PyPI License: MIT CI

What is fin-ratios?

fin-ratios is a zero-dependency library that computes financial ratios and institutional-grade scoring models from raw financial statement data. It ships identical APIs for both TypeScript and Python.

Unlike existing libraries that either fetch data (without analysis) or compute a handful of basic ratios, fin-ratios provides:

from fin_ratios.utils.investment_score import investment_score_from_series
from fin_ratios.fetchers.edgar import fetch_edgar

# Fetch 7 years of annual data from SEC EDGAR (free, no key)
annual_data = fetch_edgar('AAPL', num_years=7)

# Grand synthesis: Moat + Quality + Valuation + Management → Investment Score
score = investment_score_from_series(
    annual_data,
    pe_ratio=22.0,
    ev_ebitda=14.0,
)
print(f"{score.score}/100  [{score.grade}]  {score.conviction}")
# → 74/100  [B+]  buy

import { investmentScoreFromSeries } from 'fin-ratios'
import { fetchEdgarNormalized } from 'fin-ratios/fetchers/edgar'

// Fetch from SEC EDGAR (free, no key)
const annualData = await fetchEdgarNormalized('AAPL', { numYears: 7 })

// Full investment score
const score = investmentScoreFromSeries(annualData, {
  peRatio: 22.0,
  evEbitda: 14.0,
})
console.log(`${score.score}/100 [${score.grade}] ${score.conviction}`)
// → 74/100 [B+] buy

Scoring Models

Model Signals Output Reference
Economic Moat ROIC persistence, pricing power, reinvestment quality 0–100, wide/narrow/none Buffett, Mauboussin
Capital Allocation ROIC vs WACC, FCF quality, reinvestment yield 0–100, excellent–poor McKinsey Valuation
Earnings Quality Accruals ratio, cash backing, stability 0–100, high–poor Sloan (1996), Richardson (2005)
Quality Factor EQ + Moat + CA weighted composite 0–100, A–F grade Asness et al. (2019)
Valuation Attractiveness Earnings yield, FCF yield, EV/EBITDA, P/B, DCF upside 0–100, attractive–overvalued Damodaran (2012)
Management Quality ROIC trend, margin stability, dilution, execution 0–100, excellent–poor Mauboussin (2012)
Dividend Safety FCF payout, earnings payout, debt load, track record 0–100, safe–danger Siegel (2014)
Investment Score Grand synthesis of all models 0–100, A+–F, strong buy–sell —

Quick Navigation

  • Quick Start

    Install and run your first analysis in under 2 minutes.

  • Scoring Models

    Institutional-grade scores from raw financial data.

  • Ratio Reference

    136+ ratios with formulas and academic citations.

  • Data Fetchers

    Yahoo Finance, SEC EDGAR, FMP, Polygon, AlphaVantage, SimFin.

  • CLI Reference

    fin-ratios AAPL, fin-ratios score AAPL, fin-ratios serve.

  • TypeScript API

    Identical API in TypeScript with full type safety.