Screener

Overview

The Screener module screens financial instruments across 18 markets (stocks, crypto, forex, bonds, futures, CFDs) using the TradingView scanner API with custom filters, sorting, and field selection.

Quick Start

from tv_scraper.scrapers.screening import Screener

screener = Screener()

# Basic US stock screen
result = screener.get_screener(market="america", limit=10)

# Screen with filters and sorting
result = screener.get_screener(
    market="america",
    filters=[
        {"left": "close", "operation": "greater", "right": 100},
        {"left": "volume", "operation": "greater", "right": 1000000},
    ],
    sort_by="volume",
    sort_order="desc",
    limit=20,
)

for stock in result["data"]:
    print(f"{stock['symbol']}: ${stock['close']} - Vol: {stock['volume']}")

API Reference

Constructor

Screener(
    export_result: bool = False,
    export_type: str = "json",
    timeout: int = 10,
)

Parameter	Type	Default	Description
export_result	bool	False	Whether to export results to file.
export_type	str	"json"	Export format: "json" or "csv".
timeout	int	10	HTTP timeout in seconds.

get_screener() Method

get_screener(
    market: str = "america",
    filters: Optional[List[Dict[str, Any]]] = None,
    fields: Optional[List[str]] = None,
    sort_by: Optional[str] = None,
    sort_order: str = "desc",
    limit: int = 50,
) -> Dict[str, Any]

Parameter	Type	Default	Description
market	str	"america"	Market to screen.
filters	List[Dict] or None	None	Filter conditions.
fields	List[str] or None	None	Columns to retrieve (market defaults).
sort_by	str or None	None	Field to sort by.
sort_order	str	"desc"	Sort direction: "asc" or "desc".
limit	int	50	Maximum number of results.

Response Format

All responses use the standardized envelope:

{
    "status": "success",
    "data": [
        {
            "symbol": "NASDAQ:AAPL",
            "name": "Apple Inc.",
            "close": 150.25,
            "change": 2.512,
            "change_abs": 3.68,
            "volume": 54231000,
            "market_cap_basic": 2500000000000.0,
            "price_earnings_ttm": 28.5,
            "earnings_per_share_basic_ttm": 5.2,
            "sector": "Electronic Technology"
        },
        {
            "symbol": "NYSE:TSLA",
            "name": "Tesla, Inc.",
            "close": 210.5,
            "change": 1.15,
            "change_abs": 2.4,
            "volume": 85000000,
            "market_cap_basic": 600000000000.0,
            "price_earnings_ttm": 65.2,
            "earnings_per_share_basic_ttm": 3.2,
            "sector": "Consumer Durables"
        }
    ],
    "metadata": {
        "market": "america",
        "total": 2,
        "total_available": 1500
    },
    "error": null
}

Supported Markets

Key	Description
america	US Stocks
australia	Australian Stocks
canada	Canadian Stocks
germany	German Stocks
india	Indian Stocks
israel	Israeli Stocks
italy	Italian Stocks
luxembourg	Luxembourg Stocks
mexico	Mexican Stocks
spain	Spanish Stocks
turkey	Turkish Stocks
uk	UK Stocks
crypto	Cryptocurrencies
forex	Forex Pairs
cfd	CFDs
futures	Futures
bonds	Bonds
global	Global Markets

Filter Operations

Operation	Description	Example
greater	Greater than	{"left": "close", "operation": "greater", "right": 100}
less	Less than	{"left": "close", "operation": "less", "right": 50}
egreater	Equal or greater	{"left": "volume", "operation": "egreater", "right": 1e6}
eless	Equal or less	{"left": "pe", "operation": "eless", "right": 20}
equal	Equal to	{"left": "change", "operation": "equal", "right": 0}
nequal	Not equal	{"left": "change", "operation": "nequal", "right": 0}
in_range	Within range	{"left": "close", "operation": "in_range", "right": [50, 200]}
not_in_range	Outside range	{"left": "close", "operation": "not_in_range", "right": [10, 50]}
above	Above value	{"left": "close", "operation": "above", "right": 150}
below	Below value	{"left": "close", "operation": "below", "right": 50}
crosses	Crosses value	{"left": "close", "operation": "crosses", "right": 100}
crosses_above	Crosses above	{"left": "close", "operation": "crosses_above", "right": 200}
crosses_below	Crosses below	{"left": "close", "operation": "crosses_below", "right": 50}
has	Contains value	{"left": "name", "operation": "has", "right": "Apple"}
has_none_of	Contains none of	{"left": "name", "operation": "has_none_of", "right": ["Bank"]}

Default Fields by Market

Stock markets (america, uk, etc.): name, close, change, change_abs, volume, Recommend.All, market_cap_basic, price_earnings_ttm, earnings_per_share_basic_ttm

Crypto: name, close, change, change_abs, volume, market_cap_calc, Recommend.All

Forex: name, close, change, change_abs, Recommend.All

Examples

Crypto Screening

result = screener.get_screener(
    market="crypto",
    filters=[{"left": "market_cap_calc", "operation": "greater", "right": 1e9}],
    fields=["name", "close", "market_cap_calc", "change"],
    limit=50,
)

Range Filtering

result = screener.get_screener(
    market="america",
    filters=[{"left": "close", "operation": "in_range", "right": [50, 200]}],
    sort_by="close",
    sort_order="asc",
)

Export to CSV

screener = Screener(export_result=True, export_type="csv")
result = screener.get_screener(
    market="america",
    fields=["name", "close", "volume", "market_cap_basic"],
    limit=30,
)
# File saved automatically