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(provider='fmp')

---

Parameters

• standard
• finviz
• fmp
• nasdaq

Name	Type	Description	Default	Optional

Name	Type	Description	Default	Optional
metric	Literal['overview', 'valuation', 'financial', 'ownership', 'performance', 'technical']	The data group to return, default is 'overview'.	overview	True
exchange	Literal['all', 'amex', 'nasdaq', 'nyse']	Filter by exchange.	all	True
index	Literal['all', 'dow', 'nasdaq', 'sp500', 'russell']	Filter by index.	all	True
sector	Literal['all', 'energy', 'materials', 'industrials', 'consumer_cyclical', 'consumer_defensive', 'financial', 'healthcare', 'technology', 'communication_services', 'utilities', 'real_estate']	Filter by sector.	all	True
industry	str	Filter by industry.	all	True
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']	Filter by market cap.
Mega - > 200B
Large - 10B - 200B
Mid - 2B - 10B
Small - 300M - 2B
Micro - 50M - 300M
Nano - < 50M	all	True	None
recommendation	Literal['all', 'strong_buy', 'buy+', 'buy', 'hold+', 'hold', 'hold-', 'sell', 'sell-', 'strong_sell']	Filter by analyst recommendation.	all	True
signal	str	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 (contiunation)
wedge_down: downward trendline support and downward trendline resistance (reversal)
wedge_up: upward trendline support and upward trendline resistance (reversal)	None	True	['channel', 'channel_down', 'channel_up', 'double_bottom', 'double_top', 'downgrades', 'earnings_after', 'earnings_before', 'head_shoulders', 'head_shoulders_inverse', 'horizontal_sr', 'major_news', 'most_active', 'most_volatile', 'multiple_bottom', 'multiple_top', 'new_high', 'new_low', 'overbought', 'oversold', 'recent_insider_buying', 'recent_insider_selling', 'tl_resistance', 'tl_support', 'top_gainers', 'top_losers', 'triangle_ascending', 'triangle_descending', 'unusual_volume', 'upgrades', 'wedge', 'wedge_down', 'wedge_up']
preset	str	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) | None | True | None | | filters_dict | Union[Dict, str] | 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. | None | True | None | | limit | int | The number of data entries to return. | None | True | None |

Name	Type	Description	Default	Optional
mktcap_min	int	Filter by market cap greater than this value.	None	True
mktcap_max	int	Filter by market cap less than this value.	None	True
price_min	float	Filter by price greater than this value.	None	True
price_max	float	Filter by price less than this value.	None	True
beta_min	float	Filter by a beta greater than this value.	None	True
beta_max	float	Filter by a beta less than this value.	None	True
volume_min	int	Filter by volume greater than this value.	None	True
volume_max	int	Filter by volume less than this value.	None	True
dividend_min	float	Filter by dividend amount greater than this value.	None	True
dividend_max	float	Filter by dividend amount less than this value.	None	True
is_etf	bool	If true, returns only ETFs.	False	True
is_active	bool	If false, returns only inactive tickers.	True	True
sector	Literal['consumer_cyclical', 'energy', 'technology', 'industrials', 'financial_services', 'basic_materials', 'communication_services', 'consumer_defensive', 'healthcare', 'real_estate', 'utilities', 'industrial_goods', 'financial', 'services', 'conglomerates']	Filter by sector.	None	True
industry	str	Filter by industry.	None	True
country	str	Filter by country, as a two-letter country code.	None	True
exchange	Literal['amex', 'ams', 'ase', 'asx', 'ath', 'bme', 'bru', 'bud', 'bue', 'cai', 'cnq', 'cph', 'dfm', 'doh', 'etf', 'euronext', 'hel', 'hkse', 'ice', 'iob', 'ist', 'jkt', 'jnb', 'jpx', 'kls', 'koe', 'ksc', 'kuw', 'lse', 'mex', 'mutual_fund', 'nasdaq', 'neo', 'nse', 'nyse', 'nze', 'osl', 'otc', 'pnk', 'pra', 'ris', 'sao', 'sau', 'set', 'sgo', 'shh', 'shz', 'six', 'sto', 'tai', 'tlv', 'tsx', 'two', 'vie', 'wse', 'xetra']	Filter by exchange.	None	True
limit	int	Limit the number of results to return.	50000	True

Name	Type	Description	Default	Optional
exchange	Union[Union[Literal['all', 'nasdaq', 'nyse', 'amex'], str], List[Union[Literal['all', 'nasdaq', 'nyse', 'amex'], str]]]	Filter by exchange. Multiple items allowed for provider(s): nasdaq.	all	True
exsubcategory	Union[Union[Literal['all', 'ngs', 'ngm', 'ncm', 'adr'], str], List[Union[Literal['all', 'ngs', 'ngm', 'ncm', 'adr'], str]]]	Filter by exchange subcategory.
NGS - Nasdaq Global Select Market
NGM - Nasdaq Global Market
NCM - Nasdaq Capital Market
ADR - American Depository Receipt Multiple items allowed for provider(s): nasdaq.	all	True	None
mktcap	Union[Union[Literal['all', 'mega', 'large', 'mid', 'small', 'micro'], str], List[Union[Literal['all', 'mega', 'large', 'mid', 'small', 'micro'], str]]]	Filter by market cap.
Mega - > 200B
Large - 10B - 200B
Mid - 2B - 10B
Small - 300M - 2B
Micro - 50M - 300M Multiple items allowed for provider(s): nasdaq.	all	True	None
recommendation	Union[Union[Literal['all', 'strong_buy', 'buy', 'hold', 'sell', 'strong_sell'], str], List[Union[Literal['all', 'strong_buy', 'buy', 'hold', 'sell', 'strong_sell'], str]]]	Filter by consensus analyst action. Multiple items allowed for provider(s): nasdaq.	all	True
sector	Union[Union[Literal['all', 'energy', 'basic_materials', 'industrials', 'consumer_staples', 'consumer_discretionary', 'health_care', 'financial_services', 'technology', 'communication_services', 'utilities', 'real_estate'], str], List[Union[Literal['all', 'energy', 'basic_materials', 'industrials', 'consumer_staples', 'consumer_discretionary', 'health_care', 'financial_services', 'technology', 'communication_services', 'utilities', 'real_estate'], str]]]	Filter by sector. Multiple items allowed for provider(s): nasdaq.	all	True
region	Union[Union[Literal['all', 'africa', 'asia', 'australia_and_south_pacific', 'caribbean', 'europe', 'middle_east', 'north_america', 'south_america'], str], List[Union[Literal['all', 'africa', 'asia', 'australia_and_south_pacific', 'caribbean', 'europe', 'middle_east', 'north_america', 'south_america'], str]]]	Filter by region. Multiple items allowed for provider(s): nasdaq.	all	True
country	Union[Union[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'], str], List[Union[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'], str]]]	Filter by country. Multiple items allowed for provider(s): nasdaq.	all	True
limit	int	Limit the number of results to return.	None	True

