deepentropy/tvscreenerPublic

TradingView Screener API - Stock, Crypto, Forex, Bond, Futures, Coin

AI summary: Python library and visual code generator for querying the TradingView Screener API.

Stars
1.8K
+7 today
Forks
249
Watchers
18
Open issues
0
Open PRs
0
Contributors
~10
Commits
211
Branches
1
Views (30d)
4

JavaScriptApache-2.0Created Aug 2, 2023Last push 19d agoLatest release v0.8.2+11 stars this week+90 this month

Quick answers

What is tvscreener?
Python library and visual code generator for querying the TradingView Screener API.
What does tvscreener do?
TradingView Screener API (tvscreener) is a powerful Python library designed to programmatically retrieve and analyze financial data directly from the TradingView platform. It completely circumvents the need for official, expensive API subscriptions by effectively querying the publicly accessible screener endpoints. The library supports a massive range of asset classes, allowing quantitative developers to screen global stocks, cryptocurrencies, forex pairs, and futures markets simultaneously. It provides a visual code generator that allows non-programmers to intuitively build complex screening filters in the browser and instantly export the equivalent Python code. The underlying architecture robustly handles HTTP requests and parses the raw JSON responses into clean, structured datasets ready for immediate analysis.
Who is tvscreener for?
Quantitative analysts, algorithmic traders, and Python developers building financial tools. Familiarity with technical analysis concepts like RSI or MACD is beneficial.
How do I get started with tvscreener?
pip install tvscreener
How popular is tvscreener on GitHub?
deepentropy/tvscreener has 1,771 stars and 249 forks on GitHub, and gained 11 stars in the last 7 days.
What license does tvscreener use?
deepentropy/tvscreener is released under the Apache-2.0 license.

Star history

since Jul 29, 2026
05001K1.5KJul 2026Sep 2026Oct 2026Nov 2026
1.8K stars as of Nov 18, 2026. Measured daily since Jul 29, 2026; GitHub no longer exposes earlier star timestamps.

Update history

2 recorded
  • Nov 14, 2026New release v0.8.2 (previously v0.8.1).
  • Oct 19, 2026New release v0.8.1 (previously v0.5.2).

Contribution activity

