Special Functions

These are very unusual functions which is first time having python wrapper on them.

The Results API

nseindia.com/companies-listing/corporate-filings-financial-results

The API looks like this –

nseindia.com/api/corporates-financial-results?index=equities&period=Quarterly(opens new window)

index has three types:

equities
debt
sme

period has four types:

Quarterly
Annual
Half-Yearly
Others

Usage:

				
					nse_results(index,period)

Default Value of index is equities and period is Quarterly in nse_results() function.

Example Usage:

				
					nse_results()
nse_results("equities","Others")

The variable inp is used in many places in this documentation. So, Let’s highlight it.

The Holiday API

There are two types –

Here is how to use the function

				
					nse_holidays(type)

or,

				
					nse_holidays(type)

type = trading or clearing. By default, trading will be selected.

Here is how to see the holidays of FNOs –

				
					holiday_master(type)

type = trading or clearing. By default, trading will be selected.

Here is how to see the holidays of FNOs –

				
					print(pd.json_normalize(nse_holidays()['FO']))

The Event Calendar API

nseindia.com/companies-listing/corporate-filings-event-calendar(opens new window)

API Link: https://www.nseindia.com/api/event-calendar

Example Usage:

				
					nse_events()

TIP

You can do a cross search between FNO companies and the companies listed here.

The Past Results API

nseindia.com/companies-listing/corporate-filings-financial-results-comparision(opens new window)

API Link: nseindia.com/api/results-comparision?symbol=JUSTDIAL

Example Usage:

				
					print(nse_past_results('JUSTDIAL'))

The Block Deals API

https://www.nseindia.com/market-data/block-deal-watch(opens new window)

API Link: https://nseindia.com/api/block-deal

				
					print(nse_blockdeal())

The Market Status API

Although We have a function that merely checks if we are in market time but this API Endpoint comes from NSE.

API Link: https://nseindia.com/api/marketStatus

Example Usage:

				
					print(nse_marketStatus())

The NSE Circular API

There are two APIs that fetch NSE Circular. One that truncates to the latest data and another that shows all the circulars.

Example Usage:

				
					print(nse_circular("latest"))

This will show the NSE’s latest circulars.

API Link: https://www.nseindia.com/api/latest-circular

				
					print(nse_circular("all"))

This will show the NSE’s all circulars.

API Link: https://www.nseindia.com/api/circulars

The FII/DII API

It fetches data of FII/DII in both Pandas and raw mode. By “raw”, it means You get the usual List format.

https://www.nseindia.com/reports/fii-dii

Example Usage:

				
					print(nse_fiidii())

Output:

				
					category         date buyValue sellValue netValue
0     DII **  28-May-2021  6440.88   5165.66  1275.22
1  FII/FPI *  28-May-2021  5917.71   5004.12   913.59

If You want the output in List mode directly. Use –

				
					print(nse_fiidii("list"))

Output:

				
					[{'category': 'DII **', 'date': '28-May-2021', 'buyValue': '6440.88', 'sellValue': '5165.66', 'netValue': '1275.22'}, {'category': 'FII/FPI *', 'date': '28-May-2021', 'buyValue': '5917.71', 'sellValue': '5004.12', 'netValue': '913.59'}]

In case Pandas throws error, It will come as output default.

The Beta API

Beta is a coefficient is a measure of its volatility over time compared to a market benchmark. Market benchmark has a beta of 1. Shortly, if volatility is 1.5 it means it is 50% more volatile than the market.

You can read here about more details on the construction and working of this API here – How to find the beta of Indian stocks using Python?

Syntax:

				
					get_beta(symbol,days=365,symbol2="NIFTY 50")

symbol – The stock/index of whose beta has to be checked.
days – Time period of comparison. It’s optional with a default value of 365.
symbol2 – The stock/index against which beta has to be checked. It’s optional with a default value of NIFTY 50.

Example 1:

This will run a for loop on all FNO stocks and breaks the loop on first stock’s output.

				
					for x in fnolist():
    try:
        print(x+" : "+str(get_beta(x,255)))
        break
        #Remove break if you want to print whole list
    except:
        pass

