tv-scraper

https://smitkunpara.github.io/tv-scraper/latest/
Admin
tv-scraper is a Python library that provides a consistent API to fetch and analyze TradingView...
Tokens:47,647
Snippets:431
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install and Preview Docs with MkDocs Material and mike

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing

Install documentation tooling and preview current or versioned documentation locally.

```bash
# Install docs tooling
uv sync --extra dev

# Preview current docs
uv run mkdocs serve

# Preview versioned docs locally
uv run mike serve
```

--------------------------------

### Install tv-scraper using uv

Source: https://smitkunpara.github.io/tv-scraper/latest/getting-started?q=

Use this command to install the library if you are using uv.

```bash
uv add tv-scraper

```

--------------------------------

### Install tv-scraper using pip

Source: https://smitkunpara.github.io/tv-scraper/latest/getting-started?q=

Use this command to install the library if you are using pip.

```bash
pip install tv-scraper

```

--------------------------------

### Setup for local development

Source: https://smitkunpara.github.io/tv-scraper/latest/getting-started?q=

Clone the repository and sync dependencies for local development.

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

```

--------------------------------

### Initialize SymbolMarkets and Get Symbol Markets

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/symbol_markets

Instantiate the SymbolMarkets scraper and call get_symbol_markets with exchange and symbol parameters. Ensure correct method usage as older examples might use incorrect names.

```python
from tv_scraper import SymbolMarkets

scraper = SymbolMarkets()
scraper = SymbolMarkets()
result = scraper.get_symbol_markets(exchange="NASDAQ", symbol="AAPL")

```

```python
result = scraper.get_symbol_markets(exchange="NASDAQ", symbol="AAPL")

```

```python
scraper.get_markets(symbol="AAPL")

```

```python
scraper.get_symbol_markets(exchange="NASDAQ", symbol="AAPL")

```

--------------------------------

### CandleStreamer Quick Example

Source: https://smitkunpara.github.io/tv-scraper/latest?q=

This example demonstrates how to use the CandleStreamer to fetch OHLCV candles and indicator studies. It shows how to initialize the streamer, call the get_candles method with parameters like exchange, symbol, timeframe, and indicators, and how to process the success or error response.

```APIDOC
## CandleStreamer.get_candles

### Description
Fetches OHLCV candles and indicator studies for a given symbol and exchange.

### Method
Python method call

### Endpoint
N/A (Python library)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from tv_scraper import CandleStreamer

streamer = CandleStreamer()
result = streamer.get_candles(
    exchange="BINANCE",
    symbol="BTCUSDT",
    timeframe="1m",
    numb_candles=5,
    indicators=[("STD;RSI", "1.0")]
)

if result["status"] == "success":
    print(result["data"]["ohlcv"])
else:
    print(result["error"])
```

### Response
#### Success Response (status: "success")
- **data**: Object containing the OHLCV data and indicator studies.
- **metadata**: Object containing metadata about the request.
- **warnings**: List of strings containing any warnings.

#### Response Example
```json
{
    "status": "success",
    "data": { ... },
    "metadata": { ... },
    "warnings": [ ... ],
    "error": null
}
```

#### Failed Response (status: "failed")
- **error**: String message describing the error.

#### Response Example
```json
{
    "status": "failed",
    "data": null,
    "metadata": { ... },
    "warnings": [ ... ],
    "error": "Error message description"
}
```
```

--------------------------------

### Get Candles using Streamer (Legacy)

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/streamer?q=

This example demonstrates how to fetch historical candle data using the deprecated Streamer class. New code should use CandleStreamer.get_candles instead.

```python
from tv_scraper import Streamer

streamer = Streamer()
result = streamer.get_candles(
    exchange="BINANCE",
    symbol="BTCUSDT",
    timeframe="1h",
    numb_candles=10,
)


```

--------------------------------

### CandleStreamer Example

Source: https://smitkunpara.github.io/tv-scraper/latest

This example demonstrates how to use the CandleStreamer class to fetch historical OHLCV data and indicator studies. It shows how to initialize the streamer, call the get_candles method with parameters like exchange, symbol, timeframe, and number of candles, and how to process the response.

```APIDOC
## CandleStreamer.get_candles

### Description
Fetches historical OHLCV candles and indicator studies for a given symbol and exchange.

### Method Signature
```python
CandleStreamer.get_candles(
    exchange: str,
    symbol: str,
    timeframe: str,
    numb_candles: int,
    indicators: list[tuple[str, str]] = None
)
```

### Parameters
- **exchange** (str) - The trading exchange (e.g., "BINANCE").
- **symbol** (str) - The trading symbol (e.g., "BTCUSDT").
- **timeframe** (str) - The candle timeframe (e.g., "1m").
- **numb_candles** (int) - The number of historical candles to retrieve.
- **indicators** (list[tuple[str, str]], optional) - A list of technical indicators to include. Each indicator is a tuple of (indicator_name, parameters) (e.g., [("STD;RSI", "1.0")]).

### Request Example
```python
from tv_scraper import CandleStreamer