commits per day, last 52 weeks
NovDecJanFebMarAprMayJunJulAugSepOctNovMonWedFri2025-11-16: 0 commits2025-11-17: 0 commits2025-11-18: 0 commits2025-11-19: 0 commits2025-11-20: 0 commits2025-11-21: 0 commits2025-11-22: 0 commits2025-11-23: 0 commits2025-11-24: 0 commits2025-11-25: 0 commits2025-11-26: 0 commits2025-11-27: 0 commits2025-11-28: 0 commits2025-11-29: 9 commits2025-11-30: 0 commits2025-12-01: 0 commits2025-12-02: 0 commits2025-12-03: 0 commits2025-12-04: 0 commits2025-12-05: 0 commits2025-12-06: 0 commits2025-12-07: 0 commits2025-12-08: 2 commits2025-12-09: 2 commits2025-12-10: 7 commits2025-12-11: 0 commits2025-12-12: 0 commits2025-12-13: 0 commits2025-12-14: 0 commits2025-12-15: 0 commits2025-12-16: 0 commits2025-12-17: 0 commits2025-12-18: 0 commits2025-12-19: 0 commits2025-12-20: 0 commits2025-12-21: 0 commits2025-12-22: 0 commits2025-12-23: 0 commits2025-12-24: 0 commits2025-12-25: 0 commits2025-12-26: 0 commits2025-12-27: 0 commits2025-12-28: 0 commits2025-12-29: 0 commits2025-12-30: 0 commits2025-12-31: 0 commits2026-01-01: 0 commits2026-01-02: 0 commits2026-01-03: 0 commits2026-01-04: 0 commits2026-01-05: 1 commit2026-01-06: 0 commits2026-01-07: 0 commits2026-01-08: 0 commits2026-01-09: 0 commits2026-01-10: 0 commits2026-01-11: 0 commits2026-01-12: 2 commits2026-01-13: 0 commits2026-01-14: 0 commits2026-01-15: 2 commits2026-01-16: 0 commits2026-01-17: 0 commits2026-01-18: 0 commits2026-01-19: 0 commits2026-01-20: 0 commits2026-01-21: 0 commits2026-01-22: 0 commits2026-01-23: 0 commits2026-01-24: 0 commits2026-01-25: 0 commits2026-01-26: 0 commits2026-01-27: 0 commits2026-01-28: 0 commits2026-01-29: 0 commits2026-01-30: 0 commits2026-01-31: 0 commits2026-02-01: 0 commits2026-02-02: 0 commits2026-02-03: 0 commits2026-02-04: 0 commits2026-02-05: 0 commits2026-02-06: 0 commits2026-02-07: 0 commits2026-02-08: 0 commits2026-02-09: 0 commits2026-02-10: 0 commits2026-02-11: 0 commits2026-02-12: 0 commits2026-02-13: 0 commits2026-02-14: 0 commits2026-02-15: 0 commits2026-02-16: 0 commits2026-02-17: 0 commits2026-02-18: 0 commits2026-02-19: 0 commits2026-02-20: 0 commits2026-02-21: 0 commits2026-02-22: 0 commits2026-02-23: 0 commits2026-02-24: 0 commits2026-02-25: 0 commits2026-02-26: 0 commits2026-02-27: 0 commits2026-02-28: 0 commits2026-03-01: 0 commits2026-03-02: 0 commits2026-03-03: 0 commits2026-03-04: 0 commits2026-03-05: 0 commits2026-03-06: 0 commits2026-03-07: 0 commits2026-03-08: 0 commits2026-03-09: 0 commits2026-03-10: 0 commits2026-03-11: 0 commits2026-03-12: 0 commits2026-03-13: 0 commits2026-03-14: 0 commits2026-03-15: 0 commits2026-03-16: 1 commit2026-03-17: 0 commits2026-03-18: 0 commits2026-03-19: 0 commits2026-03-20: 0 commits2026-03-21: 0 commits2026-03-22: 0 commits2026-03-23: 0 commits2026-03-24: 0 commits2026-03-25: 0 commits2026-03-26: 0 commits2026-03-27: 2 commits2026-03-28: 1 commit2026-03-29: 0 commits2026-03-30: 0 commits2026-03-31: 0 commits2026-04-01: 0 commits2026-04-02: 0 commits2026-04-03: 0 commits2026-04-04: 0 commits2026-04-05: 0 commits2026-04-06: 0 commits2026-04-07: 0 commits2026-04-08: 0 commits2026-04-09: 0 commits2026-04-10: 0 commits2026-04-11: 0 commits2026-04-12: 0 commits2026-04-13: 0 commits2026-04-14: 0 commits2026-04-15: 0 commits2026-04-16: 0 commits2026-04-17: 0 commits2026-04-18: 0 commits2026-04-19: 0 commits2026-04-20: 0 commits2026-04-21: 0 commits2026-04-22: 0 commits2026-04-23: 0 commits2026-04-24: 0 commits2026-04-25: 0 commits2026-04-26: 0 commits2026-04-27: 0 commits2026-04-28: 0 commits2026-04-29: 0 commits2026-04-30: 0 commits2026-05-01: 0 commits2026-05-02: 0 commits2026-05-03: 0 commits2026-05-04: 0 commits2026-05-05: 0 commits2026-05-06: 0 commits2026-05-07: 0 commits2026-05-08: 0 commits2026-05-09: 0 commits2026-05-10: 0 commits2026-05-11: 0 commits2026-05-12: 0 commits2026-05-13: 0 commits2026-05-14: 0 commits2026-05-15: 0 commits2026-05-16: 0 commits2026-05-17: 0 commits2026-05-18: 0 commits2026-05-19: 0 commits2026-05-20: 0 commits2026-05-21: 0 commits2026-05-22: 0 commits2026-05-23: 0 commits2026-05-24: 0 commits2026-05-25: 0 commits2026-05-26: 0 commits2026-05-27: 0 commits2026-05-28: 0 commits2026-05-29: 0 commits2026-05-30: 0 commits2026-05-31: 0 commits2026-06-01: 0 commits2026-06-02: 0 commits2026-06-03: 0 commits2026-06-04: 0 commits2026-06-05: 0 commits2026-06-06: 0 commits2026-06-07: 0 commits2026-06-08: 0 commits2026-06-09: 0 commits2026-06-10: 0 commits2026-06-11: 0 commits2026-06-12: 0 commits2026-06-13: 0 commits2026-06-14: 0 commits2026-06-15: 0 commits2026-06-16: 0 commits2026-06-17: 0 commits2026-06-18: 0 commits2026-06-19: 0 commits2026-06-20: 0 commits2026-06-21: 0 commits2026-06-22: 0 commits2026-06-23: 0 commits2026-06-24: 0 commits2026-06-25: 0 commits2026-06-26: 0 commits2026-06-27: 0 commits2026-06-28: 0 commits2026-06-29: 0 commits2026-06-30: 0 commits2026-07-01: 0 commits2026-07-02: 0 commits2026-07-03: 0 commits2026-07-04: 0 commits2026-07-05: 0 commits2026-07-06: 0 commits2026-07-07: 0 commits2026-07-08: 0 commits2026-07-09: 0 commits2026-07-10: 0 commits2026-07-11: 0 commits2026-07-12: 0 commits2026-07-13: 1 commit2026-07-14: 0 commits2026-07-15: 0 commits2026-07-16: 0 commits2026-07-17: 0 commits2026-07-18: 0 commits2026-07-19: 0 commits2026-07-20: 0 commits2026-07-21: 0 commits2026-07-22: 0 commits2026-07-23: 0 commits2026-07-24: 0 commits2026-07-25: 0 commits2026-07-26: 0 commits2026-07-27: 0 commits2026-07-28: 0 commits2026-07-29: 0 commits2026-07-30: 0 commits2026-07-31: 0 commits2026-08-01: 0 commits2026-08-02: 0 commits2026-08-03: 0 commits2026-08-04: 0 commits2026-08-05: 0 commits2026-08-06: 0 commits2026-08-07: 0 commits2026-08-08: 0 commits2026-08-09: 1 commit2026-08-10: 0 commits2026-08-11: 0 commits2026-08-12: 0 commits2026-08-13: 0 commits2026-08-14: 0 commits2026-08-15: 0 commits2026-08-16: 0 commits2026-08-17: 0 commits2026-08-18: 0 commits2026-08-19: 0 commits2026-08-20: 0 commits2026-08-21: 0 commits2026-08-22: 0 commits2026-08-23: 0 commits2026-08-24: 0 commits2026-08-25: 0 commits2026-08-26: 0 commits2026-08-27: 0 commits2026-08-28: 0 commits2026-08-29: 0 commits2026-08-30: 0 commits2026-08-31: 0 commits2026-09-01: 0 commits2026-09-02: 0 commits2026-09-03: 0 commits2026-09-04: 0 commits2026-09-05: 0 commits2026-09-06: 0 commits2026-09-07: 0 commits2026-09-08: 3 commits2026-09-09: 0 commits2026-09-10: 0 commits2026-09-11: 0 commits2026-09-12: 0 commits2026-09-13: 0 commits2026-09-14: 0 commits2026-09-15: 2 commits2026-09-16: 0 commits2026-09-17: 0 commits2026-09-18: 0 commits2026-09-19: 0 commits2026-09-20: 0 commits2026-09-21: 0 commits2026-09-22: 0 commits2026-09-23: 4 commits2026-09-24: 0 commits2026-09-25: 0 commits2026-09-26: 0 commits2026-09-27: 0 commits2026-09-28: 0 commits2026-09-29: 1 commit2026-09-30: 0 commits2026-10-01: 0 commits2026-10-02: 0 commits2026-10-03: 0 commits2026-10-04: 0 commits2026-10-05: 0 commits2026-10-06: 0 commits2026-10-07: 0 commits2026-10-08: 0 commits2026-10-09: 0 commits2026-10-10: 0 commits2026-10-11: 0 commits2026-10-12: 0 commits2026-10-13: 0 commits2026-10-14: 4 commits2026-10-15: 9 commits2026-10-16: 0 commits2026-10-17: 0 commits2026-10-18: 0 commits2026-10-19: 0 commits2026-10-20: 0 commits2026-10-21: 0 commits2026-10-22: 0 commits2026-10-23: 0 commits2026-10-24: 0 commits2026-10-25: 0 commits2026-10-26: 0 commits2026-10-27: 0 commits2026-10-28: 0 commits2026-10-29: 0 commits2026-10-30: 0 commits2026-10-31: 0 commits2026-11-01: 2 commits2026-11-02: 0 commits2026-11-03: 0 commits2026-11-04: 0 commits2026-11-05: 0 commits2026-11-06: 0 commits2026-11-07: 0 commits2026-11-08: 0 commits2026-11-09: 0 commits2026-11-10: 0 commits2026-11-11: 0 commits2026-11-12: 0 commits2026-11-13: 0 commits2026-11-14: 0 commits
56 commits in the last yearLessMore

