screener

Screen for companies meeting various criteria.

These criteria include market cap, price, beta, volume, and dividend yield.

Examples

from openbb import obb
obb.equity.screener()

Parameters

• standard
• finviz
• fmp
• nasdaq
• yfinance

metric: Literal['overview', 'valuation', 'financial', 'ownership', 'performance', 'technical'] | None
Default: overview
The data group to return, default is 'overview'.

exchange: Literal['all', 'amex', 'nasdaq', 'nyse'] | None
Default: all
Filter by exchange.

index: Literal['all', 'dow', 'nasdaq', 'sp500', 'russell'] | None
Default: all
Filter by index.

sector: Literal['all', 'energy', 'materials', 'industrials', 'consumer_cyclical', 'consumer_defensive', 'financial', 'healthcare', 'technology', 'communication_services', 'utilities', 'real_estate'] | None
Default: all
Filter by sector.

industry: str | None
Default: all
Filter by industry.

mktcap: Literal['all', 'mega', 'large', 'large_over', 'large_under', 'mid', 'mid_over', 'mid_under', 'small', 'small_over', 'small_under', 'micro', 'micro_over', 'micro_under', 'nano'] | None
Default: all

Description

Filter by market cap.
Mega - > 200B
Large - 10B - 200B
Mid - 2B - 10B
Small - 300M - 2B
Micro - 50M - 300M
Nano - < 50M

recommendation: Literal['all', 'strong_buy', 'buy+', 'buy', 'hold+', 'hold', 'hold-', 'sell', 'sell-', 'strong_sell'] | None
Default: all
Filter by analyst recommendation.

signal: str | None

Description

The Finviz screener signal to use. When no parameters are provided, the screener defaults to 'top_gainers'. Available signals are:
channel: both support and resistance trendlines are horizontal
channel_down: both support and resistance trendlines slope downward
channel_up: both support and resistance trendlines slope upward
double_bottom: stock with 'W' shape that indicates a bullish reversal in trend
double_top: stock with 'M' shape that indicates a bearish reversal in trend
downgrades: stocks downgraded by analysts today
earnings_after: companies reporting earnings today, after market close
earnings_before: companies reporting earnings today, before market open
head_shoulders: chart formation that predicts a bullish-to-bearish trend reversal
head_shoulders_inverse: chart formation that predicts a bearish-to-bullish trend reversal
horizontal_sr: horizontal channel of price range between support and resistance trendlines
major_news: stocks with the highest news coverage today
most_active: stocks with the highest trading volume today
most_volatile: stocks with the highest widest high/low trading range today
multiple_bottom: same as double_bottom hitting more lows
multiple_top: same as double_top hitting more highs
new_high: stocks making 52-week high today
new_low: stocks making 52-week low today
overbought: stock is becoming overvalued and may experience a pullback.
oversold: oversold stocks may represent a buying opportunity for investors
recent_insider_buying: stocks with recent insider buying activity
recent_insider_selling: stocks with recent insider selling activity
tl_resistance: once a rising trendline is broken
tl_support: once a falling trendline is broken
top_gainers: stocks with the highest price gain percent today
top_losers: stocks with the highest price percent loss today
triangle_ascending: upward trendline support and horizontal trendline resistance
triangle_descending: horizontal trendline support and downward trendline resistance
unusual_volume: stocks with unusually high volume today - the highest relative volume ratio
upgrades: stocks upgraded by analysts today
wedge: upward trendline support, downward trendline resistance (continuation)
wedge_down: downward trendline support and downward trendline resistance (reversal)
wedge_up: upward trendline support and upward trendline resistance (reversal)

preset: str | None

Description

A configured preset file to use for the query. This overrides all other query parameters except 'metric', and 'limit'. Presets (.ini text files) can be created and modified in the '~/OpenBBUserData/finviz/presets' directory. If the path does not exist, it will be created and populated with the default presets on the first run. Refer to the file, 'screener_template.ini', for the format and options.

Note: Syntax of parameters in preset files must follow the template file exactly - i.e, Analyst Recom. = Strong Buy (1)

