tradingview-screener-ts
Version:
TypeScript port of TradingView Screener with 100% Python parity - Based on the original Python library by shner-elmo (https://github.com/shner-elmo/TradingView-Screener)
283 lines • 9.64 kB
TypeScript
import { Column } from './column';
import { QueryDict, ScreenerDict, FilterOperationDict, OperationDict, RequestConfig, ScreenerDataResult } from './types/models';
/**
* Default range for query results
*/
export declare const DEFAULT_RANGE: [number, number];
/**
* TradingView scanner API URL template
*/
export declare const URL = "https://scanner.tradingview.com/{market}/scan";
/**
* Default HTTP headers for API requests
*/
export declare const HEADERS: Record<string, string>;
/**
* Combines multiple expressions with AND logic
* @param expressions - Filter expressions to combine
* @returns Combined operation dictionary
*/
export declare function And(...expressions: Array<FilterOperationDict | OperationDict>): OperationDict;
/**
* Combines multiple expressions with OR logic
* @param expressions - Filter expressions to combine
* @returns Combined operation dictionary
*/
export declare function Or(...expressions: Array<FilterOperationDict | OperationDict>): OperationDict;
/**
* This class allows you to perform SQL-like queries on the TradingView stock screener.
*
* The `Query` object represents a query that can be made to the official TradingView API, and it
* stores all the data as JSON internally.
*
* @example
* To perform a simple query all you have to do is:
* ```typescript
* import { Query } from 'tradingview-screener-ts';
*
* const result = await new Query().getScannerData();
* console.log(result);
* // {
* // totalCount: 18060,
* // data: [
* // { ticker: 'AMEX:SPY', name: 'SPY', close: 410.68, volume: 107367671, market_cap_basic: null },
* // { ticker: 'NASDAQ:QQQ', name: 'QQQ', close: 345.31, volume: 63475390, market_cap_basic: null },
* // // ... more rows
* // ]
* // }
* ```
*
* The `getScannerData()` method will return an object with `totalCount` (like a `COUNT(*)`) and
* `data` array containing the actual results.
*
* By default, the `Query` will select the columns: `name`, `close`, `volume`, `market_cap_basic`,
* but you can override that:
*
* @example
* ```typescript
* const result = await new Query()
* .select('open', 'high', 'low', 'VWAP', 'MACD.macd', 'RSI', 'Price to Earnings Ratio (TTM)')
* .getScannerData();
* ```
*
* You can find 250+ columns available in the TradingView documentation.
*
* Now let's do some queries using the `WHERE` statement, select all the stocks that the `close` is
* bigger or equal than 350:
*
* @example
* ```typescript
* import { Query, Column } from 'tradingview-screener-ts';
*
* const result = await new Query()
* .select('close', 'volume', '52 Week High')
* .where(new Column('close').gte(350))
* .getScannerData();
* ```
*
* You can even use other columns in these kind of operations:
*
* @example
* ```typescript
* const result = await new Query()
* .select('close', 'VWAP')
* .where(new Column('close').gte(new Column('VWAP')))
* .getScannerData();
* ```
*/
export declare class Query {
private query;
private url;
/**
* Creates a new Query instance with default configuration
*/
constructor();
/**
* Select specific columns to retrieve
* @param columns - Column names or Column instances to select
* @returns This Query instance for method chaining
*/
select(...columns: Array<Column | string>): this;
/**
* Filter screener results (expressions are joined with the AND operator)
* @param expressions - Filter expressions to apply
* @returns This Query instance for method chaining
*/
where(...expressions: FilterOperationDict[]): this;
/**
* Filter screener using AND/OR operators (nested expressions also allowed)
*
* Rules:
* 1. The argument passed to `where2()` **must** be wrapped in `And()` or `Or()`.
* 2. `And()` and `Or()` can accept one or more conditions as arguments.
* 3. Conditions can be simple (e.g., `new Column('field').eq('value')`) or complex, allowing nesting of `And()` and `Or()` to create intricate logical filters.
* 4. Unlike the `where()` method, which only supports chaining conditions with the `AND` operator, `where2()` allows mixing and nesting of `AND` and `OR` operators.
*
* @param operation - Operation dictionary with AND/OR logic
* @returns This Query instance for method chaining
*
* @example
* Combining conditions with `OR` and nested `AND`:
* ```typescript
* import { Query, And, Or, col } from 'tradingview-screener-ts';
*
* const result = await new Query()
* .select('type', 'typespecs')
* .where2(
* Or(
* And(col('type').eq('stock'), col('typespecs').has(['common', 'preferred'])),
* And(col('type').eq('fund'), col('typespecs').hasNoneOf(['etf'])),
* col('type').eq('dr')
* )
* )
* .getScannerData();
* ```
*/
where2(operation: OperationDict): this;
/**
* Applies sorting to the query results based on the specified column
* @param column - Column to sort by
* @param ascending - Sort order (true for ascending, false for descending)
* @param nullsFirst - Whether to place null values first
* @returns This Query instance for method chaining
*
* @example
* ```typescript
* new Query().orderBy('volume', false) // sort descending
* new Query().orderBy('close', true)
* new Query().orderBy('dividends_yield_current', false, false)
* ```
*/
orderBy(column: Column | string, ascending?: boolean, nullsFirst?: boolean): this;
/**
* Limit the number of results
* @param limit - Maximum number of results to return
* @returns This Query instance for method chaining
*/
limit(limit: number): this;
/**
* Skip a number of results (pagination)
* @param offset - Number of results to skip
* @returns This Query instance for method chaining
*/
offset(offset: number): this;
/**
* Set the markets to query
* @param markets - Market names to include
* @returns This Query instance for method chaining
*
* @example
* ```typescript
* // Single market
* new Query().setMarkets('italy')
*
* // Multiple markets
* new Query().setMarkets('america', 'israel', 'hongkong', 'switzerland')
*
* // Different asset classes
* new Query().setMarkets('cfd', 'crypto', 'forex', 'futures')
* ```
*/
setMarkets(...markets: string[]): this;
/**
* Set specific tickers to query
* @param tickers - Ticker symbols to include (format: 'EXCHANGE:SYMBOL')
* @returns This Query instance for method chaining
*
* @example
* ```typescript
* new Query().setTickers('NASDAQ:TSLA')
* new Query().setTickers('NYSE:GME', 'AMEX:SPY', 'MIL:RACE', 'HOSE:VIX')
* ```
*/
setTickers(...tickers: string[]): this;
/**
* Scan only equities that are in the given index (or indexes)
* @param indexes - Index symbols to filter by
* @returns This Query instance for method chaining
*
* @example
* ```typescript
* new Query().setIndex('SYML:SP;SPX')
* new Query().setIndex('SYML:NSE;NIFTY', 'SYML:TVC;UKX')
* ```
*/
setIndex(...indexes: string[]): this;
/**
* Set a custom property on the query
* @param key - Property key
* @param value - Property value
* @returns This Query instance for method chaining
*/
setProperty(key: string, value: any): this;
/**
* Perform a POST web-request and return the raw data from the API
* @param config - Additional request configuration
* @returns Raw API response
*
* @example
* ```typescript
* const rawData = await new Query()
* .select('close', 'volume')
* .limit(5)
* .getScannerDataRaw();
*
* console.log(rawData);
* // {
* // totalCount: 17559,
* // data: [
* // { s: 'NASDAQ:NVDA', d: [116.14, 312636630] },
* // { s: 'AMEX:SPY', d: [542.04, 52331224] },
* // // ...
* // ]
* // }
* ```
*/
getScannerDataRaw(config?: RequestConfig): Promise<ScreenerDict>;
/**
* Perform a POST web-request and return the data from the API as a structured result
* @param config - Additional request configuration
* @returns Structured result with totalCount and data array
*
* @example
* ```typescript
* const result = await new Query()
* .select('name', 'close', 'volume')
* .where(new Column('close').gte(100))
* .getScannerData();
*
* console.log(`Found ${result.totalCount} results`);
* result.data.forEach(row => {
* console.log(`${row.name}: $${row.close}`);
* });
* ```
*/
getScannerData(config?: RequestConfig): Promise<ScreenerDataResult>;
/**
* Create a copy of this Query
* @returns New Query instance with copied configuration
*/
copy(): Query;
/**
* Get the current query configuration
* @returns Current query dictionary
*/
getQuery(): QueryDict;
/**
* Get the current URL
* @returns Current API URL
*/
getUrl(): string;
/**
* String representation of the Query
* @returns Formatted string representation
*/
toString(): string;
/**
* Check equality with another Query
* @param other - Other Query to compare with
* @returns True if queries are equal
*/
equals(other: Query): boolean;
}
//# sourceMappingURL=query.d.ts.map