Signals and awards

derived from tracked data
  • Permissive license

    Apache-2.0

  • Continuous integration

    Automated checks passing

What tvscreener does

TradingView Screener API (tvscreener) is a powerful Python library designed to programmatically retrieve and analyze financial data directly from the TradingView platform. It completely circumvents the need for official, expensive API subscriptions by effectively querying the publicly accessible screener endpoints. The library supports a massive range of asset classes, allowing quantitative developers to screen global stocks, cryptocurrencies, forex pairs, and futures markets simultaneously. It provides a visual code generator that allows non-programmers to intuitively build complex screening filters in the browser and instantly export the equivalent Python code. The underlying architecture robustly handles HTTP requests and parses the raw JSON responses into clean, structured datasets ready for immediate analysis.

Quantitative analysts, algorithmic traders, and Python developers building financial tools. Familiarity with technical analysis concepts like RSI or MACD is beneficial.

  • Unofficial Screener API Access: Programmatically extracts comprehensive financial and technical indicators from TradingView without requiring a paid subscription key.
  • Multi-Asset Class Support: Capable of querying real-time and historical data across global equities, cryptocurrency exchanges, forex pairs, and bond markets.
  • Visual Code Generator: Features a web-based interface that lets users visually select filters and instantly generates the exact Python code needed to execute the query.
  • Structured Data Retrieval: Automatically parses TradingView's complex raw JSON responses into clean, easy-to-manipulate Python dictionary and list structures.
  • Custom Filtering Logic: Allows quantitative traders to define highly specific queries based on hundreds of technical indicators like moving averages and RSI.
  • Cross-Platform Python Library: Installs seamlessly via pip and integrates smoothly into existing automated trading scripts, Jupyter notebooks, or data pipelines.

Where teams use it

Automated Daily Market Screening

Retail investors can run automated scripts to find specific technical setups, like moving average crossovers, across the entire S&P 500.

Quantitative Strategy Backtesting

Algorithmic traders can download historical technical indicators for thousands of stocks to rigorously test their predictive mathematical models.

Cryptocurrency Arbitrage Detection

Traders can continuously monitor price discrepancies and volume spikes across various global crypto exchanges supported by the TradingView platform.

Building Custom Financial Dashboards

Developers can feed the structured Python output into Streamlit or Dash applications to visualize market breadth and sector performance visually.

Fundamental Analysis Aggregation

Value investors can quickly filter companies based on P/E ratios, dividend yields, and earnings growth without relying on expensive terminal software.

Getting started: pip install tvscreener

README

main branch
TradingView Screener API Logo

TradingView™ Screener API


TradingView™ Screener API: simple Python library to retrieve data from TradingView™ Screener

PyPI version Downloads Coverage

🚀 Try the Code Generator

Build screener queries visually and get Python code instantly!

Code Generator

The Code Generator lets you:

  • Select from 10 screener types (Stock, ETF, Crypto, Forex, Bond, Government Bond, Futures, Coin, Index, Economics)
  • Build filters visually with 13,000+ fields, combined with AND / OR
  • Generate ready-to-use Python code
  • Copy and run in your environment

tradingview-screener.png

Get the results as a Pandas Dataframe

dataframe.png

Disclaimer

This is an unofficial, third-party library and is not affiliated with, endorsed by, or connected to TradingView™ in any way. TradingView™ is a trademark of TradingView™, Inc. This independent project provides a Python interface to publicly available data from TradingView's screener. Use of this library is at your own risk and subject to TradingView's terms of service.

Main Features

  • Query Stock, ETF, Forex, Crypto, Bond, Government Bond, Futures, Coin, Option, Index and Economics Screeners
  • OR / nested filters with | and &, and operators such as has(), above_pct(), in_day_range()
  • TradingView presets (gainers, losers, all-time highs...) and earnings, dividend, IPO and economic calendars
  • Financial statements: about 20 years of annual and 8 years of quarterly income statement, balance sheet and cash flow
  • Real-time quotes pushed by TradingView, recent dividends, earnings and splits, and seasonals
  • News with filters, filings and earnings call transcripts
  • Yield curves and matrix, futures forward curves, IV term structure and smile, symbol search, peers and single-symbol lookups
  • All the fields available: 13,000+ fields across all screener types
  • Any time interval (no need to be a registered user - 1D, 5m, 1h, etc.)
  • Fluent API with select() and where() methods for cleaner code
  • Field discovery - search fields by name, get technicals, filter by category
  • Field presets - curated field groups for common use cases
  • Type-safe validation - catches field/screener mismatches
  • Filters by any fields, symbols, markets, countries, etc.
  • Get the results as a Pandas Dataframe
  • Styled output with TradingView-like colors and formatting
  • Streaming/Auto-update - continuously fetch data at specified intervals
  • MCP server for AI assistants: pip install tvscreener[mcp], then claude mcp add tvscreener -- tvscreener-mcp