Output:

				
					TORNTPHARM : -0.168

Example 2:

The first function is checking NIFTY’s beta against NIFTY Bank.
The second function is checking NIFTY Bank’s beta against NIFTY

				
					#NIFTY Against NIFTY Bank
x = "NIFTY 50"
print(x+" : "+str(get_beta(x,255,"NIFTY BANK")))

#NIFTY Bank Against NIFTY
x = "NIFTY BANK"
print(x+" : "+str(get_beta(x,255)))

Output:

				
					NIFTY 50 : 0.55
NIFTY BANK : 1.395

Note – We used 255 as Number of Days because it is globally assumed that, there are 255 trading days. For near-term correlation, feel free to change the values.

The NSE PreOpen API

Command:

				
					nse_preopen(key,type)

Variations:

				
					key = "NIFTY" (default)
key = "BANKNIFTY"
key = "SME"
key = "FO"
key = "OTHERS"
key = "ALL"

type = "raw"
type = "pandas" (default)

Example 1:

				
					payload=nse_preopen("FO","raw")
print(payload) # It will print raw JSON
print(payload["advances"])
print(payload["declines"])
print(payload["unchanged"])

Example 2:

				
					payload=nse_preopen("FO","pandas") # It will post Pandas DataFrame

The NSE PreOpen Movers API

Command:

				
					nse_preopen_movers(key="FO",filter=1.5)

key is the same as just pasted above in the NSE Pre openc function.
filter is where you can choose how much gap up or down.

Usage:

				
					gainers,movers=nse_preopen_movers("NIFTY")
print(gainers)
print(movers)

This function is coded to avoid the usage of numpy library. You can read about this discussion here.

The NSE Most Active API

Command:

				
					nse_most_active(type="securities",sort="value")

Variations:

				
					type = "securities" (default)
type = "etf"
type = "sme"

sort = "volume"
sort = "value" (default)

Let’s take the example with the default type which is securities. You can find two things with this API in that case –

Most Active Securities by Volume
Most Active Securities by Values

This function is coded as a helper function to the query of How can I get the top 20 most liquid F&O stocks from NSE?

The StockList API

Command:

				
					nse_eq_symbols()

It will paste the entire codes of all equities in a single list. Right now (22-08-2023), It will post 1898 such codes. This function is coded as a helper function to the query of [Feature Request] StockList API

The NSE FNO Pariticipant Wise OI API

Command:

				
					get_fao_participant_oi(date)

The date should in a string format. Here you can see an example –

Example Usage:

				
					get_fao_participant_oi("04-06-2021")

It will give the Participant wise Open Interest in that Date above. The output will look like –

				
						Participant wise Open Interest (no. of contracts) in Equity Derivatives as on Jun 04,2021	Unnamed: 1	Unnamed: 2	Unnamed: 3	Unnamed: 4	Unnamed: 5	Unnamed: 6	Unnamed: 7	Unnamed: 8	Unnamed: 9	Unnamed: 10	Unnamed: 11	Unnamed: 12	Unnamed: 13	Unnamed: 14
0	Client Type	Future Index Long	Future Index Short	Future Stock Long	Future Stock Short\t	Option Index Call Long	Option Index Put Long	Option Index Call Short	Option Index Put Short	Option Stock Call Long	Option Stock Put Long	Option Stock Call Short	Option Stock Put Short	Total Long Contracts\t	Total Short Contracts
1	Client	115751	150820	1067753	165524	983422	884125	1006084	1087839	726845	226208	425543	323856	4004104	3159666
2	DII	2176	41572	33248	1082528	267	44771	0	0	0	0	49490	0	80462	1173590
3	FII	99389	21814	686884	686197	250553	316276	161235	169809	51329	58603	89957	46531	1463034	1175543
4	Pro	19346	22456	232887	86523	321284	342464	388207	329988	157826	213394	371010	127818	1287201	1326002
5	TOTAL	236662	236662	2020772	2020772	1555526	1587636	1555526	1587636	936000	498205	936000	498205	6834801	6834801