streamer = CandleStreamer()
result = streamer.get_candles(
    exchange="BINANCE",
    symbol="BTCUSDT",
    timeframe="1m",
    numb_candles=5,
    indicators=[("STD;RSI", "1.0")]
)
```

### Response
Every public method returns a dictionary with the following structure:

```json
{
    "status": "success" | "failed",
    "data": ...,
    "metadata": {...},
    "warnings": [str, ...],
    "error": None | "message"
}
```

#### Success Response Example
```json
{
    "status": "success",
    "data": {
        "ohlcv": [
            [1678886400000, 24000.0, 24100.0, 23900.0, 24050.0, 100.0],
            ...
        ]
    },
    "metadata": {},
    "warnings": [],
    "error": null
}
```

#### Error Response Example
```json
{
    "status": "failed",
    "data": null,
    "metadata": {},
    "warnings": [],
    "error": "An error message describing the failure."
}
```
```

--------------------------------

### Invalid Market Input Example

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/market_movers

This example demonstrates an incorrect usage where an invalid market name is provided, leading to a failure. Always use predefined market identifiers.

```python
scraper.get_market_movers(market="america", category="gainers")

```

--------------------------------

### Initialize Fundamentals Scraper

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/fundamentals

Instantiate the Fundamentals scraper. No specific setup or imports are required beyond importing the class.

```python
from tv_scraper import Fundamentals

scraper = Fundamentals()
```

--------------------------------

### Set Up Development Environment with uv

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing?q=

Install all project dependencies, including development tools, and set up the project in development mode using uv.

```bash
# Install all dependencies (main + dev tools)
uv sync --extra dev

# Install in development mode
uv pip install -e .
```

--------------------------------

### Initialize Calendar Scraper

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/calendar

Instantiate the Calendar scraper. No specific setup or imports are required beyond importing the Calendar class.

```python
from tv_scraper import Calendar

scraper = Calendar()
```

--------------------------------

### Error Handling Example

Source: https://smitkunpara.github.io/tv-scraper/latest/api-conventions?q=

Illustrates how the API handles invalid inputs and returns error information.

```APIDOC
## Error Handling

Public scraper methods return failures instead of raising data-access errors.
```python
result = scraper.get_technicals(
    exchange="INVALID",
    symbol="AAPL",
    technical_indicators=["RSI"],
)
```

```json
{ "status": "failed", "data": None, "metadata": {
    "exchange": "INVALID",
    "symbol": "AAPL",
    "technical_indicators": ["RSI"],
},
"warnings": [],
"error": "Invalid value: 'INVALID'. ...", 
}
```
```

--------------------------------

### Correct Input for get_technicals

Source: https://smitkunpara.github.io/tv-scraper/latest/getting-started?q=

This example demonstrates the correct way to pass exchange and symbol as separate arguments to the get_technicals method.

```python
scraper.get_technicals(exchange="NASDAQ", symbol="AAPL")

```

--------------------------------

### Request Style Examples

Source: https://smitkunpara.github.io/tv-scraper/latest/api-conventions

Demonstrates various ways to call tv-scraper methods, emphasizing keyword arguments, optional lists, and snake_case naming.

```APIDOC
## Request Style

### Separate `exchange` and `symbol`
For symbol-based methods, pass them as two arguments:
```python
scraper.get_technicals(exchange="NASDAQ", symbol="AAPL")
```

### Use keyword arguments
Keyword arguments make the calls easier to read and reduce mistakes:
```python
scraper.get_market_movers(
    market="stocks-usa",
    category="gainers",
    limit=10,
)
```

### Optional lists stay as Python lists
```python
scraper.get_news(
    provider=["reuters", "tradingview"],
    market_country=["US", "IN"],
    market=["stock", "crypto"],
)
```

### Naming stays snake_case
```python
scraper.get_technicals(export="json")
```
```

--------------------------------

### Initialize and Get Symbol Markets

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/symbol_markets?q=

Instantiate SymbolMarkets and retrieve trading locations for a specific exchange and symbol. Ensure the SymbolMarkets class is imported.

```python
from tv_scraper import SymbolMarkets

scraper = SymbolMarkets()
scraper = SymbolMarkets()
result = scraper.get_symbol_markets(exchange="NASDAQ", symbol="AAPL")
```

--------------------------------

### Write CandleStreamer Tests

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing?q=

Example tests for the CandleStreamer class, covering successful candle fetching and error handling for invalid exchanges.

```python
import pytest
from tv_scraper import CandleStreamer

class TestCandleStreamer:
    def test_get_candles_success(self):
        """Test fetching candles successfully."""
        streamer = CandleStreamer()
        result = streamer.get_candles(
            exchange="BINANCE",
            symbol="BTCUSDT",
            timeframe="1m",
            numb_candles=5
        )
        assert result["status"] == "success"
        assert "ohlcv" in result["data"]
        assert len(result["data"]["ohlcv"]) == 5

    def test_invalid_exchange(self):
        """Test error handling for invalid exchange."""
        streamer = CandleStreamer()
        result = streamer.get_candles(
            exchange="INVALID",
            symbol="BTCUSDT"
        )
        assert result["status"] == "failed"
        assert result["error"] is not None
```

--------------------------------

### Minimal Code Example for Bug Reproduction

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing?q=

