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
• yfinance

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
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
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
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
limit	int	The number of data entries to return.	None	True

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
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
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

Name	Type	Description	Default	Optional
country	str	Filter by country, as a two-letter country code. Default is, 'us'. Use, 'all', for all countries.	us	True
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']	Filter by exchange.	None	True
sector	Literal['basic_materials', 'communication_services', 'consumer_cyclical', 'consumer_defensive', 'energy', 'financial_services', 'healthcare', 'industrials', 'real_estate', 'technology', 'utilities']	Filter by sector.	None	True
industry	str	Filter by industry.	None	True
mktcap_min	int	Filter by market cap greater than this value. Default is 500M.	500000000	True
mktcap_max	int	Filter by market cap less than this value.	None	True
price_min	float	Filter by price greater than this value. Default is, 5	5	True
price_max	float	Filter by price less than this value.	None	True
volume_min	int	Filter by volume greater than this value. Default is, 10K	10000	True
volume_max	int	Filter by volume 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
limit	int	Limit the number of results returned. Default is, 200. Set to, 0, for all results.	200	True

---

Returns

OBBject
    results : List[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

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.

Name	Type	Description
symbol	str	Symbol representing the entity requested in the data.
name	str	Name of the company.
open	float	Open price for the day.
high	float	High price for the day.
low	float	Low price for the day.
previous_close	float	Previous close price.
ma50	float	50-day moving average.
ma200	float	200-day moving average.
year_high	float	52-week high.
year_low	float	52-week low.
market_cap	float	Market Cap.
shares_outstanding	float	Shares outstanding.
book_value	float	Book value per share.
price_to_book	float	Price to book ratio.
eps_ttm	float	Earnings per share over the trailing twelve months.
eps_forward	float	Forward earnings per share.
pe_forward	float	Forward price-to-earnings ratio.
dividend_yield	float	Trailing twelve month dividend yield.
exchange	str	Exchange where the stock is listed.
exchange_timezone	str	Timezone of the exchange.
earnings_date	datetime	Most recent earnings date.
currency	str	Currency of the price data.