Tip

New in 0.8: financial statements, real-time quotes, economic calendar, news, filings and earnings call transcripts, also as MCP tools. See Financials and Events and News and Filings.

Installation

The source code is currently hosted on GitHub at: https://github.com/deepentropy/tvscreener

Binary installers for the latest released version are available at the Python Package Index (PyPI)

# or PyPI
pip install tvscreener

From pip + GitHub:

$ pip install git+https://github.com/deepentropy/tvscreener.git

Usage

Basic Screeners

import tvscreener as tvs

# Stock Screener
ss = tvs.StockScreener()
df = ss.get()  # returns a dataframe with 150 rows by default

# Forex Screener
fs = tvs.ForexScreener()
df = fs.get()

# Crypto Screener
cs = tvs.CryptoScreener()
df = cs.get()

# Bond Screener (NEW)
bs = tvs.BondScreener()
df = bs.get()

# Futures Screener (NEW)
futs = tvs.FuturesScreener()
df = futs.get()

# Coin Screener (NEW) - CEX and DEX coins
coins = tvs.CoinScreener()
df = coins.get()

# Option Screener - option chains with greeks and IV (underlying required)
opts = tvs.OptionScreener("NASDAQ:AAPL")
opts.where(tvs.OptionField.DELTA.between(0.4, 0.6))
df = opts.get()

# Implied volatility term structure
df = tvs.get_iv_term_structure("NASDAQ:AAPL")

# ETF Screener - ETFs sorted by assets under management
etfs = tvs.ETFScreener()
etfs.where(tvs.StockField.EXPENSE_RATIO < 0.1)
df = etfs.get()

# Index Screener - indices, CFDs, crypto market caps
df = tvs.IndexScreener().main_indices().get()

# Economics Screener - 15,000+ economic indicators
es = tvs.EconomicsScreener()
es.where(tvs.EconomicsField.COUNTRY_CODE == 'US')
df = es.get()

# Government bond yield curve
df = tvs.get_yield_curve("US")

OR Filters and Presets

ss = tvs.StockScreener()
ss.where((tvs.StockField.SECTOR == 'Finance') | (tvs.StockField.SECTOR == 'Utilities'))
ss.where(tvs.StockField.PRICE.above_pct(tvs.StockField.SIMPLE_MOVING_AVERAGE_50, 5))
df = ss.get()

# TradingView's own screens
df = tvs.StockScreener().set_preset(tvs.Preset.GAINERS).get()

Calendars

earnings = tvs.get_earnings_calendar("2026-10-12", "2026-10-18")
dividends = tvs.get_dividends_calendar("2026-10-12", "2026-10-18")
ipos = tvs.get_ipo_calendar("2026-10-01", "2026-10-31", markets=tvs.Market.ALL)
macro = tvs.get_economic_calendar("2026-10-12", "2026-10-18", countries=["US", "EU"], importance="high")

Financials, Events and Real-Time Quotes

income = tvs.get_financials("NASDAQ:AAPL", "income", "FY")       # ~20 fiscal years
balance = tvs.get_financials("NASDAQ:AAPL", "balance_sheet", "FQ")
events = tvs.get_corporate_events("NASDAQ:AAPL")                  # dividends, earnings, splits
seasonals = tvs.get_seasonals("NASDAQ:AAPL")                      # monthly returns by year

for quote in tvs.stream_quotes(["NASDAQ:AAPL", "BINANCE:BTCUSDT"], duration=60):
    print(quote["symbol"], quote.get("price"))

News, Filings and Market Helpers

news = tvs.get_news("NASDAQ:AAPL", corp_activity="insider_trading")
text = tvs.get_article(news["id"].iloc[0])
docs = tvs.get_documents("NASDAQ:AAPL", category="call_transcript")
transcript = tvs.get_document(docs["transcript_id"].iloc[0])

tvs.search_symbols("US0378331005")             # ISIN -> NASDAQ:AAPL and other listings
tvs.get_peers("NASDAQ:AAPL")
tvs.get_forward_curve("NYMEX:CL")
tvs.get_yield_matrix(["US", "DE", "JP"])
tvs.get_volatility_smile("NASDAQ:AAPL", "2026-11-13")

Fluent API

Use select() and where() for cleaner, chainable code:

from tvscreener import StockScreener, StockField

ss = StockScreener()
ss.select(
    StockField.NAME,
    StockField.PRICE,
    StockField.CHANGE_PERCENT,
    StockField.VOLUME,
    StockField.MARKET_CAPITALIZATION
)
ss.where(StockField.MARKET_CAPITALIZATION > 1e9)
ss.where(StockField.CHANGE_PERCENT > 5)
df = ss.get()

Field Discovery

Search and explore the 13,000+ available fields:

from tvscreener import StockField

# Search fields by name or label
rsi_fields = StockField.search("rsi")
print(f"Found {len(rsi_fields)} RSI-related fields")

# Get all technical indicator fields
technicals = StockField.technicals()
print(f"Found {len(technicals)} technical fields")

# Get recommendation fields
recommendations = StockField.recommendations()

Field Presets

Use curated field groups for common analysis needs:

from tvscreener import (
    StockScreener, get_preset, list_presets,
    STOCK_PRICE_FIELDS, STOCK_VALUATION_FIELDS, STOCK_DIVIDEND_FIELDS,
    STOCK_PERFORMANCE_FIELDS, STOCK_OSCILLATOR_FIELDS
)