Provide a minimal, self-contained Python code snippet that reproduces the reported bug.

```python
# Provide a minimal code example that reproduces the issue
```

--------------------------------

### Incorrect Input for get_technicals

Source: https://smitkunpara.github.io/tv-scraper/latest/getting-started?q=

This example shows an incorrect way to pass exchange and symbol, where they are combined into a single string instead of separate arguments.

```python
scraper.get_technicals(exchange="NASDAQ:AAPL", symbol="AAPL")

```

--------------------------------

### Invalid Market Input - Python

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/markets?q=

This example demonstrates an incorrect market input, which will cause the function to fail. Ensure market names are from the accepted values list.

```python
scraper.get_markets(market="stocks-usa")
```

--------------------------------

### Success Response Structure

Source: https://smitkunpara.github.io/tv-scraper/latest/getting-started?q=

Example of the JSON structure returned upon a successful API call, including data, metadata, and empty warnings/error fields.

```json
{
    "status": "success",
    "data": {"RSI": 54.21, "MACD.macd": 0.15},
    "metadata": {
        "exchange": "NASDAQ",
        "symbol": "AAPL",
        "timeframe": "1d",
        "technical_indicators": ["RSI", "MACD.macd"],
    },
    "warnings": [],
    "error": None,
}

```

--------------------------------

### Build and Serve Documentation with MkDocs

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing?q=

Serve the documentation locally for development or build it for production using MkDocs.

```bash
# Serve docs locally for development
mkdocs serve

# Build docs for production
mkdocs build
```

--------------------------------

### Example Bug Report: Technicals Scraper Timeout

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing

An example bug report detailing a timeout issue with the Technicals scraper, including steps to reproduce and environment details.

```python
from tv_scraper import Technicals

scraper = Technicals()
result = scraper.get_technicals(
    exchange="BINANCE",
    symbol="BTCUSD",
    technical_indicators=["RSI", "MACD"]
)


```

--------------------------------

### Manage Versioned Docs with mike

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing?q=

Deploy new documentation versions and set the default documentation version using mike.

```bash
# Publish a release docs version
uv run mike deploy --update-aliases <version> <alias>

# Set the default docs version
uv run mike set-default latest
```

--------------------------------

### Example Bug Report: Technicals Scraper Timeout

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing?q=

An example bug report detailing a timeout issue with the Technicals scraper, including steps to reproduce, expected vs. actual behavior, and environment details.

```python
from tv_scraper import Technicals

scraper = Technicals()
result = scraper.get_technicals(
    exchange="BINANCE",
    symbol="BTCUSD",
    technical_indicators=["RSI", "MACD"]
)

```

--------------------------------

### Initialize Pine Facade with Cookie

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/pine?q=

Instantiate the Pine facade by providing your TradingView cookie. A missing cookie will result in failed requests.

```python
from tv_scraper import Pine

pine = Pine(cookie="paste_your_cookie_here")
```

--------------------------------

### Get All Fundamentals

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/fundamentals

Retrieves all available fundamental fields for a specified exchange and symbol.

```APIDOC
## Get All Fundamentals

### Description
Retrieves all fundamental fields for a given stock symbol from the TradingView scanner endpoint.

### Method Signature
`get_fundamentals(exchange: str, symbol: str)`

### Parameters
#### Path Parameters
- **exchange** (str) - Required - The stock exchange (e.g., "NASDAQ").
- **symbol** (str) - Required - The stock symbol (e.g., "AAPL").

### Request Example
```python
from tv_scraper import Fundamentals

scraper = Fundamentals()
result = scraper.get_fundamentals(exchange="NASDAQ", symbol="AAPL")
```

### Response Example
```json
{
    "status": "success",
    "data": {
        "symbol": "NASDAQ:AAPL",
        "market_cap_basic": 2950000000000,
        "total_revenue": 416161000000,
        "net_income": 108000000000,
        "price_earnings_ttm": 29.4,
        ...
    },
    "metadata": {
        "exchange": "NASDAQ",
        "symbol": "AAPL",
        "fields": [...],
        "data_category": "fundamentals"
    },
    "warnings": [],
    "error": null
}
```
```

--------------------------------

### Get All Fundamentals

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/fundamentals?q=

Retrieves all available fundamental fields for a given exchange and symbol.

```APIDOC
## Get All Fundamentals

### Description
Retrieves all available fundamental fields for a given exchange and symbol.

### Method
```python
scraper.get_fundamentals(exchange: str, symbol: str)
```

### Parameters
#### Path Parameters
- **exchange** (str) - Required - Use a supported exchange from Exchanges.
- **symbol** (str) - Required - Symbol slug such as `AAPL`.

### Request Example
```python
from tv_scraper import Fundamentals

scraper = Fundamentals()
result = scraper.get_fundamentals(exchange="NASDAQ", symbol="AAPL")
```

### Response
#### Success Response (200)
Returns a JSON object containing fundamental data for the specified symbol, including market capitalization, P/E ratio, and other financial metrics.

#### Response Example
```json
{
    "status": "success",
    "data": {
        "symbol": "NASDAQ:AAPL",
        "market_cap_basic": 2950000000000,
        "price_earnings_ttm": 29.4,
        ...
    },
    "metadata": {
        "exchange": "NASDAQ",
        "symbol": "AAPL",
        "fields": [...],
        "data_category": "fundamentals"
    },
    "warnings": [],
    "error": null
}
```
```