---

Returns

OBBject
    results : List[EquityScreener]
        Serializable results.

    provider : Optional[Literal['finviz', 'fmp', 'nasdaq']]
        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

Name	Type	Description
symbol	str	Symbol representing the entity requested in the data.
name	str	Name of the company.

Name	Type	Description
symbol	str	Symbol representing the entity requested in the data.
name	str	Name of the company.
earnings_date	str	Earnings date, where 'a' and 'b' mean after and before market close, respectively.
country	str	Country of the company.
sector	str	Sector of the company.
industry	str	Industry of the company.
beta	float	Beta of the stock.
analyst_recommendation	float	Analyst's mean recommendation. (1=Buy 5=Sell).
market_cap	float	Market capitalization of the company.
price	float	Price of a share.
change_percent	float	Price change percentage.
change_from_open	float	Price change percentage, from the opening price.
gap	float	Price gap percentage, from the previous close.
volume	Union[float, int]	The trading volume.
volume_avg	Union[float, int]	3-month average daily volume.
volume_relative	float	Current volume relative to the average.
average_true_range	float	Average true range (14).
price_change_1W	float	One-week price return.
price_change_1M	float	One-month price return.
price_change_3M	float	Three-month price return.
price_change_6M	float	Six-month price return.
price_change_1Y	float	One-year price return.
price_change_YTD	float	Year-to-date price return.
volatility_1W	float	One-week volatility.
volatility_1M	float	One-month volatility.
year_high_percent	float	Percent difference from current price to the 52-week high.
year_low_percent	float	Percent difference from current price to the 52-week low.
sma20_percent	float	Percent difference from current price to the 20-day simple moving average.
sma50_percent	float	Percent difference from current price to the 50-day simple moving average.
sma200_percent	float	Percent difference from current price to the 200-day simple moving average.
rsi	float	Relative strength index (14).
shares_outstanding	Union[float, int]	Number of shares outstanding.
shares_float	Union[float, int]	Number of shares available to trade.
short_interest	float	Percent of float reported as short.
short_ratio	float	Short interest ratio
insider_ownership	float	Insider ownership as a percentage.
insider_ownership_change	float	6-month change in insider ownership percentage.
institutional_ownership	float	Institutional ownership as a percentage.
institutional_ownership_change	float	3-month change in institutional ownership percentage.
price_to_earnings	float	Price to earnings ratio.
forward_pe	float	Forward price to earnings ratio.
peg_ratio	float	Price/Earnings-To-Growth (PEG) ratio.
price_to_sales	float	Price to sales ratio.
price_to_book	float	Price to book ratio.
price_to_cash	float	Price to cash ratio.
price_to_fcf	float	Price to free cash flow ratio.
eps_growth_past_1Y	float	EPS growth for this year.
eps_growth_next_1Y	float	EPS growth next year.
eps_growth_past_5Y	float	EPS growth for the previous 5 years.
eps_growth_next_5Y	float	EPS growth for the next 5 years.
sales_growth_past_5Y	float	Sales growth for the previous 5 years.
dividend_yield	float	Annualized dividend yield.
return_on_assets	float	Return on assets.
return_on_equity	float	Return on equity.
return_on_investment	float	Return on investment.
current_ratio	float	Current ratio.
quick_ratio	float	Quick ratio.
long_term_debt_to_equity	float	Long term debt to equity ratio.
debt_to_equity	float	Total debt to equity ratio.
gross_margin	float	Gross margin.
operating_margin	float	Operating margin.
profit_margin	float	Profit margin.

Name	Type	Description
symbol	str	Symbol representing the entity requested in the data.
name	str	Name of the company.
market_cap	int	The market cap of ticker.
sector	str	The sector the ticker belongs to.
industry	str	The industry ticker belongs to.
beta	float	The beta of the ETF.
price	float	The current price.
last_annual_dividend	float	The last annual amount dividend paid.
volume	int	The current trading volume.
exchange	str	The exchange code the asset trades on.
exchange_name	str	The full name of the primary exchange.
country	str	The two-letter country abbreviation where the head office is located.
is_etf	Literal[True, False]	Whether the ticker is an ETF.
actively_trading	Literal[True, False]	Whether the ETF is actively trading.

Name	Type	Description
symbol	str	Symbol representing the entity requested in the data.
name	str	Name of the company.
last_price	float	Last sale price.
change	float	1-day change in price.
change_percent	float	1-day percent change in price.
market_cap	int	Market cap.