# See all available presets
print(list_presets())
# ['stock_price', 'stock_volume', 'stock_valuation', 'stock_dividend', ...]

# Use presets directly
ss = StockScreener()
ss.specific_fields = STOCK_VALUATION_FIELDS + STOCK_DIVIDEND_FIELDS
df = ss.get()

# Or get preset by name
fields = get_preset('stock_performance')

Available Presets:

Category Presets
Stock stock_price, stock_volume, stock_valuation, stock_dividend, stock_profitability, stock_performance, stock_oscillators, stock_moving_averages, stock_earnings
Crypto crypto_price, crypto_volume, crypto_performance, crypto_technical
Forex forex_price, forex_performance, forex_technical
Bond bond_basic, bond_yield, bond_maturity
Futures futures_price, futures_technical
Coin coin_price, coin_market

Time Intervals for Technical Fields

Apply different time intervals to technical indicators:

from tvscreener import StockScreener, StockField

ss = StockScreener()

# Get RSI with 1-hour interval
rsi_1h = StockField.RELATIVE_STRENGTH_INDEX_14.with_interval("60")

# Available intervals: 1, 5, 15, 30, 60, 120, 240, 1D, 1W, 1M
ss.specific_fields = [
    StockField.NAME,
    StockField.PRICE,
    rsi_1h,
    StockField.MACD_LEVEL_12_26.with_interval("240"),  # 4-hour MACD
]
df = ss.get()

Parameters

For detailed usage examples, see the documentation and notebooks below.

Styled Output

You can apply TradingView-style formatting to your screener results using the beautify function. This adds colored text for ratings and percent changes, formatted numbers with K/M/B suffixes, and visual indicators for buy/sell/neutral recommendations.

import tvscreener as tvs

# Get raw data
ss = tvs.StockScreener()
df = ss.get()

# Apply TradingView styling
styled = tvs.beautify(df, tvs.StockField)

# Display in Jupyter/IPython (shows colored output)
styled

The styled output includes:

  • Rating columns with colored text and directional arrows:
    • Buy signals: Blue color with up arrow (↑)
    • Sell signals: Red color with down arrow (↓)
    • Neutral: Gray color with dash (-)
  • Percent change columns: Green for positive, Red for negative
  • Number formatting: K, M, B, T suffixes for large numbers
  • Missing values: Displayed as "--"

Streaming / Auto-Update

You can use the stream() method to continuously fetch screener data at specified intervals. This is useful for monitoring real-time market data.

import tvscreener as tvs

# Basic streaming with iteration limit
ss = tvs.StockScreener()
for df in ss.stream(interval=10, max_iterations=5):
    print(f"Got {len(df)} rows")

# Streaming with callback
from datetime import datetime

def on_update(df):
    print(f"Updated at {datetime.now()}: {len(df)} rows")

ss = tvs.StockScreener()
try:
    for df in ss.stream(interval=5, on_update=on_update):
        # Process data
        pass
except KeyboardInterrupt:
    print("Stopped streaming")

# Stream with filters
ss = tvs.StockScreener()
ss.set_markets(tvs.Market.AMERICA)
for df in ss.stream(interval=30, max_iterations=10):
    print(df.head())

Parameters:

  • interval: Refresh interval in seconds (minimum 1.0 to avoid rate limiting)
  • max_iterations: Maximum number of refreshes (None = infinite)
  • on_update: Optional callback function called with each DataFrame

Documentation

📖 Full Documentation - Complete guides, API reference, and examples.

Quick Links

Guide Description
Quick Start Get up and running in 5 minutes
Filtering Complete filtering reference
Stock Screening Value, momentum, dividend strategies
Technical Analysis RSI, MACD, multi-timeframe
Financials and Events Statements, dividends, earnings, seasonals
News and Filings Filtered news, 10-Q/10-K, call transcripts
Streaming Screener refreshes and real-time quotes
API Reference Screeners, Fields, Enums

Jupyter Notebooks

Interactive examples organized by use case:

Notebook Description
01-quickstart.ipynb Overview of all 6 screeners
02-stocks.ipynb Stock screening strategies
03-crypto.ipynb Crypto analysis
04-forex.ipynb Forex pairs screening
05-bonds-futures.ipynb Bonds and futures
View on GitHub

Recent activity

commits and pull requests

Releases and announcements