--------------------------------

### Get Available Indicators

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/candle_streamer

Retrieves a list of available indicator IDs that can be used with the CandleStreamer.

```APIDOC
## get_available_indicators

### Description
Retrieves a list of available indicator IDs that can be used with the CandleStreamer. This is useful for discovering built-in indicators.

### Method
`CandleStreamer.get_available_indicators()`

### Parameters
None

### Request Example
```python
result = CandleStreamer.get_available_indicators()
```

### Response
Returns a list of indicator script IDs. For custom or private indicators, use your Pine script ID and version. A cookie may be required if the script is owned by your TradingView account.
```

--------------------------------

### Get Selected Fundamentals

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/fundamentals

Retrieves specific fundamental fields for a given exchange and symbol.

```APIDOC
## Get Selected Fundamentals

### Description
Retrieves a specified list of fundamental fields for a given stock symbol from the TradingView scanner endpoint.

### Method Signature
`get_fundamentals(exchange: str, symbol: str, fields: list[str])`

### Parameters
#### Path Parameters
- **exchange** (str) - Required - The stock exchange (e.g., "NASDAQ").
- **symbol** (str) - Required - The stock symbol (e.g., "AAPL").
- **fields** (list[str]) - Optional - A list of field names to retrieve (e.g., `["total_revenue", "net_income"]`). If `None` or an empty list, all fields are fetched.

### Request Example
```python
result = scraper.get_fundamentals(
    exchange="NASDAQ",
    symbol="AAPL",
    fields=["total_revenue", "net_income", "price_earnings_ttm"],
)
```

### Response Example
```json
{
    "status": "success",
    "data": {
        "symbol": "NASDAQ:AAPL",
        "total_revenue": 416161000000,
        "net_income": 108000000000,
        "price_earnings_ttm": 29.4
    },
    "metadata": {
        "exchange": "NASDAQ",
        "symbol": "AAPL",
        "fields": ["total_revenue", "net_income", "price_earnings_ttm"],
        "data_category": "fundamentals"
    },
    "warnings": [],
    "error": null
}
```
```

--------------------------------

### Run Quality Checks

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing?q=

Execute tests and build documentation as part of the quality assurance process before committing changes.

```bash
# Run tests
python -m pytest

# Build documentation
mkdocs build
```

--------------------------------

### Get Selected Fundamentals

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/fundamentals?q=

Retrieves specific fundamental fields for a given exchange and symbol.

```APIDOC
## Get Selected Fundamentals

### Description
Retrieves specific fundamental fields for a given exchange and symbol. Users can specify a list of desired fields to fetch.

### Method
```python
scraper.get_fundamentals(exchange: str, symbol: str, fields: list[str])
```

### Parameters
#### Path Parameters
- **exchange** (str) - Required - Use a supported exchange from Exchanges.
- **symbol** (str) - Required - Symbol slug such as `AAPL`.
- **fields** (list[str]) - Optional - A list of field names to fetch. If `None` or `[]`, all fields are fetched.

### Request Example
```python
result = scraper.get_fundamentals(
    exchange="NASDAQ",
    symbol="AAPL",
    fields=["total_revenue", "net_income", "price_earnings_ttm"],
)
```

### Response
#### Success Response (200)
Returns a JSON object containing the requested fundamental data fields for the specified symbol.

#### Response Example
```json
{
    "status": "success",
    "data": {
        "symbol": "NASDAQ:AAPL",
        "total_revenue": 416161000000,
        "net_income": 108000000000,
        "price_earnings_ttm": 29.4
    },
    "metadata": {
        "exchange": "NASDAQ",
        "symbol": "AAPL",
        "fields": ["total_revenue", "net_income", "price_earnings_ttm"],
        "data_category": "fundamentals"
    },
    "warnings": [],
    "error": null
}
```
```

--------------------------------

### Initialize CandleStreamer with Cookie and Indicators

Source: https://smitkunpara.github.io/tv-scraper/latest/getting_cookies?q=

Configure the CandleStreamer with a TradingView cookie and specify custom indicators. This is useful for fetching candle data with specific technical analysis indicators applied.

```python
from tv_scraper import CandleStreamer

streamer = CandleStreamer(cookie=TRADINGVIEW_COOKIE)
result = streamer.get_candles(
    exchange="BINANCE",
    symbol="BTCUSDT",
    indicators=[("STD;RSI", "37.0")],
)


```

--------------------------------

### Initialize and Use Minds Scraper

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/minds

Instantiate the Minds scraper and fetch community posts for a symbol. Ensure correct exchange and symbol are provided. The limit parameter controls the number of posts fetched.

```python
from tv_scraper import Minds

scraper = Minds()
result = scraper.get_minds(exchange="NASDAQ", symbol="AAPL", limit=20)
```

--------------------------------

### Get Available Indicators

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/candle_streamer?q=

Retrieves a list of available indicator script IDs that can be used with CandleStreamer.

