finviz-api
##########
*Unofficial Python API for FinViz*

.. image:: https://badge.fury.io/py/finviz.svg
    :target: https://badge.fury.io/py/finviz

.. image:: https://img.shields.io/badge/python-3.10+-blue.svg
    :target: https://www.python.org/downloads/

.. image:: https://pepy.tech/badge/finviz
    :target: https://pepy.tech/project/finviz

.. image:: https://github.com/mariostoev/finviz/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/mariostoev/finviz/actions


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 <CHANGELOG.md>`_ for full details.


Installation
============

.. code:: bash

    pip install finviz

Or install the latest development version:

.. code:: bash

    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.

.. _FinViz: https://finviz.com

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

.. code:: python

    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.

.. code:: python

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

.. code:: python

    # 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:**

.. code:: python

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


Individual Stock Functions
==========================

.. code:: python

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

.. code:: python

    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:

.. list-table::
   :header-rows: 1

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

.. code:: python

    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:

.. code:: python

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


Development
===========

.. code:: bash

    # 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!*

.. image:: https://user-images.githubusercontent.com/8982949/33011169-6da4af5e-cddd-11e7-94e5-a52d776b94ba.png
        :target: https://www.paypal.me/finvizapi


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