19 total
  1. v0.8.2v0.8.2Nov 1, 2026

    ## Fixed - `get_financials` no longer crashes with `RecursionError` or drops items (#74). It now uses the company's own layout, as reported by TradingView (`fund_view_mode`). Before, many balance sheets (e.g. NVDA, KO, XOM) selected the `other` layout, which lists an item as its own parent. - `get_financials` no longer returns an empty result without explanation (#73): - `balance_sheet` with `TTM` raises `ValueError`, because TradingView has no such fields. - When a company has no data for the statement and period, a warning is issued. - TradingView keeps a `TTM` history for a few items only, and for no statistics: this is now documented.

  2. v0.8.1v0.8.1Oct 15, 2026

    ## MCP server - **12 new tools** for the 0.8.0 features: - `financials`, `corporate_events`, `seasonals`, `quotes` - `news`, `company_documents`, `earnings_calls`, `read_text` - `find_symbols`, `peers`, `forward_curve`, `volatility_smile` - `get_calendar` accepts `kind="economic"`, with `countries` and `importance`. - `yield_curve` accepts several countries (or `ALL`) and `tenors`, and then returns a matrix. The server now has 24 tools. ## Fixed - `custom_query` no longer ignores invalid input. It now returns an error for: - unknown filter keys (e.g. `operator` instead of `op`), fields, operators, `sort_by` fields and asset types; - a missing `op` or `value`. Before, a misspelled key quietly became `>=`, and unknown parts were dropped, which gave plausible but wrong results. - `discover_fields` and `list_field_types` reject an unknown asset type instead of falling back to stocks.

  3. v0.8.0v0.8.0Oct 15, 2026

    ## Highlights tvscreener now reads the data behind TradingView's symbol pages, charts and calendars. No account needed. - **Financial statements**: `get_financials("NASDAQ:AAPL", "income", "FY")`. Income statement, balance sheet, cash flow and statistics by fiscal year, quarter, half-year or TTM. About 20 years and 32 quarters for large companies, in TradingView's layout (industrial, bank, insurer). - **Real-time quotes**: `stream_quotes(["NASDAQ:AAPL", "BINANCE:BTCUSDT"])` yields each change pushed by TradingView, including pre/after-market prices. `update_mode` shows delayed exchanges. - **Corporate events and seasonals**: `get_corporate_events()` returns recent dividends, earnings vs estimates and splits. `get_seasonals()` returns monthly returns by year. - **Economic calendar**: `get_economic_calendar(start, end, countries, importance)` with actual, forecast and previous values. - **Filings and transcripts**: `get_documents()` lists 10-Q/10-K, earnings releases and transcripts. `get_document()` returns transcript or summary text. `get_earnings_calls()` returns call dates with transcript and audio links. - **News**: `get_news()` filters by provider, market, sector, corporate a

  4. v0.7.0v0.7.0Oct 15, 2026

    ## Highlights - **OR and nested filters** (#62): `ss.where((StockField.SECTOR == 'Finance') | (StockField.SECTOR == 'Utilities'))` - **New filter operations** (#63): `has()`, `has_none_of()`, `is_empty()`, `not_empty()`, `in_day_range()`, `above_pct()`, `below_pct()`, `within_pct()`, `not_within_pct()`, `match()` - **4 new screeners**: - `ETFScreener` (#69): ETFs and ETNs sorted by AUM, with readable classification fields (`ASSET_CLASS_NAME`, `FOCUS_NAME`...) - `EconomicsScreener` (#66): 15,000+ economic indicators by country and category - `IndexScreener` (#67): stock indices, CFDs and crypto market-cap indices - `GovernmentBondScreener` and `get_yield_curve("US")` (#68) - **Presets and calendars** (#70): `StockScreener().set_preset(Preset.GAINERS)`, `get_earnings_calendar()`, `get_dividends_calendar()`, `get_ipo_calendar()` - **`set_currency("eur")`** (#71): fundamentals in one currency - **Scanner helpers** (#72): `get_symbol()`, `get_enum_values()`, `get_metainfo()` / `Screener.metainfo()` ## Fields (#64) The field enums were regenerated from TradingView's field catalogue by `scripts/generate_fields.py`. A field is only added when it returns data on real symbols. -

  5. v0.6.0v0.6.0Oct 14, 2026

    ## Added - **`OptionScreener` and `OptionField`** (#53): option chains from the TradingView options scanner, for one or more underlyings. - Greeks (delta, gamma, theta, vega, rho), implied volatility (mid, bid, ask), theoretical price, bid/ask - Expiration is returned as a datetime; expiration filters accept dates, ISO strings or `YYYYMMDD` integers - Works for US equities and ETFs (`NASDAQ:AAPL`, `AMEX:SPY`), indices (`SP:SPX`) and `NSE:NIFTY` - **`get_iv_term_structure(symbol)`** (#53): implied volatility by time to expiration, one point per listed expiration plus standard tenors (1w to 1y). ```python import tvscreener as tvs opts = tvs.OptionScreener("NASDAQ:AAPL") opts.where(tvs.OptionField.OPTION_TYPE == "call") opts.where(tvs.OptionField.DELTA.between(0.4, 0.6)) df = opts.get() ts = tvs.get_iv_term_structure("NASDAQ:AAPL") ``` Notes: implied volatilities are fractions (0.27 = 27%). The options scanner does not return last price, volume or open interest. See the [Option Screener docs](https://deepentropy.github.io/tvscreener/screeners/option/). Full suite: 168 tests and 2 subtests passed.

Code frequency