```APIDOC
## get_available_indicators

### Description
Retrieves a list of available indicator script IDs that can be used with CandleStreamer. This is useful for discovering built-in indicators.

### Method
```python
CandleStreamer.get_available_indicators()
```

### Response Example (Success)
```python
["STD;RSI", "STD;MACD", ...]
```
```

--------------------------------

### Get Candles with Indicators

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/candle_streamer

Fetches historical OHLCV candles along with specified indicator study data.

```APIDOC
## get_candles (Candles with Indicators)

### Description
Fetches historical OHLCV candles along with specified indicator study data.

### Method
`CandleStreamer.get_candles()`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **exchange** (string) - Required - The supported exchange name.
- **symbol** (string) - Required - The exchange symbol slug (e.g., `BTCUSDT`).
- **timeframe** (string) - Required - The supported timeframe (e.g., `1h`, `15m`).
- **numb_candles** (integer) - Required - The number of candles to retrieve, must be between 1 and 5000.
- **indicators** (list of tuples) - Optional - A list of tuples, where each tuple contains `(script_id, version)` for the indicator studies to attach.

### Request Example
```python
result = streamer.get_candles(
    exchange="BINANCE",
    symbol="BTCUSDT",
    timeframe="15m",
    numb_candles=20,
    indicators=[("STD;RSI", "37.0")],
)
```

### Response
#### Success Response (200)
Returns a JSON object containing candle data, indicator data keyed by study name, metadata, warnings, and error status.

```json
{
    "status": "success",
    "data": {
        "ohlcv": [
            {
                "index": 0,
                "timestamp": 1700000000,
                "open": 185.0,
                "high": 187.0,
                "low": 184.0,
                "close": 186.0,
                "volume": 50000000,
            },
            # ... more candles
        ],
        "indicators": {
            "STD;RSI": [
                {"index": 0, "timestamp": 1700000000, "0": 55.5},
                # ... more rows
            ]
        },
    },
    "metadata": {
        "exchange": "BINANCE",
        "symbol": "BTCUSDT",
        "timeframe": "15m",
        "numb_candles": 20,
        "indicators": [("STD;RSI", "37.0")],
    },
    "warnings": [],
    "error": null,
}
```

#### Failure Response
If no OHLCV data arrives, returns `status="failed"`.
If requested indicators do not resolve, returns `status="failed"` with missing indicator IDs in the error message.
```

--------------------------------

### Handle Missing Filter Input

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/options

This example demonstrates an invalid request that fails because neither an expiration date nor a strike price is provided. At least one of these filters is required.

```python
scraper.get_options(exchange="BSE", symbol="SENSEX")
```

--------------------------------

### Get Candles with Indicators

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/candle_streamer?q=

Fetches historical OHLCV candles along with data for specified indicator studies.

```APIDOC
## get_candles (Candles with Indicators)

### Description
Fetches historical OHLCV candles along with data for specified indicator studies.

### Method
```python
CandleStreamer.get_candles(
    exchange: str,
    symbol: str,
    timeframe: str,
    numb_candles: int,
    indicators: list[tuple[str, str]] = None
)
```

### Parameters
#### Path Parameters
- **exchange** (str) - Required - The supported exchange (e.g., "BINANCE").
- **symbol** (str) - Required - The exchange symbol slug (e.g., "BTCUSDT").
- **timeframe** (str) - Required - The supported timeframe (e.g., "15m").
- **numb_candles** (int) - Required - The number of candles to retrieve, must be between 1 and 5000.
- **indicators** (list[tuple[str, str]]) - Optional - A list of tuples, where each tuple contains the indicator script ID and version (e.g., [("STD;RSI", "37.0")]).

### Response Example (Success)
```json
{
    "status": "success",
    "data": {
        "ohlcv": [
            {
                "index": 0,
                "timestamp": 1700000000,
                "open": 185.0,
                "high": 187.0,
                "low": 184.0,
                "close": 186.0,
                "volume": 50000000
            }
        ],
        "indicators": {
            "STD;RSI": [
                {"index": 0, "timestamp": 1700000000, "0": 55.5}
            ]
        }
    },
    "metadata": {
        "exchange": "BINANCE",
        "symbol": "BTCUSDT",
        "timeframe": "15m",
        "numb_candles": 20,
        "indicators": [("STD;RSI", "37.0")]
    },
    "warnings": [],
    "error": null
}
```
```

--------------------------------

### Get Candles Only

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/candle_streamer

Fetches a specified number of historical OHLCV candles for a given exchange, symbol, and timeframe.

```APIDOC
## get_candles (Candles Only)

### Description
Fetches a specified number of historical OHLCV candles for a given exchange, symbol, and timeframe.

### Method
`CandleStreamer.get_candles()`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **exchange** (string) - Required - The supported exchange name.
- **symbol** (string) - Required - The exchange symbol slug (e.g., `BTCUSDT`).
- **timeframe** (string) - Required - The supported timeframe (e.g., `1h`, `15m`).
- **numb_candles** (integer) - Required - The number of candles to retrieve, must be between 1 and 5000.

### Request Example
```python
from tv_scraper import CandleStreamer

