finviz-api

Unofficial Python API for FinViz

What's New in v2.0

v2.0.0 is a major update that fixes all scraping issues caused by FinViz website changes:

Fixed get_stock() - now returns 90+ data points
Fixed Screener - table parsing and header extraction
Fixed get_news() - handles new timestamp formats
Fixed get_insider() - supports new table structure
Fixed get_analyst_price_targets() - updated selectors
Python 3.10+ required (dropped 3.9 support)
Comprehensive test suite with real API testing

See CHANGELOG.md for full details.

Installation

pip install finviz

Or install the latest development version:

pip install git+https://github.com/mariostoev/finviz@v2-development

What is Finviz?

FinViz aims to make market information accessible and provides a lot of data in visual snapshots, allowing traders and investors to quickly find the stock, future or forex pair they are looking for. The site provides advanced screeners, market maps, analysis, comparative tools, and charts.

Important Information

Any quotes data displayed on finviz.com is delayed by 15 minutes for NASDAQ, and 20 minutes for NYSE and AMEX. This API should NOT be used for live trading, it's main purpose is financial analysis, research, and data scraping.

Quick Start

import finviz

# Get stock data
stock = finviz.get_stock('AAPL')
print(stock['Price'], stock['P/E'], stock['Market Cap'])

# Get news
news = finviz.get_news('AAPL')
for timestamp, headline, url, source in news[:5]:
    print(f"{timestamp} - {headline} ({source})")

# Get insider transactions
insiders = finviz.get_insider('AAPL')
for trade in insiders[:3]:
    print(trade['Insider Trading'], trade['Transaction'], trade['Value ($)'])

# Get analyst price targets
targets = finviz.get_analyst_price_targets('AAPL')
for target in targets:
    print(target['analyst'], target['rating'], target.get('target_to'))

Using Screener

The Screener allows you to filter stocks based on various criteria. You can either build filters programmatically or copy them from the FinViz website URL.

from finviz.screener import Screener

# Screen for large-cap NASDAQ stocks in the S&P 500
filters = ['exch_nasd', 'idx_sp500', 'cap_largeover']
stock_list = Screener(filters=filters, table='Overview', order='price')

print(f"Found {len(stock_list)} stocks")

for stock in stock_list[:10]:
    print(stock['Ticker'], stock['Company'], stock['Market Cap'])

# Export to CSV
stock_list.to_csv("stocks.csv")

# Export to SQLite
stock_list.to_sqlite("stocks.sqlite3")

# Export to pandas DataFrame (requires pandas)
df = stock_list.to_dataframe()

Available Tables:

Overview - Basic company info, market cap, price
Valuation - P/E, P/S, P/B, PEG ratios
Financial - ROA, ROE, ROI, margins
Ownership - Insider/institutional ownership, short interest
Performance - Price performance across timeframes
Technical - RSI, SMA, volatility, beta

Initialize from URL:

# Copy filters directly from FinViz website URL
url = "https://finviz.com/screener.ashx?v=111&f=cap_largeover,exch_nasd&o=-marketcap"
stock_list = Screener.init_from_url(url)

Get Available Filters:

# Get all available filter options
filters = Screener.load_filter_dict()
print(filters.keys())  # ['Exchange', 'Index', 'Sector', 'Industry', ...]

Individual Stock Functions

import finviz

# Comprehensive stock data (90+ metrics)
stock = finviz.get_stock('AAPL')
# Returns: {'Ticker': 'AAPL', 'Company': 'Apple Inc', 'Sector': 'Technology',
#           'P/E': '34.26', 'Market Cap': '3755.76B', 'Price': '255.53', ...}

# Recent news with timestamps
news = finviz.get_news('AAPL')
# Returns: [('2024-01-15 12:00', 'Headline...', 'https://...', 'MarketWatch'), ...]

# Insider trading activity
insiders = finviz.get_insider('AAPL')
# Returns: [{'Insider Trading': 'COOK TIMOTHY D', 'Relationship': 'CEO',
#            'Transaction': 'Sale', 'Value ($)': '41,530,891', ...}, ...]

# Analyst ratings and price targets
targets = finviz.get_analyst_price_targets('AAPL', last_ratings=10)
# Returns: [{'date': '2024-01-09', 'analyst': 'Morgan Stanley',
#            'rating': 'Overweight', 'target_from': 200, 'target_to': 220}, ...]

# All market news (not ticker-specific)
all_news = finviz.get_all_news()

Using Portfolio

from finviz.portfolio import Portfolio

portfolio = Portfolio('<email>', '<password>', '<portfolio-name>')
print(portfolio)

# Create portfolio from CSV
portfolio.create_portfolio('My Portfolio', 'positions.csv')

CSV format for portfolio import:

Ticker	Transaction	Date (Opt.)	Shares	Price (Opt.)
AAPL	1	05-25-2024	34	185.50
NVDA	1		100

Transaction: 1 = Buy, 2 = Sell. Empty optional fields use today's data.

Downloading Charts

stock_list.get_charts(period='d', chart_type='c', size='l', ta='1')

# period: 'd' (daily), 'w' (weekly), 'm' (monthly)
# chart_type: 'c' (candle), 'l' (line)
# size: 's' (small), 'l' (large)
# ta: '1' (show technical analysis), '0' (hide)

Configuration

Environment Variables:

DISABLE_TQDM=1 - Disable progress bars

Async Support:

The Screener supports async requests for faster data fetching:

stock_list = Screener(filters=filters, request_method="async")

Development

# Clone and install in development mode
git clone https://github.com/mariostoev/finviz
cd finviz
pip install -e ".[dev]"

# Run tests
pytest finviz/tests/ -v

# Run tests (skip slow ones)
pytest finviz/tests/ -v -m "not slow"

You can also buy me a coffee!

https://user-images.githubusercontent.com/8982949/33011169-6da4af5e-cddd-11e7-94e5-a52d776b94ba.png

Disclaimer

Using this library to acquire data from FinViz may be against their Terms of Service. Use it responsibly and at your own risk. This library is built for educational purposes.

finviz