filters_dict: dict | str | None
A formatted dictionary, or serialized JSON string, of additional filters to apply to the query. This parameter can be used as an alternative to preset files, and is ignored when a preset is supplied. Invalid entries will raise an error. Syntax should follow the 'screener_template.ini' file.

limit: int | None
The number of data entries to return.

mktcap_min: int | None
Filter by market cap greater than this value.

mktcap_max: int | None
Filter by market cap less than this value.

price_min: float | None
Filter by price greater than this value.

price_max: float | None
Filter by price less than this value.

beta_min: float | None
Filter by a beta greater than this value.

beta_max: float | None
Filter by a beta less than this value.

volume_min: int | None
Filter by volume greater than this value.

volume_max: int | None
Filter by volume less than this value.

dividend_min: float | None
Filter by dividend amount greater than this value.

dividend_max: float | None
Filter by dividend amount less than this value.

sector: Literal['consumer_cyclical', 'energy', 'technology', 'industrials', 'financial_services', 'basic_materials', 'communication_services', 'consumer_defensive', 'healthcare', 'real_estate', 'utilities', 'industrial_goods', 'financial', 'services'] | None
Filter by sector.

industry: str | None
Filter by industry.

country: Country | None
Filter by country. Accepts ISO 3166-1 alpha-2 codes (e.g., 'US', 'DE'), alpha-3 codes (e.g., 'USA'), or country names (e.g., 'United States', 'united_states').

exchange: Exchange | None
Filter by exchange. Accepts ISO 10383 MIC codes (e.g., 'XNAS', 'XNYS'), acronyms (e.g., 'NASDAQ', 'NYSE'), or exchange names (e.g., 'New York Stock Exchange').

is_etf: bool | None
If true, includes ETFs.

is_active: bool | None
If false, returns only inactive tickers.

is_fund: bool | None
If true, includes funds.

all_share_classes: bool | None
If true, includes all share classes of a equity.

limit: int | None
Default: 50000
Limit the number of results to return.

exchange: Literal['all', 'nasdaq', 'nyse', 'amex'] | None
Default: all
Filter by exchange.

exsubcategory: Literal['all', 'ngs', 'ngm', 'ncm', 'adr'] | None
Default: all

Description

Filter by exchange subcategory.

• NGS - Nasdaq Global Select Market
  
• NGM - Nasdaq Global Market
  
• NCM - Nasdaq Capital Market
  
• ADR - American Depository Receipt
  

mktcap: Literal['all', 'mega', 'large', 'mid', 'small', 'micro'] | None
Default: all

Description

Filter by market cap.

• Mega - > 200B
  
• Large - 10B - 200B
  
• Mid - 2B - 10B
  
• Small - 300M - 2B
  
• Micro - 50M - 300M
  

recommendation: Literal['all', 'strong_buy', 'buy', 'hold', 'sell', 'strong_sell'] | None
Default: all
Filter by consensus analyst action.

sector: Literal['all', 'energy', 'basic_materials', 'industrials', 'consumer_staples', 'consumer_discretionary', 'health_care', 'financial_services', 'technology', 'communication_services', 'utilities', 'real_estate'] | None
Default: all
Filter by sector.

region: Literal['all', 'africa', 'asia', 'australia_and_south_pacific', 'caribbean', 'europe', 'middle_east', 'north_america', 'south_america'] | None
Default: all
Filter by region.

country: Literal['all', 'argentina', 'armenia', 'australia', 'austria', 'belgium', 'bermuda', 'brazil', 'canada', 'cayman_islands', 'chile', 'colombia', 'costa_rica', 'curacao', 'cyprus', 'denmark', 'finland', 'france', 'germany', 'greece', 'guernsey', 'hong_kong', 'india', 'indonesia', 'ireland', 'isle_of_man', 'israel', 'italy', 'japan', 'jersey', 'luxembourg', 'macau', 'mexico', 'monaco', 'netherlands', 'norway', 'panama', 'peru', 'philippines', 'puerto_rico', 'russia', 'singapore', 'south_africa', 'south_korea', 'spain', 'sweden', 'switzerland', 'taiwan', 'turkey', 'united_kingdom', 'united_states', 'usa'] | None
Default: all
Filter by country. Accepts country names, ISO 3166-1 alpha-2/alpha-3 codes, or 'all' for all countries. Multiple comma-separated values allowed.