streamer = CandleStreamer()
result = streamer.get_candles(
    exchange="BINANCE",
    symbol="BTCUSDT",
    timeframe="1h",
    numb_candles=25,
)
```

### Response
#### Success Response (200)
Returns a JSON object containing candle data, indicator data (if requested), metadata, warnings, and error status.

```json
{
    "status": "success",
    "data": {
        "ohlcv": [
            {
                "index": 0,
                "timestamp": 1700000000,
                "open": 185.0,
                "high": 187.0,
                "low": 184.0,
                "close": 186.0,
                "volume": 50000000,
            },
            # ... more candles
        ],
        "indicators": {},
    },
    "metadata": {
        "exchange": "BINANCE",
        "symbol": "BTCUSDT",
        "timeframe": "1h",
        "numb_candles": 25,
    },
    "warnings": [],
    "error": null,
}
```

#### Failure Response
If no OHLCV data arrives, returns `status="failed"`.
If requested indicators do not resolve, returns `status="failed"` with missing indicator IDs in the error message.
```

--------------------------------

### Clone tv-scraper Repository

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing?q=

Clone the tv-scraper repository locally and navigate into the project directory.

```bash
git clone https://github.com/smitkunpara/tv-scraper.git
cd tv-scraper
```

--------------------------------

### Get Candles Only

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/candle_streamer?q=

Fetches a specified number of historical OHLCV candles for a given exchange, symbol, and timeframe.

```APIDOC
## get_candles (Candles Only)

### Description
Fetches a specified number of historical OHLCV candles for a given exchange, symbol, and timeframe.

### Method
```python
CandleStreamer.get_candles(
    exchange: str,
    symbol: str,
    timeframe: str,
    numb_candles: int,
)
```

### Parameters
#### Path Parameters
- **exchange** (str) - Required - The supported exchange (e.g., "BINANCE").
- **symbol** (str) - Required - The exchange symbol slug (e.g., "BTCUSDT").
- **timeframe** (str) - Required - The supported timeframe (e.g., "1h").
- **numb_candles** (int) - Required - The number of candles to retrieve, must be between 1 and 5000.

### Response Example (Success)
```json
{
    "status": "success",
    "data": {
        "ohlcv": [
            {
                "index": 0,
                "timestamp": 1700000000,
                "open": 185.0,
                "high": 187.0,
                "low": 184.0,
                "close": 186.0,
                "volume": 50000000
            }
        ],
        "indicators": {}
    },
    "metadata": {
        "exchange": "BINANCE",
        "symbol": "BTCUSDT",
        "timeframe": "1h",
        "numb_candles": 25
    },
    "warnings": [],
    "error": null
}
```
```

--------------------------------

### Get Options by Strike

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/options

Fetches option chain rows for a specific underlying symbol and strike price.

```APIDOC
## Get Options by Strike

### Description
Fetches option chain rows for a specific underlying symbol and strike price.

### Method
`get_options`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **exchange** (string) - Required - The exchange of the underlying symbol (e.g., `BSE`).
- **symbol** (string) - Required - The underlying symbol (e.g., `SENSEX`).
- **strike** (integer or float) - Required - The strike price for filtering.
- **expiration** (integer) - Optional - The expiration date in `YYYYMMDD` format.
- **columns** (list) - Optional - A list of allowed option columns to retrieve.

### Request Example
```python
from tv_scraper import Options

scraper = Options()
result = scraper.get_options(
    exchange="BSE",
    symbol="SENSEX",
    strike=83300,
)
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation ('success' or 'failed').
- **data** (list) - A list of option chain data objects.
- **metadata** (object) - Contains metadata about the request and response.
- **warnings** (list) - A list of warnings, if any.
- **error** (any) - Contains error information if the status is 'failed'.

#### Response Example
```json
{
    "status": "success",
    "data": [
        {
            "symbol": "BSE:OPTION_SYMBOL",
            "strike": 83300,
            "bid": 101.5,
            "ask": 103.0,
        },
        ...
    ],
    "metadata": {
        "exchange": "BSE",
        "symbol": "SENSEX",
        "strike": 83300,
        "total": 12,
        "filter_value": 83300,
    },
    "warnings": [],
    "error": null,
}
```
```

--------------------------------

### Get Options by Expiration

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/options

Fetches option chain rows for a specific underlying symbol and expiration date.

```APIDOC
## Get Options by Expiration

### Description
Fetches option chain rows for a specific underlying symbol and expiration date.

### Method
`get_options`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **exchange** (string) - Required - The exchange of the underlying symbol (e.g., `BSE`).
- **symbol** (string) - Required - The underlying symbol (e.g., `SENSEX`).
- **expiration** (integer) - Required - The expiration date in `YYYYMMDD` format.
- **strike** (integer or float) - Optional - The strike price for filtering.
- **columns** (list) - Optional - A list of allowed option columns to retrieve.

