tv-scraper-py 0.1.0

TradingView data scraper with multiple output formats

📺 TV Scraper

Fetch historical price data from TradingView in any format you need.

📖 Overview

TV Scraper is a lightweight yet powerful Python library that fetches historical OHLCV (Open, High, Low, Close, Volume) data from TradingView. Whether you need DataFrames for analysis, NumPy arrays for machine learning, or JSON for APIs — TV Scraper has you covered.

Why TV Scraper?

• 🚀 One line to get data — df = tv.get("BTCUSDT")
• 🎨 7 output formats — pandas, numpy, arrays, dict, json, csv, raw tuples
• 🧹 Zero bloat — Only requires websocket-client
• 📊 ML-ready — Direct to TensorFlow, PyTorch, or scikit-learn
• 🔄 Batch fetching — Get multiple symbols in one call
• 🛡️ Smart defaults — Works out of the box, fully customizable
• 🌍 All TradingView markets — Crypto, stocks, forex, indices, commodities

---

📦 Installation

Basic Install (DataFrame support)

pip install tv_scraper[pandas]

ML Install (NumPy arrays)

pip install tv_scraper[numpy]

Full Install (everything)

pip install tv_scraper[all]

From GitHub (latest)

pip install git+https://github.com/anuragjha0001/tv_scraper.git

---

🚀 Quick Start

from tv_scraper import TvDatafeed

# Create instance
tv = TvDatafeed()

# Get Bitcoin daily data (returns DataFrame)
df = tv.get("BTCUSDT")
print(df.head())

Output:

                       open    high     low   close    volume
timestamp                                                   
2026-04-05 00:00:00  83500.0  84200.0  83400.0  84000.0   125.34
2026-04-06 00:00:00  84000.0  84800.0  83900.0  84600.0   200.50
...

---

📚 Usage Guide

1. Basic Fetching

from tv_scraper import TvDatafeed
from datetime import datetime, timedelta

tv = TvDatafeed()

# Simple - last 30 days daily data
df = tv.get("BTCUSDT")

# With custom parameters
df = tv.get(
    symbol="ETHUSDT",
    exchange="BINANCE",      # Default: BINANCE
    interval="1H",           # 1m, 5m, 15m, 1H, 4H, 1D, 1W, 1M
    start="2024-01-01",      # Start date
    end="2024-01-31",        # End date
)

# Using datetime objects
start = datetime(2024, 1, 1)
end = datetime.now()
df = tv.get("SOLUSDT", start=start, end=end, interval="4H")

2. All Output Formats

tv = TvDatafeed()

# DataFrame (default)
df = tv.get("BTCUSDT", output_format="pandas")

# NumPy structured array
arr = tv.get("BTCUSDT", output_format="numpy")
print(arr.dtype)  # [('timestamp', '<i8'), ('open', '<f8'), ...]

# Separate arrays (ML-ready)
ts, o, h, l, c, v = tv.get("BTCUSDT", output_format="arrays")

# List of dictionaries (API-ready)
data = tv.get("BTCUSDT", output_format="dict")
# [{"timestamp": 1704067200, "open": 42500.5, ...}, ...]

# JSON string
json_str = tv.get("BTCUSDT", output_format="json", indent=2)

# CSV string
csv_str = tv.get("BTCUSDT", output_format="csv")

# Raw tuples (fastest)
bars = tv.get("BTCUSDT", output_format="raw")
# [(1704067200, 42500.5, 43200.0, 42400.0, 43100.0, 125.34), ...]

3. Batch Fetching (Multiple Symbols)

tv = TvDatafeed()

results = tv.get_multi([
    {"symbol": "BTCUSDT", "interval": "1H", "output_format": "pandas"},
    {"symbol": "ETHUSDT", "interval": "1H", "output_format": "dict"},
    {"symbol": "SOLUSDT", "interval": "4H", "output_format": "json"},
])

# Access results
btc_df = results["BINANCE:BTCUSDT"]
eth_data = results["BINANCE:ETHUSDT"]
sol_json = results["BINANCE:SOLUSDT"]

4. ML Pipeline (PyTorch/TensorFlow Ready)

from tv_scraper import TvDatafeed
import numpy as np
import torch

tv = TvDatafeed()

# Get data as separate arrays
ts, opens, highs, lows, closes, volumes = tv.get(
    "BTCUSDT", 
    interval="1H",
    output_format="arrays"
)

# Feature engineering
X = np.column_stack([opens, highs, lows, volumes])
y = np.roll(closes, -1)[:-1]  # Next period's close
X = X[:-1]

# Convert to PyTorch tensors
X_tensor = torch.from_numpy(X).float()
y_tensor = torch.from_numpy(y).float()

print(f"Features: {X_tensor.shape}, Target: {y_tensor.shape}")

5. API Backend (FastAPI)

from fastapi import FastAPI
from tv_scraper import TvDatafeed

app = FastAPI()
tv = TvDatafeed()