limit: int | None
Limit the number of results to return.

country: str | None
Default: us
Filter by country. Accepts ISO 3166-1 alpha-2 codes (e.g., 'US', 'DE'), alpha-3 codes (e.g., 'USA'), country names (e.g., 'United States'), or 'all' for all countries.

exchange: Literal['ams', 'aqs', 'ase', 'asx', 'ath', 'ber', 'bru', 'bse', 'bts', 'bud', 'bue', 'bvb', 'bvc', 'ccs', 'cnq', 'cph', 'cxe', 'dfm', 'doh', 'dus', 'ebs', 'fka', 'fra', 'ger', 'ham', 'han', 'hel', 'hkg', 'ice', 'iob', 'ise', 'ist', 'jkt', 'jnb', 'jpx', 'kls', 'kuw', 'lis', 'lit', 'lse', 'mce', 'mex', 'mil', 'mun', 'ncm', 'neo', 'ngm', 'nms', 'nsi', 'nyq', 'nze', 'oem', 'oqb', 'oqx', 'osl', 'par', 'pnk', 'pra', 'ris', 'sau', 'ses', 'set', 'sgo', 'shh', 'shz', 'sto', 'stu', 'tai', 'tal', 'tlv', 'tor', 'two', 'van', 'vie', 'vse', 'wse'] | None
Filter by exchange.

sector: Literal['basic_materials', 'communication_services', 'consumer_cyclical', 'consumer_defensive', 'energy', 'financial_services', 'healthcare', 'industrials', 'real_estate', 'technology', 'utilities'] | None
Filter by sector.

industry: str | None
Filter by industry.

mktcap_min: int | None
Default: 500000000
Filter by market cap greater than this value. Default is 500M.

mktcap_max: int | None
Filter by market cap less than this value.

price_min: float | None
Default: 5
Filter by price greater than this value. Default is, 5

price_max: float | None
Filter by price less than this value.

volume_min: int | None
Default: 10000
Filter by volume greater than this value. Default is, 10K

volume_max: int | None
Filter by volume less than this value.

beta_min: float | None
Filter by a beta greater than this value.

beta_max: float | None
Filter by a beta less than this value.

limit: int | None
Default: 200
Limit the number of results returned. Default is, 200. Set to, 0, for all results.

---

Returns

results: EquityScreener

Serializable results.

provider: Optional[Literal['finviz', 'fmp', 'nasdaq', 'yfinance']]

Provider name.

warnings: Optional[list[Warning_]]

list of warnings.

chart: Optional[Chart]

Chart object.

extra: dict[str, Any]

Extra info.

---

Data

• standard
• finviz
• fmp
• nasdaq
• yfinance

symbol: str
Symbol representing the entity requested in the data.

name: str | None
Name of the company.

symbol: str
Symbol representing the entity requested in the data.

name: str | None
Name of the company.

earnings_date: str | None
Earnings date, where 'a' and 'b' mean after and before market close, respectively.

country: str | None
Country of the company.

sector: str | None
Sector of the company.

industry: str | None
Industry of the company.

beta: float | None
Beta of the stock.

analyst_recommendation: float | None
Analyst's mean recommendation. (1=Buy 5=Sell).

market_cap: float | None
Market capitalization of the company.

price: float | None
Price of a share.

change_percent: float | None
Price change percentage.

change_from_open: float | None
Price change percentage, from the opening price.

gap: float | None
Price gap percentage, from the previous close.

volume: int | float | None
The trading volume.

volume_avg: int | float | None
3-month average daily volume.

volume_relative: float | None
Current volume relative to the average.

average_true_range: float | None
Average true range (14).

price_change_1w: float | None
One-week price return.

price_change_1m: float | None
One-month price return.

price_change_3m: float | None
Three-month price return.

price_change_6m: float | None
Six-month price return.

price_change_1y: float | None
One-year price return.

price_change_ytd: float | None
Year-to-date price return.

volatility_1w: float | None
One-week volatility.

volatility_1m: float | None
One-month volatility.

year_high_percent: float | None
Percent difference from current price to the 52-week high.