### Request Example
```python
from tv_scraper import Options

scraper = Options()
result = scraper.get_options(
    exchange="BSE",
    symbol="SENSEX",
    expiration=20260219,
)
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation ('success' or 'failed').
- **data** (list) - A list of option chain data objects.
- **metadata** (object) - Contains metadata about the request and response.
- **warnings** (list) - A list of warnings, if any.
- **error** (any) - Contains error information if the status is 'failed'.

#### Response Example
```json
{
    "status": "success",
    "data": [
        {
            "symbol": "BSE:OPTION_SYMBOL",
            "expiration": 20260219,
            "strike": 83300,
            "bid": 101.5,
            "ask": 103.0,
        },
        ...
    ],
    "metadata": {
        "exchange": "BSE",
        "symbol": "SENSEX",
        "expiration": 20260219,
        "total": 84,
        "filter_value": 20260219,
    },
    "warnings": [],
    "error": null,
}
```
```

--------------------------------

### Initialize Ideas Scraper with Cookie

Source: https://smitkunpara.github.io/tv-scraper/latest/getting_cookies?q=

Use this snippet to initialize the Ideas scraper with a provided TradingView cookie. This is necessary when TradingView presents a captcha or for accessing features requiring authentication.

```python
from tv_scraper import Ideas

TRADINGVIEW_COOKIE = "paste_your_cookie_here"

scraper = Ideas(cookie=TRADINGVIEW_COOKIE)
result = scraper.get_ideas(
    exchange="CRYPTO",
    symbol="BTCUSD",
    start_page=1,
    end_page=2,
)


```

--------------------------------

### First Successful Call to get_technicals

Source: https://smitkunpara.github.io/tv-scraper/latest/getting-started?q=

Instantiate the Technicals scraper and call get_technicals with exchange, symbol, and desired indicators. Check the status and print data or error.

```python
from tv_scraper import Technicals

scraper = Technicals()
result = scraper.get_technicals(
    exchange="NASDAQ",
    symbol="AAPL",
    technical_indicators=["RSI", "MACD.macd"],
)

if result["status"] == "success":
    print(result["data"])
else:
    print(result["error"])

```

--------------------------------

### Get All Technical Indicators

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/technicals?q=

Fetches all available technical indicators for a given exchange and symbol by omitting the `technical_indicators` parameter.

```APIDOC
## Get All Technical Indicators

### Description
Fetches all available technical indicators for a given exchange and symbol. This is achieved by omitting the `technical_indicators` parameter, which defaults to returning the full set of indicators.

### Method
`get_technicals`

### Parameters
#### Path Parameters
- `exchange` (string) - Required - The stock exchange (e.g., "NASDAQ").
- `symbol` (string) - Required - The stock symbol (e.g., "AAPL").
- `timeframe` (string) - Required - The timeframe for the indicators (e.g., "1d").

### Request Example
```python
from tv_scraper import Technicals

scraper = Technicals()
result = scraper.get_technicals(
    exchange="NASDAQ",
    symbol="AAPL",
    timeframe="1d"
)
```

### Response
#### Success Response (200)
- `status` (string) - Indicates the success of the operation.
- `data` (object) - Contains all available technical indicator values.
- `metadata` (object) - Contains metadata about the request.
- `warnings` (list) - Any warnings generated during the request.
- `error` (null) - Error object, null if no error.

#### Response Example (truncated)
```json
{
    "status": "success",
    "data": {
        "Recommend.Other": 0.09090909090909091,
        "Recommend.All": 0.3787878787878788,
        "RSI": 54.36791522625663,
        "MACD.macd": -1.7690915227776713,
        "MACD.signal": -2.9115386038865543,
        ...
    },
    "metadata": {
        "exchange": "NASDAQ",
        "symbol": "AAPL",
        "timeframe": "1d"
    },
    "warnings": [],
    "error": null
}
```
```

--------------------------------

### Initialize and Get Forecast Data

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/forecast_streamer

Instantiate ForecastStreamer and retrieve forecast data for a given stock symbol and exchange. Ensure the symbol is a stock, otherwise the call will fail.

```python
from tv_scraper import ForecastStreamer

streamer = ForecastStreamer()
result = streamer.get_forecast(exchange="NASDAQ", symbol="AAPL")

```

--------------------------------

### Common Input Pattern for get_technicals

Source: https://smitkunpara.github.io/tv-scraper/latest/getting-started?q=

Demonstrates the standard way to provide exchange and symbol as separate keyword arguments to methods like get_technicals.

```python
result = scraper.get_technicals(exchange="NASDAQ", symbol="AAPL")

```

--------------------------------

### Get Market Data - Python

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/markets?q=

Use this to fetch ranked market data. Specify the market, sorting criteria, and the number of results. Non-stock markets may have restrictions.

```python
from tv_scraper import Markets

scraper = Markets()
result = scraper.get_markets(
    market="america",
    sort_by="market_cap",
    sort_order="desc",
    limit=25,
)
```

--------------------------------

### Basic Market Scan with Screener

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/screener

Use this snippet to perform a basic market scan with custom filters, field selection, and sorting. Ensure the `tv_scraper` library is installed.

```python
from tv_scraper import Screener

scraper = Screener()
result = scraper.get_screener(
    market="america",
    filters=[{"left": "close", "operation": "greater", "right": 100}],
    fields=["name", "close", "volume", "market_cap_basic"],
    sort_by="market_cap_basic",
    sort_order="desc",
    limit=25,
)

```

--------------------------------