This function is coded as a helper function to the query of [Feature Request] NSE FNO Participant Wise OI

Dividend Timeline API

Updated version of the old nsetools-style dividend lookup. This was actually documented on this site for a while before it existed in the code — calling it used to raise AttributeError: module 'nsepython' has no attribute 'dividend_timeline'. It’s implemented for real now, built on top of NSE’s /api/top-corp-info endpoint (the same one the Shareholding Pattern API below uses), filtered down to just the dividend-purpose corporate actions. See GitHub issue #75.

Usage:

				
					dividend_timeline(symbol)

Example Usage:

				
					print(dividend_timeline("INFY"))

Output:

				
					  symbol       exdate                                                                               purpose
0   INFY  10-Jun-2026                                                            Dividend - Rs 25 Per Share
1   INFY  27-Oct-2025                                                    Interim Dividend - Rs 23 Per Share
2   INFY  30-May-2025                                                            Dividend - Rs 22 Per Share
3   INFY  29-Oct-2024                                                    Interim Dividend - Rs 21 Per Share
4   INFY  31-May-2024  Annual General Meeting/Special Dividend - Rs 8 Per Share /Dividend - Rs 20 Per Share
5   INFY  25-Oct-2023                                                    Interim Dividend - Rs 18 Per Share

Returns a Pandas DataFrame, newest ex-date first. purpose is NSE’s own raw corporate-action text — parse the rupee amount out of it yourself if you need it as a number, the format isn’t fully consistent symbol to symbol.

Shareholding Pattern API

Same backstory as dividend_timeline() above — documented, not implemented, now fixed (issue #75). Pulls the shareholding-pattern history (Promoter & Promoter Group / Public / Shares held by Employee Trusts / Total) out of the same /api/top-corp-info endpoint, one row per filing date, newest filing first.

Usage:

				
					share_holding(symbol)

Example Usage:

				
					print(share_holding("INFY"))

Output:

				
					          date Promoter & Promoter Group Public Shares held by Employee Trusts   Total
0  30-Jun-2026                     13.82  85.97                           0.21  100.00
1  31-Mar-2026                     14.38  85.38                           0.23  100.00
2  31-Dec-2025                     14.52  85.24                           0.24  100.00
3  04-Dec-2025                     14.55  85.21                           0.24  100.00

Column names come straight from NSE’s own category labels, so they can vary slightly between companies (e.g. some don’t have an Employee Trust row at all) — check .columns on the returned DataFrame rather than hardcoding them.

Annual Reports API

Forum feature request (topic 1459), new in v2.100. Lists a listed company’s annual reports with direct PDF/zip download links, built on NSE’s /api/annual-reports endpoint — a plain metadata+link listing, not part of the Akamai-walled historical/* family, so it’s reliable. year_from/year_to filter client-side on the report’s fromYr (NSE’s own API has no year-range parameter; it always returns the full available history — commonly 15–20+ years for large-cap companies).

Usage:

				
					nse_annual_reports(symbol, year_from=None, year_to=None, index="equities")

Example Usage:

				
					print(nse_annual_reports("RELIANCE", year_from=2022))

Output:

				
					                   companyName  ... attFileSize
0  Reliance Industries Limited  ...    10.50 MB
1  Reliance Industries Limited  ...         NaN
2  Reliance Industries Limited  ...         NaN
3  Reliance Industries Limited  ...         NaN

[4 rows x 9 columns]

Returns a Pandas DataFrame, columns companyName, fromYr, toYr, submission_type, broadcast_dttm, disseminationDateTime, timeTaken, fileName, attFileSize. Important: fileName is a direct download URL on nsearchives.nseindia.com (e.g. https://nsearchives.nseindia.com/annual_reports/AR_29285_RELIANCE_2025_2026_A_11007429_28052026133947.pdf) — this function does not download the file itself, it only returns the metadata and the link, same as every other *_history-style function in this library. Fetch the URL yourself (e.g. with requests or curl) if you want the actual PDF/zip.