year_low_percent: float | None
Percent difference from current price to the 52-week low.

sma20_percent: float | None
Percent difference from current price to the 20-day simple moving average.

sma50_percent: float | None
Percent difference from current price to the 50-day simple moving average.

sma200_percent: float | None
Percent difference from current price to the 200-day simple moving average.

rsi: float | None
Relative strength index (14).

shares_outstanding: int | float | None
Number of shares outstanding.

shares_float: int | float | None
Number of shares available to trade.

short_interest: float | None
Percent of float reported as short.

short_ratio: float | None
Short interest ratio

insider_ownership: float | None
Insider ownership as a percentage.

insider_ownership_change: float | None
6-month change in insider ownership percentage.

institutional_ownership: float | None
Institutional ownership as a percentage.

institutional_ownership_change: float | None
3-month change in institutional ownership percentage.

price_to_earnings: float | None
Price to earnings ratio.

forward_pe: float | None
Forward price to earnings ratio.

peg_ratio: float | None
Price/Earnings-To-Growth (PEG) ratio.

price_to_sales: float | None
Price to sales ratio.

price_to_book: float | None
Price to book ratio.

price_to_cash: float | None
Price to cash ratio.

price_to_fcf: float | None
Price to free cash flow ratio.

eps_growth_past_1y: float | None
EPS growth for this year.

eps_growth_next_1y: float | None
EPS growth next year.

eps_growth_past_5y: float | None
EPS growth for the previous 5 years.

eps_growth_next_5y: float | None
EPS growth for the next 5 years.

sales_growth_past_5y: float | None
Sales growth for the previous 5 years.

dividend_yield: float | None
Annualized dividend yield.

return_on_assets: float | None
Return on assets.

return_on_equity: float | None
Return on equity.

return_on_investment: float | None
Return on investment.

current_ratio: float | None
Current ratio.

quick_ratio: float | None
Quick ratio.

long_term_debt_to_equity: float | None
Long term debt to equity ratio.

debt_to_equity: float | None
Total debt to equity ratio.

gross_margin: float | None
Gross margin.

operating_margin: float | None
Operating margin.

profit_margin: float | None
Profit margin.

symbol: str
Symbol representing the entity requested in the data.

name: str | None
Name of the company.

market_cap: int | None
The market cap of ticker.

sector: str | None
The sector the ticker belongs to.

industry: str | None
The industry ticker belongs to.

beta: float | None
The beta of the ETF.

price: float | None
The current price.

last_annual_dividend: float | None
The last annual amount dividend paid.

volume: int | None
The current trading volume.

exchange: str | None
The exchange code the asset trades on.

exchange_name: str | None
The full name of the primary exchange.

country: str | None
The two-letter country abbreviation where the head office is located.

is_etf: bool | None
Whether the ticker is an ETF.

is_fund: bool | None
Whether the ticker is a fund.

actively_trading: bool | None
Whether the ETF is actively trading.

symbol: str
Symbol representing the entity requested in the data.

name: str | None
Name of the company.

last_price: float
Last sale price.

change: float | None
1-day change in price.

change_percent: float | None
1-day percent change in price.

market_cap: int | None
Market cap.

symbol: str
Symbol representing the entity requested in the data.

name: str | None
Name of the company.

open: float | None
Open price for the day.

high: float | None
High price for the day.

low: float | None
Low price for the day.

previous_close: float | None
Previous close price.

ma50: float | None
50-day moving average.

ma200: float | None
200-day moving average.

year_high: float | None
52-week high.

year_low: float | None
52-week low.

market_cap: float | None
Market Cap.

shares_outstanding: float | None
Shares outstanding.

book_value: float | None
Book value per share.

price_to_book: float | None
Price to book ratio.

eps_ttm: float | None
Earnings per share over the trailing twelve months.

eps_forward: float | None
Forward earnings per share.

pe_forward: float | None
Forward price-to-earnings ratio.

dividend_yield: float | None
Trailing twelve month dividend yield.

exchange: str | None
Exchange where the stock is listed.

exchange_timezone: str | None
Timezone of the exchange.

earnings_date: datetime | None
Most recent earnings date.

currency: str | None
Currency of the price data.