nsetools

Important Usage Notes

• Educational Use Only: This library is intended for educational and informational purposes and does not provide financial or investment advice.
• Public Data Only: It retrieves only publicly available data from the official NSE website. It does not require authentication and does not scrape private or real-time tick-by-tick data.
• No Affiliation: This project is not affiliated with or endorsed by the National Stock Exchange of India (NSE).
• Liability: The software is provided "as is". The author assumes no liability for inaccuracies, disruptions, or financial losses resulting from its use.

Install the nsetools library using pip to begin extracting data from the National Stock Exchange (India).

pip install nsetools

Execute the test suite using the provided Makefile command.

make test

To develop with nsetools, clone the repository and use make dev to install the package in development mode along with its dependencies.

python -m venv nsetools-dev
cd nsetools-dev
source bin/activate
git clone https://github.com/vsjha18/nsetools.git
cd nsetools
make dev

To use the library, import the Nse class from nsetools and instantiate it. The nse object will serve as the primary interface for accessing Stock, Index, and Derivatives APIs.

from nsetools import Nse
se = Nse()

To interact with the National Stock Exchange (NSE) APIs, instantiate the Nse class. You can optionally provide a session_refresh_interval to manage connection timeouts by periodically refreshing the session.

Args:

• session_refresh_interval (int, optional): Time in seconds after which the session should be refreshed. Defaults to 120.

from nsetools import Nse

# Default initialization (120s refresh)
nse = Nse()

# Custom initialization
nse = Nse(session_refresh_interval=300)

Retrieve futures trading data using nse.get_future_quote(code, expiry_date=None).

• If expiry_date is None, it returns a list of data for all available expiries.
• If a specific expiry_date is provided (format: 'DD-Mon-YYYY'), it returns a single dict for that expiry.

# Get all expiries for RELIANCE
all_futures = nse.get_future_quote('RELIANCE')

# Get specific expiry
specific_future = nse.get_future_quote('RELIANCE', expiry_date='27-Mar-2025')

Retrieve real-time data for stocks with the highest gains or losses using nse.get_top_gainers(index=...) or nse.get_top_losers(index=...).

Supported index values include:

• "NIFTY" or "NIFTY 50"
• "BANKNIFTY" or "NIFTY BANK"
• "NIFTYNEXT50" or "NIFTY NEXT 50"
• "SECGTR20" (Securities > ₹20)
• "SECLWR20" (Securities < ₹20)
• "FNO" (Futures & Options)
• "ALL" (All Securities)

# Get top gainers for NIFTY
gainers = nse.get_top_gainers(index="NIFTY")

# Get top losers for all securities
losers = nse.get_top_losers(index="ALL")

Use nse.get_stock_quote_in_index(index="...", include_index=False) to fetch real-time quotes for all stocks within a specific index.

If include_index=True, the first item in the returned list will be the quote for the index itself. If False, the list contains only the constituent stock quotes.

# Get quotes for all stocks in NIFTY 50
quotes = nse.get_stock_quote_in_index("NIFTY 50", include_index=False)

Use nse.get_advances_declines(index='...') to get the count of advancing and declining stocks within a specific index. Returns a dictionary with advances and declines keys.

stats = nse.get_advances_declines("NIFTY BANK")
print(f"Advances: {stats['advances']}, Declines: {stats['declines']}")

Access index-level data through several methods:

• nse.get_index_list(): Returns a list of all available NSE index symbols.
• nse.get_index_quote(index="..."): Gets detailed quote info for a specific index (e.g., "NIFTY 50").
• nse.get_all_index_quote(): Fetches quotes for all indices in a single call.
• nse.get_stocks_in_index(index="..."): Returns a list of stock symbols that are constituents of the specified index.

# Get all index names
indices = nse.get_index_list()

# Get quote for NIFTY 50
quote = nse.get_index_quote("NIFTY 50")

# Get constituents of NIFTY BANK
constituents = nse.get_stocks_in_index("NIFTY BANK")

Identify stocks that have recently hit their 52-week price extremes using nse.get_52_week_high() or nse.get_52_week_low(). Both methods return a list[dict] containing details like symbol, company name, and the specific high/low values.

highs = nse.get_52_week_high()
for stock in highs:
    print(f"{stock['symbol']} hit {stock['new52WHL']}")