@app.get("/api/crypto/{symbol}")
def get_crypto_data(symbol: str, interval: str = "1D"):
    return tv.get(
        symbol.upper(),
        interval=interval,
        output_format="json"
    )

# GET http://localhost:8000/api/crypto/BTCUSDT?interval=1H

6. Context Manager

# Connection auto-closes after use
with TvDatafeed() as tv:
    df = tv.get("BTCUSDT")
    # Connection automatically closed

7. Stock & Forex Markets

tv = TvDatafeed()

# Indian Stocks (NSE)
df = tv.get("RELIANCE", exchange="NSE", interval="1D")

# US Stocks (NASDAQ)
df = tv.get("AAPL", exchange="NASDAQ", interval="1H")

# Forex
df = tv.get("EURUSD", exchange="FX_IDC", interval="1D")

# Indices
df = tv.get("SPX", exchange="SP", interval="1D")

# Commodities
df = tv.get("XAUUSD", exchange="OANDA", interval="1D")

---

🕐 Supported Timeframes

Code	Timeframe	Bars/Day
1m	1 Minute	1440
3m	3 Minutes	480
5m	5 Minutes	288
15m	15 Minutes	96
30m	30 Minutes	48
1H	1 Hour	24
2H	2 Hours	12
3H	3 Hours	8
4H	4 Hours	6
1D	Daily	1
1W	Weekly	~0.14
1M	Monthly	~0.03

---

🎯 Output Formats

Format	Returns	Required	Best For
pandas	DataFrame	pandas	Data analysis, plotting
numpy	Structured ndarray	numpy	Scientific computing
arrays	Tuple of 6 arrays	numpy	ML/AI pipelines
dict	List of dicts	None	APIs, databases
json	JSON string	None	HTTP responses
csv	CSV string	None	Excel, spreadsheets
raw	List of tuples	None	Custom processing

---

📊 Performance Benchmarks

Format	1,000 bars	10,000 bars	100,000 bars
raw (tuple)	0.05s	0.20s	1.50s
numpy	0.08s	0.30s	2.00s
arrays	0.09s	0.35s	2.20s
dict	0.15s	0.50s	3.00s
pandas	0.25s	0.80s	5.00s
json	0.30s	1.00s	6.00s

Benchmarks on Python 3.12, i7-13700K

---

🛠️ API Reference

TvDatafeed Class

TvDatafeed(
    auth_token="unauthorized_user_token",  # TradingView auth token
    max_retries=3,                         # Connection retry attempts
    timeout=10                             # WebSocket timeout (seconds)
)

get() Parameters

Parameter	Type	Default	Description
symbol	str	Required	Trading pair symbol
exchange	str	"BINANCE"	Exchange identifier
interval	str	"1D"	Timeframe interval
start	str/datetime	30 days ago	Start of date range
end	str/datetime	now	End of date range
output_format	str	"pandas"	Output format
**format_kwargs	dict	{}	Extra formatter options

Date Format Examples

# All these work:
tv.get("BTCUSDT", start="2024-01-01")           # YYYY-MM-DD
tv.get("BTCUSDT", start="01-01-2024")           # DD-MM-YYYY
tv.get("BTCUSDT", start="2024-01-01 12:30:00")  # With time
tv.get("BTCUSDT", start=datetime(2024, 1, 1))   # datetime object
tv.get("BTCUSDT", start=1704067200)             # Unix timestamp

---

❗ Error Handling

from tv_scraper import TvDatafeed
from tv_scraper.exceptions import *

tv = TvDatafeed()

try:
    df = tv.get("INVALID_SYMBOL")
except NoDataError:
    print("No data returned for this symbol")
except ConnectionError:
    print("Could not connect to TradingView")
except FormatError:
    print("Invalid output format specified")
except InvalidSymbolError:
    print("Symbol format is invalid")

Exception Hierarchy

TvScraperError (base)
├── ConnectionError    — WebSocket connection failures
├── NoDataError        — No data for symbol/range
├── InvalidSymbolError — Bad symbol format
├── FormatError        — Invalid output format
└── ParseError         — Response parsing failures

---

🧪 Running Tests

pip install tv_scraper[dev]
pytest tests/ -v
pytest tests/ --cov=tv_scraper --cov-report=html

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for details.

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m "Add amazing feature"
4. Push branch: git push origin feature/amazing-feature
5. Open a Pull Request

---

📝 Changelog

See CHANGELOG.md for version history.

---

⚠️ Disclaimer

This library is for educational and research purposes only.

• Respect TradingView's Terms of Service
• Implement appropriate rate limiting in production
• Consider using official APIs for critical applications

---

📄 License

MIT License — See LICENSE for details.

---

🌟 Star History

If you find this useful, please ⭐ star the repository!

---

📬 Contact

• Author: Anurag Jha
• Email: [e-mail]
• GitHub: @anuragjha0001
• Issues: Report Bug

---

Made with ❤️ by Anurag Jha