Market Movers

Overview

The MarketMovers scraper retrieves top gainers, losers, most-active instruments, penny stocks, and pre-market / after-hours movers from TradingView's scanner API.

Quick Start

from tv_scraper.scrapers.screening import MarketMovers

movers = MarketMovers()
result = movers.get_market_movers(market="stocks-usa", category="gainers", limit=20)

for stock in result["data"]:
    print(f"{stock['symbol']}: {stock['change']}%")

API Reference

Constructor

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

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

`get_market_movers()`

get_market_movers(
    market: str = "stocks-usa",
    category: str = "gainers",
    fields: Optional[List[str]] = None,
    limit: int = 50,
) -> Dict[str, Any]

Parameter	Type	Default	Description
`market`	`str`	`"stocks-usa"`	Market to query (see supported list).
`category`	`str`	`"gainers"`	Movers category (see supported list).
`fields`	`List[str]\|None`	`None`	Columns to retrieve; `None` = defaults.
`limit`	`int`	`50`	Maximum number of results.

Supported Markets

stocks-usa, stocks-uk, stocks-india, stocks-australia, stocks-canada, crypto, forex, bonds, futures.

Supported Categories

Stock markets: gainers, losers, most-active, penny-stocks, pre-market-gainers, pre-market-losers, after-hours-gainers, after-hours-losers.

Non-stock markets: gainers, losers, most-active.

Default Fields

name, close, change, change_abs, volume, market_cap_basic, price_earnings_ttm, earnings_per_share_basic_ttm, logoid, description.

Response Format

All responses follow the standard envelope:

{
    "status": "success",          # or "failed"
    "data": [                     # list of dicts, or None on failure
        {
            "symbol": "NASDAQ:AAPL",
            "name": "Apple Inc.",
            "close": 190.5,
            "change": 3.2,
            ...
        }
    ],
    "metadata": {
        "market": "stocks-usa",
        "category": "gainers",
        "total": 20,
    },
    "error": None,                # error message string on failure
}

Examples

Losers and Most Active

movers = MarketMovers()

losers = movers.get_market_movers(category="losers", limit=10)
active = movers.get_market_movers(category="most-active", limit=10)

Pre-Market / After-Hours

pre_gainers = movers.get_market_movers(category="pre-market-gainers")
ah_losers   = movers.get_market_movers(category="after-hours-losers")

Custom Fields

result = movers.get_market_movers(
    fields=["name", "close", "change", "volume"],
    limit=5,
)

Multiple Markets

for mkt in ["stocks-usa", "crypto", "forex"]:
    r = movers.get_market_movers(market=mkt, category="gainers", limit=5)
    print(f"{mkt}: {len(r['data'])} results")

Export to CSV

movers = MarketMovers(export_result=True, export_type="csv")
movers.get_market_movers(market="stocks-usa", category="gainers")
# File saved to export/ directory