additions and deletions
+351.7K-351.7KWeek of 2025-11-16: +0 linesWeek of 2025-11-16: -0 linesWeek of 2025-11-23: +94,112 linesWeek of 2025-11-23: -46,417 linesWeek of 2025-11-30: +0 linesWeek of 2025-11-30: -0 linesWeek of 2025-12-07: +351,741 linesWeek of 2025-12-07: -260,169 linesWeek of 2025-12-14: +0 linesWeek of 2025-12-14: -0 linesWeek of 2025-12-21: +0 linesWeek of 2025-12-21: -0 linesWeek of 2025-12-28: +0 linesWeek of 2025-12-28: -0 linesWeek of 2026-01-04: +147 linesWeek of 2026-01-04: -340 linesWeek of 2026-01-11: +933 linesWeek of 2026-01-11: -81 linesWeek of 2026-01-18: +0 linesWeek of 2026-01-18: -0 linesWeek of 2026-01-25: +0 linesWeek of 2026-01-25: -0 linesWeek of 2026-02-01: +0 linesWeek of 2026-02-01: -0 linesWeek of 2026-02-08: +0 linesWeek of 2026-02-08: -0 linesWeek of 2026-02-15: +0 linesWeek of 2026-02-15: -0 linesWeek of 2026-02-22: +0 linesWeek of 2026-02-22: -0 linesWeek of 2026-03-01: +0 linesWeek of 2026-03-01: -0 linesWeek of 2026-03-08: +0 linesWeek of 2026-03-08: -0 linesWeek of 2026-03-15: +55 linesWeek of 2026-03-15: -30 linesWeek of 2026-03-22: +167 linesWeek of 2026-03-22: -2 linesWeek of 2026-03-29: +0 linesWeek of 2026-03-29: -0 linesWeek of 2026-04-05: +0 linesWeek of 2026-04-05: -0 linesWeek of 2026-04-12: +0 linesWeek of 2026-04-12: -0 linesWeek of 2026-04-19: +0 linesWeek of 2026-04-19: -0 linesWeek of 2026-04-26: +0 linesWeek of 2026-04-26: -0 linesWeek of 2026-05-03: +0 linesWeek of 2026-05-03: -0 linesWeek of 2026-05-10: +0 linesWeek of 2026-05-10: -0 linesWeek of 2026-05-17: +0 linesWeek of 2026-05-17: -0 linesWeek of 2026-05-24: +0 linesWeek of 2026-05-24: -0 linesWeek of 2026-05-31: +0 linesWeek of 2026-05-31: -0 linesWeek of 2026-06-07: +0 linesWeek of 2026-06-07: -0 linesWeek of 2026-06-14: +0 linesWeek of 2026-06-14: -0 linesWeek of 2026-06-21: +0 linesWeek of 2026-06-21: -0 linesWeek of 2026-06-28: +0 linesWeek of 2026-06-28: -0 linesWeek of 2026-07-05: +0 linesWeek of 2026-07-05: -0 linesWeek of 2026-07-12: +25 linesWeek of 2026-07-12: -6 linesWeek of 2026-07-19: +0 linesWeek of 2026-07-19: -0 linesWeek of 2026-07-26: +0 linesWeek of 2026-07-26: -0 linesWeek of 2026-08-02: +0 linesWeek of 2026-08-02: -0 linesWeek of 2026-08-09: +18 linesWeek of 2026-08-09: -0 linesWeek of 2026-08-16: +0 linesWeek of 2026-08-16: -0 linesWeek of 2026-08-23: +0 linesWeek of 2026-08-23: -0 linesWeek of 2026-08-30: +0 linesWeek of 2026-08-30: -0 linesWeek of 2026-09-06: +203 linesWeek of 2026-09-06: -13 linesWeek of 2026-09-13: +72 linesWeek of 2026-09-13: -2 linesWeek of 2026-09-20: +11,592 linesWeek of 2026-09-20: -10,274 linesWeek of 2026-09-27: +6,894 linesWeek of 2026-09-27: -0 linesWeek of 2026-10-04: +0 linesWeek of 2026-10-04: -0 linesWeek of 2026-10-11: +55,433 linesWeek of 2026-10-11: -44,723 linesWeek of 2026-10-18: +0 linesWeek of 2026-10-18: -0 linesWeek of 2026-10-25: +0 linesWeek of 2026-10-25: -0 linesWeek of 2026-11-01: +114 linesWeek of 2026-11-01: -13 linesWeek of 2026-11-08: +0 linesWeek of 2026-11-08: -0 linesNov 16, 2025Nov 8, 2026
+521.5K lines added, -362.1K removed over the last year.

Commits per week

last 52 weeks
130Week of 2025-11-16: 0 commitsWeek of 2025-11-23: 9 commitsWeek of 2025-11-30: 0 commitsWeek of 2025-12-07: 11 commitsWeek of 2025-12-14: 0 commitsWeek of 2025-12-21: 0 commitsWeek of 2025-12-28: 0 commitsWeek of 2026-01-04: 1 commitsWeek of 2026-01-11: 4 commitsWeek of 2026-01-18: 0 commitsWeek of 2026-01-25: 0 commitsWeek of 2026-02-01: 0 commitsWeek of 2026-02-08: 0 commitsWeek of 2026-02-15: 0 commitsWeek of 2026-02-22: 0 commitsWeek of 2026-03-01: 0 commitsWeek of 2026-03-08: 0 commitsWeek of 2026-03-15: 1 commitsWeek of 2026-03-22: 3 commitsWeek of 2026-03-29: 0 commitsWeek of 2026-04-05: 0 commitsWeek of 2026-04-12: 0 commitsWeek of 2026-04-19: 0 commitsWeek of 2026-04-26: 0 commitsWeek of 2026-05-03: 0 commitsWeek of 2026-05-10: 0 commitsWeek of 2026-05-17: 0 commitsWeek of 2026-05-24: 0 commitsWeek of 2026-05-31: 0 commitsWeek of 2026-06-07: 0 commitsWeek of 2026-06-14: 0 commitsWeek of 2026-06-21: 0 commitsWeek of 2026-06-28: 0 commitsWeek of 2026-07-05: 0 commitsWeek of 2026-07-12: 1 commitsWeek of 2026-07-19: 0 commitsWeek of 2026-07-26: 0 commitsWeek of 2026-08-02: 0 commitsWeek of 2026-08-09: 1 commitsWeek of 2026-08-16: 0 commitsWeek of 2026-08-23: 0 commitsWeek of 2026-08-30: 0 commitsWeek of 2026-09-06: 3 commitsWeek of 2026-09-13: 2 commitsWeek of 2026-09-20: 4 commitsWeek of 2026-09-27: 1 commitsWeek of 2026-10-04: 0 commitsWeek of 2026-10-11: 13 commitsWeek of 2026-10-18: 0 commitsWeek of 2026-10-25: 0 commitsWeek of 2026-11-01: 2 commitsWeek of 2026-11-08: 0 commitsNov 16, 2025Nov 8, 2026
56 commits in the last 52 weeks.

When work happens

