Getting Started

This guide covers installation, basic usage, response format, export options, and error handling for tv-scraper.

Installation

Using pip

pip install tv-scraper

Using uv

uv add tv-scraper

Development Installation

git clone https://github.com/smitkunpara/tv-scraper.git
cd tv-scraper
uv sync --extra dev

Basic Usage

Market Data

from tv_scraper import Technicals, Overview, Fundamentals, Markets

# Technical indicators
tech = Technicals()
result = tech.get_technicals(exchange="NASDAQ", symbol="AAPL")
print(result["data"])  # {"RSI": 65.5, "MACD.macd": 1.23, ...}

# Symbol overview
overview = Overview()
result = overview.get_overview(exchange="NASDAQ", symbol="AAPL")
print(result["data"])

# Fundamental data
fundamentals = Fundamentals()
result = fundamentals.get_fundamentals(exchange="NASDAQ", symbol="AAPL")
print(result["data"])

# Market listings (top stocks by market cap)
markets = Markets()
result = markets.get_markets(market="america")
print(result["data"])

Social

from tv_scraper import Ideas, Minds, News

# Trading ideas
ideas = Ideas()
result = ideas.get_ideas(exchange="CRYPTO", symbol="BTCUSD")
for idea in result["data"]:
    print(idea["title"], idea["author"])

# Minds discussions
minds = Minds()
result = minds.get_minds(exchange="NASDAQ", symbol="AAPL")
print(result["data"])

# News
news = News()
result = news.get_news_headlines(exchange="NASDAQ", symbol="AAPL")
for article in result["data"]:
    print(article["title"])

Screening

from tv_scraper import Screener, MarketMovers, SymbolMarkets

# Stock screener
screener = Screener()
result = screener.get_screener(market="america")
print(result["data"])

# Market movers
movers = MarketMovers()
result = movers.get_market_movers(market="stocks-usa", category="gainers")
print(result["data"])

# Find all exchanges for a symbol
sym_markets = SymbolMarkets()
result = sym_markets.get_markets(symbol="AAPL")
print(result["data"])

Events

from tv_scraper import Calendar

calendar = Calendar()
result = calendar.get_dividends(markets=["america"])
print(result["data"])

Streaming

from tv_scraper import Streamer

# Get historical candles with indicators (with optional cookies for auth)
streamer = Streamer(cookie="<TRADINGVIEW_COOKIE>")
result = streamer.get_candles(
    exchange="BINANCE",
    symbol="BTCUSDT",
    indicators=[("STD;RSI", "21.0")]  # (script_id, version) tuples
)

# Real-time price streaming
for tick in streamer.stream_realtime_price(exchange="BINANCE", symbol="BTCUSDT"):
    print(tick["price"])

Response Format

All scraper methods return a standardized response envelope:

{
    "status": "success",   # "success" or "failed"
    "data": { ... },       # the response payload (dict, list, etc.)
    "metadata": {          # contextual information
        "symbol": "AAPL",
        "exchange": "NASDAQ"
    },
    "error": None          # error string if status == "failed", else None
}

Checking for Errors

result = tech.get_technicals(exchange="NASDAQ", symbol="AAPL")

if result["status"] == "success":
    data = result["data"]
    # process data
else:
    print(f"Error: {result['error']}")

Export Options

All scrapers support automatic export to JSON or CSV:

# Export to JSON
tech = Technicals(export_result=True, export_type="json")
result = tech.get_technicals(exchange="NASDAQ", symbol="AAPL")
# File saved to export/ directory

# Export to CSV
tech = Technicals(export_result=True, export_type="csv")
result = tech.get_technicals(exchange="NASDAQ", symbol="AAPL")

Supported export types: - "json" — saves as a .json file - "csv" — saves as a .csv file

Invalid export types raise a ValueError at construction time:

try:
    tech = Technicals(export_type="xml")  # ValueError!
except ValueError as e:
    print(e)

Error Handling

Scrapers never raise exceptions for data errors. Instead, they return an error response:

result = tech.get_technicals(exchange="INVALID", symbol="AAPL")
# {
#     "status": "failed",
#     "data": None,
#     "metadata": {"exchange": "INVALID", "symbol": "AAPL"},
#     "error": "Invalid exchange: 'INVALID'. ..."
# }

Only construction-time validation (like invalid export_type) raises exceptions.

Exception Types

For advanced usage, the exception hierarchy is available in tv_scraper.core.exceptions:

from tv_scraper.core import (
    TvScraperError,     # Base exception
    ValidationError,    # Invalid parameters
    DataNotFoundError,  # Requested data not found
    NetworkError,       # HTTP/WebSocket failures
    ExportError,        # File export failures
)