### Get Forecast Data

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/forecast_streamer?q=

Retrieves analyst forecast data for a given stock symbol. This method is only available for stock instruments.

```APIDOC
## Get Forecast

### Description
Retrieves analyst forecast fields from TradingView quote updates for a specified stock symbol. This method is exclusively available for stock symbols.

### Method Signature
```python
get_forecast(exchange: str, symbol: str)
```

### Parameters
#### Path Parameters
- **exchange** (str) - Required - Use a supported exchange from Exchanges.
- **symbol** (str) - Required - Stock symbol slug such as `AAPL`.

### Notes
- The method verifies the symbol first and then checks the symbol type. If the instrument is not a stock, the call fails.
- The capture loop stops once all required keys are found or the packet limit is reached.
- Export runs only on full success.

### Output Keys
The `data` payload always uses these keys:
  * `revenue_currency`
  * `previous_close_price`
  * `average_price_target`
  * `highest_price_target`
  * `lowest_price_target`
  * `median_price_target`
  * `yearly_eps_data`
  * `quarterly_eps_data`
  * `yearly_revenue_data`
  * `quarterly_revenue_data`

### Data Structure
The `yearly_eps_data`, `quarterly_eps_data`, `yearly_revenue_data`, and `quarterly_revenue_data` fields are lists of row objects. Each row includes `Actual`, `Estimate`, `FiscalPeriod`, `IsReported`, and `Type`. `FiscalPeriod` is yearly (for example, `"2017"`) or quarterly (for example, `"2021-Q2"`) depending on the field.

### Example Usage
```python
from tv_scraper import ForecastStreamer

streamer = ForecastStreamer()
result = streamer.get_forecast(exchange="NASDAQ", symbol="AAPL")
```

### Error Handling
- If one or more required keys are still missing after capture, the method returns `status="failed"`.
- `data` is still included in the response.
- Missing keys are listed in the `error` field.
```

--------------------------------

### Initialize Scraper with Environment Variable Cookie

Source: https://smitkunpara.github.io/tv-scraper/latest/getting_cookies?q=

Initialize scrapers like Pine without explicitly passing the cookie, leveraging the TRADINGVIEW_COOKIE environment variable. Ensure the environment variable is set before running the script.

```python
from tv_scraper import Pine

pine = Pine()


```

--------------------------------

### Get Available Indicators

Source: https://smitkunpara.github.io/tv-scraper/latest/streaming/candle_streamer?q=

Retrieves a list of available indicator IDs that can be used when requesting candle data or real-time prices.

```python
result = CandleStreamer.get_available_indicators()
```

--------------------------------

### Get All Technical Indicators

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/technicals

Retrieve all available technical indicators for a given exchange, symbol, and timeframe by omitting the `technical_indicators` parameter.

```APIDOC
## Get All Technical Indicators

### Description
Fetches all available technical indicator values for a given exchange, symbol, and timeframe by omitting the `technical_indicators` parameter.

### Method
`get_technicals`

### Parameters
#### Path Parameters
- `exchange` (string) - Required - The stock exchange (e.g., "NASDAQ").
- `symbol` (string) - Required - The stock symbol (e.g., "AAPL").
- `timeframe` (string) - Required - The timeframe for the indicators (e.g., "1d").

### Request Example
```python
from tv_scraper import Technicals

scraper = Technicals()
result = scraper.get_technicals(
    exchange="NASDAQ",
    symbol="AAPL",
    timeframe="1d"
)
```

### Response
#### Success Response (200)
- `status` (string) - Indicates the success of the operation.
- `data` (object) - Contains all available technical indicator values.
- `metadata` (object) - Contains information about the request parameters.
- `warnings` (list) - Any warnings generated during the request.
- `error` (null) - Indicates no error occurred.

#### Response Example (truncated)
```json
{
    "status": "success",
    "data": {
        "Recommend.Other": 0.09090909090909091,
        "Recommend.All": 0.3787878787878788,
        "RSI": 54.36791522625663,
        "MACD.macd": -1.7690915227776713,
        "MACD.signal": -2.9115386038865543,
        ...
    },
    "metadata": {
        "exchange": "NASDAQ",
        "symbol": "AAPL",
        "timeframe": "1d",
    },
    "warnings": [],
    "error": null,
}
```
```

--------------------------------

### Fetch Options by Expiration

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/options

Use this snippet to retrieve option chain data for a specific expiration date. Ensure the `Options` class is imported and initialized.

```python
from tv_scraper import Options

scraper = Options()
result = scraper.get_options(
    exchange="BSE",
    symbol="SENSEX",
    expiration=20260219,
)
```

--------------------------------

### Invalid Field for Dividends

Source: https://smitkunpara.github.io/tv-scraper/latest/scrapers/calendar?q=

This example demonstrates an incorrect usage where a field not applicable to dividends is passed. This will result in an error or unexpected behavior.

```python
scraper.get_dividends(fields=["earnings_release_date"])

```

--------------------------------

### Create Feature Branch

Source: https://smitkunpara.github.io/tv-scraper/latest/contributing?q=

Create a new branch for your feature development.

```bash
git checkout -b feature/your-feature-name
```
Tokens:
Raw