weekday and hour
SunMonTueWedThuFriSat036912151821Sun 0:00 — 0 commitsSun 1:00 — 0 commitsSun 2:00 — 0 commitsSun 3:00 — 0 commitsSun 4:00 — 0 commitsSun 5:00 — 0 commitsSun 6:00 — 0 commitsSun 7:00 — 0 commitsSun 8:00 — 0 commitsSun 9:00 — 0 commitsSun 10:00 — 0 commitsSun 11:00 — 0 commitsSun 12:00 — 0 commitsSun 13:00 — 0 commitsSun 14:00 — 1 commitsSun 15:00 — 0 commitsSun 16:00 — 0 commitsSun 17:00 — 0 commitsSun 18:00 — 1 commitsSun 19:00 — 0 commitsSun 20:00 — 2 commitsSun 21:00 — 1 commitsSun 22:00 — 0 commitsSun 23:00 — 0 commitsMon 0:00 — 0 commitsMon 1:00 — 0 commitsMon 2:00 — 0 commitsMon 3:00 — 0 commitsMon 4:00 — 0 commitsMon 5:00 — 0 commitsMon 6:00 — 0 commitsMon 7:00 — 0 commitsMon 8:00 — 1 commitsMon 9:00 — 2 commitsMon 10:00 — 0 commitsMon 11:00 — 0 commitsMon 12:00 — 0 commitsMon 13:00 — 0 commitsMon 14:00 — 0 commitsMon 15:00 — 4 commitsMon 16:00 — 3 commitsMon 17:00 — 4 commitsMon 18:00 — 3 commitsMon 19:00 — 0 commitsMon 20:00 — 3 commitsMon 21:00 — 1 commitsMon 22:00 — 0 commitsMon 23:00 — 2 commitsTue 0:00 — 0 commitsTue 1:00 — 0 commitsTue 2:00 — 0 commitsTue 3:00 — 0 commitsTue 4:00 — 0 commitsTue 5:00 — 0 commitsTue 6:00 — 0 commitsTue 7:00 — 0 commitsTue 8:00 — 2 commitsTue 9:00 — 1 commitsTue 10:00 — 3 commitsTue 11:00 — 1 commitsTue 12:00 — 0 commitsTue 13:00 — 0 commitsTue 14:00 — 0 commitsTue 15:00 — 0 commitsTue 16:00 — 0 commitsTue 17:00 — 2 commitsTue 18:00 — 0 commitsTue 19:00 — 0 commitsTue 20:00 — 2 commitsTue 21:00 — 0 commitsTue 22:00 — 0 commitsTue 23:00 — 1 commitsWed 0:00 — 0 commitsWed 1:00 — 0 commitsWed 2:00 — 0 commitsWed 3:00 — 0 commitsWed 4:00 — 0 commitsWed 5:00 — 0 commitsWed 6:00 — 0 commitsWed 7:00 — 0 commitsWed 8:00 — 0 commitsWed 9:00 — 2 commitsWed 10:00 — 0 commitsWed 11:00 — 1 commitsWed 12:00 — 3 commitsWed 13:00 — 7 commitsWed 14:00 — 9 commitsWed 15:00 — 18 commitsWed 16:00 — 7 commitsWed 17:00 — 10 commitsWed 18:00 — 5 commitsWed 19:00 — 0 commitsWed 20:00 — 0 commitsWed 21:00 — 3 commitsWed 22:00 — 7 commitsWed 23:00 — 4 commitsThu 0:00 — 0 commitsThu 1:00 — 0 commitsThu 2:00 — 0 commitsThu 3:00 — 0 commitsThu 4:00 — 0 commitsThu 5:00 — 0 commitsThu 6:00 — 0 commitsThu 7:00 — 0 commitsThu 8:00 — 4 commitsThu 9:00 — 6 commitsThu 10:00 — 5 commitsThu 11:00 — 1 commitsThu 12:00 — 0 commitsThu 13:00 — 0 commitsThu 14:00 — 2 commitsThu 15:00 — 1 commitsThu 16:00 — 0 commitsThu 17:00 — 0 commitsThu 18:00 — 0 commitsThu 19:00 — 0 commitsThu 20:00 — 0 commitsThu 21:00 — 1 commitsThu 22:00 — 2 commitsThu 23:00 — 0 commitsFri 0:00 — 0 commitsFri 1:00 — 0 commitsFri 2:00 — 0 commitsFri 3:00 — 0 commitsFri 4:00 — 0 commitsFri 5:00 — 0 commitsFri 6:00 — 0 commitsFri 7:00 — 0 commitsFri 8:00 — 1 commitsFri 9:00 — 1 commitsFri 10:00 — 2 commitsFri 11:00 — 0 commitsFri 12:00 — 3 commitsFri 13:00 — 3 commitsFri 14:00 — 2 commitsFri 15:00 — 3 commitsFri 16:00 — 5 commitsFri 17:00 — 0 commitsFri 18:00 — 0 commitsFri 19:00 — 0 commitsFri 20:00 — 1 commitsFri 21:00 — 0 commitsFri 22:00 — 0 commitsFri 23:00 — 0 commitsSat 0:00 — 0 commitsSat 1:00 — 0 commitsSat 2:00 — 0 commitsSat 3:00 — 0 commitsSat 4:00 — 0 commitsSat 5:00 — 0 commitsSat 6:00 — 0 commitsSat 7:00 — 0 commitsSat 8:00 — 0 commitsSat 9:00 — 0 commitsSat 10:00 — 0 commitsSat 11:00 — 0 commitsSat 12:00 — 0 commitsSat 13:00 — 6 commitsSat 14:00 — 3 commitsSat 15:00 — 0 commitsSat 16:00 — 0 commitsSat 17:00 — 0 commitsSat 18:00 — 0 commitsSat 19:00 — 0 commitsSat 20:00 — 4 commitsSat 21:00 — 0 commitsSat 22:00 — 0 commitsSat 23:00 — 2 commits
Commit volume by weekday and hour (UTC). Larger dots mean more commits.

Who is committing

last 52 weeks
Maintainer commits11 (15%)
Community commits60 (85%)

71 commits in total over the last year.

DateListRankStars gained
Feb 9, 2026daily#23+141
  • affaan-m/ECC

    The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

    307.9K stars · JavaScript

  • react/react

    The library for web and native user interfaces.

    252.8K stars · JavaScript

  • DietrichGebert/ponytail

    Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

    195.7K stars · JavaScript

  • vercel/next.js

    The React Framework

    143.6K stars · JavaScript

  • addyosmani/agent-skills

    Production-grade engineering skills for AI coding agents.

    119.4K stars · JavaScript

  • Leonxlnx/taste-skill

    Agent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages

    119.4K stars · JavaScript