Fundamentals

Overview

The Fundamentals scraper retrieves comprehensive financial data — income statement, balance sheet, cash flow, margins, profitability, liquidity, leverage, valuation, and dividends — for any symbol via the TradingView scanner API.

Quick Start

from tv_scraper.scrapers.market_data import Fundamentals

scraper = Fundamentals()

# All fundamental metrics for Apple
result = scraper.get_fundamentals(exchange="NASDAQ", symbol="AAPL")
print(result["data"])

# Income statement only
income = scraper.get_income_statement(exchange="NASDAQ", symbol="AAPL")

# Compare multiple symbols
comparison = scraper.compare_fundamentals(
    symbols=[
        {"exchange": "NASDAQ", "symbol": "AAPL"},
        {"exchange": "NASDAQ", "symbol": "MSFT"},
    ],
    fields=["total_revenue", "net_income", "market_cap_basic"],
)

Constructor

Fundamentals(
    export_result: bool = False,
    export_type: str = "json",   # "json" or "csv"
    timeout: int = 10,
)

Methods

`get_fundamentals(exchange, symbol, fields=None)`

Fetch fundamental data for a single symbol.

Parameter	Type	Default	Description
`exchange`	`str`	—	Exchange name (e.g. `"NASDAQ"`)
`symbol`	`str`	—	Trading symbol (e.g. `"AAPL"`)
`fields`	`list[str] \\| None`	`None`	Specific fields. `None` → all fields.

Returns a standardized response envelope:

{
    "status": "success",
    "data": {"symbol": "NASDAQ:AAPL", "total_revenue": ..., ...},
    "metadata": {"exchange": "NASDAQ", "symbol": "AAPL"},
    "error": None,
}

`compare_fundamentals(symbols, fields=None)`

Compare fundamental data across multiple symbols.

Parameter	Type	Default	Description
`symbols`	`list[dict]`	—	List of `{"exchange": "...", "symbol": "..."}` dicts
`fields`	`list[str] \\| None`	`None`	Specific fields. `None` → key comparison metrics.

Category Helpers

Each takes exchange: str, symbol: str and returns the same envelope:

Method	Fields
`get_income_statement()`	Revenue, profit, EPS, EBITDA
`get_balance_sheet()`	Assets, debt, equity
`get_cash_flow()`	Operating, investing, financing cash flows
`get_statistics()`	Liquidity + leverage + valuation ratios
`get_dividends()`	Yield, per share, payout ratio
`get_profitability()`	ROE, ROA, ROI
`get_margins()`	Gross, operating, net, EBITDA margins

Field Categories

Income Statement (13 fields)

total_revenue, revenue_per_share_ttm, total_revenue_fy, gross_profit, gross_profit_fy, operating_income, operating_income_fy, net_income, net_income_fy, EBITDA, basic_eps_net_income, earnings_per_share_basic_ttm, earnings_per_share_diluted_ttm

Balance Sheet (9 fields)

total_assets, total_assets_fy, cash_n_short_term_invest, cash_n_short_term_invest_fy, total_debt, total_debt_fy, stockholders_equity, stockholders_equity_fy, book_value_per_share_fq

Cash Flow (7 fields)

cash_f_operating_activities, cash_f_operating_activities_fy, cash_f_investing_activities, cash_f_investing_activities_fy, cash_f_financing_activities, cash_f_financing_activities_fy, free_cash_flow

Margins (8 fields)

gross_margin, gross_margin_percent_ttm, operating_margin, operating_margin_ttm, pretax_margin_percent_ttm, net_margin, net_margin_percent_ttm, EBITDA_margin

Profitability (5 fields)

return_on_equity, return_on_equity_fq, return_on_assets, return_on_assets_fq, return_on_investment_ttm

Liquidity (4 fields)

current_ratio, current_ratio_fq, quick_ratio, quick_ratio_fq

Leverage (3 fields)

debt_to_equity, debt_to_equity_fq, debt_to_assets

Valuation (8 fields)

market_cap_basic, market_cap_calc, market_cap_diluted_calc, enterprise_value_fq, price_earnings_ttm, price_book_fq, price_sales_ttm, price_free_cash_flow_ttm

Dividends (3 fields)

dividends_yield, dividends_per_share_fq, dividend_payout_ratio_ttm