Merge pull request #116 from jugaad-py/fix/issue-105-stock-quote-fno-nextapi

[Fix] Issue #105 - Fix stock_quote_fno() using NSE NextApi endpoint

Author: sevakram

.github/copilot-instructions.md

@@ -23,6 +23,20 @@ $ source env/bin/activate
 # Running tests
 Tests are important while development. Whenever you add/update a functionality, ensure you add tests for the same. We are using `pytest` for testing.
 
+# GitHub CLI Usage
+Use GitHub CLI (`gh`) to interact with GitHub for fetching issues, PRs, and project information:
+
+- **Fetch an issue by number**: `gh issue view <issue-number>`
+- **List open issues**: `gh issue list --state open`
+- **List closed issues**: `gh issue list --state closed`
+- **Search issues by label**: `gh issue list --label "<label>"`
+- **Fetch a specific PR**: `gh pr view <pr-number>`
+- **List open PRs**: `gh pr list --state open`
+- **Create a PR**: `gh pr create --title "..." --body "..."`
+- **View PR details with comments**: `gh pr view <pr-number> --comments`
+
+Always use `gh` instead of manually browsing GitHub when you need to reference issues or PRs.
+
 # Project structure
 
 - `blog_run_test.sh`: Shell script for running tests in a blog context.
@@ -71,6 +85,7 @@ Tests are important while development. Whenever you add/update a functionality,
 1. **Take the requirement from the user**
    - Listen carefully and document the requirement clearly
    - Ask clarifying questions if ambiguous
+   - If referring to a GitHub issue/PR, use `gh issue view <number>` or `gh pr view <number>` to fetch full details
 
 2. **Discuss and refine the requirement WITH the user**
    - Clarify scope, expected behavior, edge cases

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.33.0] - 2026-03-16
+
+### Changed
+- **BREAKING CHANGE**: `stock_quote_fno()` now returns NSE NextApi response format (see API_REFERENCE.md)
+  - **Old format**: Nested structure with `stocks[*].metadata` and `stocks[*].tradeInfo`
+  - **New format**: Flat array structure with `data[*]` containing all contract info
+  - Returns all available contracts (futures + all expiries of calls and puts) in single response
+  - Each contract now includes comprehensive fields: `identifier`, `instrumentType`, `expiryDate`, `optionType`, `strikePrice`, `lastPrice`, `openInterest`, etc.
+  - Response also includes `timestamp` field
+
+### Fixed
+- Issue #105: `stock_quote_fno()` returning empty data - NSE deprecated old `/api/quote-derivative` endpoint
+  - Now uses NSE NextApi endpoint (`getSymbolDerivativesData`) which provides current derivatives data
+  - Resolves `IndexError: list index out of range` when accessing `stocks[0]`
+
+### Updated
+- Enhanced test coverage: `test_stock_quote_fno()` now validates actual data presence, not just structure
+- Updated API documentation with new response fields and format
+- Updated LIVE_DATA_GUIDE with examples for processing new response format
+- Updated QUICKSTART guide with new usage examples
+
 ## [0.32.0] - 2026-03-16
 
 ### Added

docs/API_REFERENCE.md

@@ -134,20 +134,49 @@ Get detailed trade information for a stock.
 }
 ```
 
-#### `stock_quote_fno(symbol)`
-Get futures and options quotes for a stock.
+#### `stock_quote_fno(symbol)` - [BREAKING CHANGE v0.33]
+Get futures and options quotes for a symbol.
 
 **Parameters:**
-- `symbol` (str): Stock symbol
+- `symbol` (str): Stock or index symbol (e.g., 'RELIANCE', 'NIFTY')
 
 **Returns:**
 ```python
 {
-    'stocks': list,              # List of all F&O contracts
-    # Each contract contains metadata and market depth
+    'data': [
+        {
+            'identifier': 'FUTSTKRELIANCE30-Mar-2026XX0.00',
+            'instrumentType': 'FUTSTK',           # FUTSTK (Futures) or OPTSTK (Options)
+            'underlying': 'RELIANCE',
+            'expiryDate': '30-Mar-2026',
+            'optionType': 'XX',                  # XX (Futures), CE (Call), PE (Put)
+            'strikePrice': '0.00',
+            'lastPrice': 2850.5,
+            'change': 15.2,
+            'pchange': 0.54,
+            'openPrice': 2835.0,
+            'highPrice': 2860.0,
+            'lowPrice': 2820.0,
+            'closePrice': 2835.3,
+            'prevClose': 2835.3,
+            'totalTradedVolume': 45678,
+            'totalTurnover': 1296789420,
+            'openInterest': 123456,
+            'changeinOpenInterest': 1234,
+            'pchangeinOpenInterest': 1.01,
+            'underlyingValue': 2850.5,
+            'volumeFreezeQuantity': 240001,
+            'ticksize': 0.05,
+            ...other fields
+        },
+        ...more contracts
+    ],
+    'timestamp': '16-Mar-2026 15:30:00'
 }
 ```
 
+**Note:** Response includes all available contracts (futures + all expiries of calls and puts) for the given symbol.
+
 ### Option Chains
 
 #### `index_option_chain(symbol, expiry_date=None)`

docs/LIVE_DATA_GUIDE.md

@@ -387,45 +387,79 @@ contract = turnover['value'][0]
 ### Futures and Options Quote for Stock
 
 ```python
-# Get all F&O contracts for a stock
-quotes = n.stock_quote_fno("HDFC")
+# Get all F&O contracts for a symbol (includes all expiries and strikes)
+fno_data = n.stock_quote_fno("RELIANCE")
 
-# List all contracts with prices
-for quote in quotes['stocks']:
-    identifier = quote['metadata']['identifier']
-    last_price = quote['metadata']['lastPrice']
-    print(f"{identifier}: {last_price}")
+# Response structure
+{
+    'data': [
+        {
+            'identifier': 'FUTSTKRELIANCE30-Mar-2026XX0.00',
+            'instrumentType': 'FUTSTK',  # or 'OPTSTK'
+            'underlying': 'RELIANCE',
+            'expiryDate': '30-Mar-2026',
+            'optionType': 'XX',          # 'XX' for Futures, 'CE' or 'PE' for Options
+            'strikePrice': '0.00',
+            'lastPrice': 2850.5,
+            'openPrice': 2835.0,
+            'highPrice': 2860.0,
+            'lowPrice': 2820.0,
+            'closePrice': 2835.3,
+            'prevClose': 2835.3,
+            'change': 15.2,
+            'pchange': 0.54,
+            'openInterest': 123456,
+            'changeinOpenInterest': 1234,
+            'totalTradedVolume': 45678,
+            'totalTurnover': 1296789420,
+            'underlyingValue': 2850.5,
+            'volumeFreezeQuantity': 240001,
+            'ticksize': 0.05,
+        },
+        ...more contracts
+    ],
+    'timestamp': '16-Mar-2026 15:30:00'
+}
 ```
 
-### Contract Details
+### Processing Contract Data
 
 ```python
-contract = quotes['stocks'][0]
+# Iterate through all contracts
+fno_data = n.stock_quote_fno("RELIANCE")
 
-# Metadata
-metadata = contract['metadata']
-{
-    'instrumentType': 'Stock Futures',
-    'expiryDate': '28-Jan-2021',
-    'optionType': '-',
-    'strikePrice': 0,
-    'identifier': 'FUTSTKHDFC28-01-2021XX0.00',
-    'lastPrice': 2565.85,
-    'change': -29.35,
-    'pChange': -1.13,
-    'numberOfContractsTraded': 26898,
-    'totalTurnover': 211855.64
-}
+# Filter futures only
+futures = [c for c in fno_data['data'] if c['instrumentType'] == 'FUTSTK']
 
-# Order book (market depth)
-order_book = contract['marketDeptOrderBook']
+# Filter call options with 30-Mar expiry
+calls_mar = [c for c in fno_data['data'] 
+             if c['instrumentType'] == 'OPTSTK' 
+             and c['optionType'] == 'CE'
+             and c['expiryDate'] == '30-Mar-2026']
 
-# Trade info
-trade_info = contract['tradeInfo']
-print(f"Open Interest: {trade_info['openInterest']}")
-print(f"Change in OI: {trade_info['changeinOpenInterest']}")
-print(f"Volatility (Daily): {contract['otherInfo']['dailyvolatility']}")
-print(f"Volatility (Annualized): {contract['otherInfo']['annualisedVolatility']}")
+# Get highest IV call option
+calls_mar_sorted = sorted(calls_mar, key=lambda x: x['lastPrice'], reverse=True)
+for call in calls_mar_sorted[:5]:
+    print(f"Strike: {call['strikePrice']:8} | Price: {call['lastPrice']:8.2f} | OI: {call['openInterest']}")
+```
+
+### Working with Specific Contracts
+
+```python
+# Get a specific contract
+contract = fno_data['data'][0]
+
+# Extract key information
+identifier = contract['identifier']
+price = contract['lastPrice']
+oi = contract['openInterest']
+volume = contract['totalTradedVolume']
+iv = contract.get('impliedVolatility', 'N/A')  # If available
+
+print(f"Contract: {identifier}")
+print(f"Current Price: {price}")
+print(f"Open Interest: {oi}")
+print(f"Volume: {volume}")
 ```
 
 ---

docs/QUICKSTART.md

@@ -114,10 +114,20 @@ from jugaad_data.nse import NSELive
 
 n = NSELive()
 
-# Stock futures and options
-quotes = n.stock_quote_fno("HDFC")
-for quote in quotes['stocks']:
-    print(f"{quote['metadata']['identifier']}\t{quote['metadata']['lastPrice']}")
+# Stock/Index futures and options data
+fno_data = n.stock_quote_fno("RELIANCE")
+
+# Process all contracts
+for contract in fno_data['data']:
+    identifier = contract['identifier']
+    price = contract['lastPrice']
+    oi = contract['openInterest']
+    print(f"{identifier:40} | Price: {price:8.2f} | OI: {oi}")
+
+# Filter only call options
+calls = [c for c in fno_data['data'] 
+         if c['instrumentType'] == 'OPTSTK' and c['optionType'] == 'CE']
+print(f"Total Call Contracts: {len(calls)}")
 
 # Equity derivative turnover
 turnover = n.eq_derivative_turnover()

jugaad_data/nse/live.py

@@ -7,11 +7,13 @@
 class NSELive:
     time_out = 5
     base_url = "https://www.nseindia.com/api"
+    nextapi_url = "https://www.nseindia.com/api/NextApi/apiClient/GetQuoteApi"
     page_url = "https://www.nseindia.com/get-quotes/equity?symbol=LT"
     _routes = {
             "stock_meta": "/equity-meta-info",
             "stock_quote": "/quote-equity",
             "stock_derivative_quote": "/quote-derivative",
+            "stock_derivatives_data": "/NextApi/apiClient/GetQuoteApi",
             "market_status": "/marketStatus",
             "chart_data": "/chart-databyindex",
             "market_turnover": "/market-turnover",
@@ -56,15 +58,62 @@ def get(self, route, payload={}):
         r = self.s.get(url, params=payload)
         return r.json()
 
+    def _get_nextapi(self, function_name, **params):
+        """Call NextApi endpoint with functionName and additional parameters.
+        
+        Args:
+            function_name: The functionName parameter for NextApi
+            **params: Additional query parameters
+        
+        Returns:
+            Parsed JSON response from NextApi
+        """
+        query_params = {"functionName": function_name}
+        query_params.update(params)
+        r = self.s.get(self.nextapi_url, params=query_params)
+        return r.json()
+
     @live_cache
     def stock_quote(self, symbol):
         data = {"symbol": symbol}
         return self.get("stock_quote", data) 
 
     @live_cache
     def stock_quote_fno(self, symbol):
-        data = {"symbol": symbol}
-        return self.get("stock_derivative_quote", data)
+        """Fetch live derivatives (futures & options) data for a symbol.
+        
+        Args:
+            symbol: Stock/Index symbol (e.g., 'HDFC', 'NIFTY')
+        
+        Returns:
+            Dictionary with derivatives data:
+            {
+                "data": [
+                    {
+                        "identifier": "OPTSTKHDFC30-Mar-2026CE2500.00",
+                        "instrumentType": "OPTSTK",  # OPTSTK or FUTSTK
+                        "underlying": "HDFC",
+                        "expiryDate": "30-Mar-2026",
+                        "optionType": "CE",  # CE, PE, or XX for futures
+                        "strikePrice": "2500.00",
+                        "lastPrice": 125.5,
+                        "openInterest": 1234,
+                        "totalTradedVolume": 5000,
+                        "openPrice": 120.0,
+                        "highPrice": 130.0,
+                        "lowPrice": 119.5,
+                        "changeInOpenInterest": 100,
+                        ...more fields
+                    },
+                    ...more contracts
+                ],
+                "timestamp": "..."
+            }
+        
+        Note: This uses the NSE NextApi endpoint (getSymbolDerivativesData).
+        Returns all available contracts for the given symbol.
+        """
+        return self._get_nextapi("getSymbolDerivativesData", symbol=symbol)
 
     @live_cache
     def trade_info(self, symbol):

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "jugaad-data"
-version = "0.32.0"
+version = "0.33.0"
 requires-python = ">= 3.9"
 authors = [{name = "jugaad-coder", email = "abc@xyz.com"}]
 description = "Free Zerodha API python library"

tests/test_nse_live.py

@@ -6,10 +6,22 @@ def test_stock_quote():
     assert r['info']['symbol'] == 'HDFC'
 
 def test_stock_quote_fno():
-    r = n.stock_quote_fno("HDFC")
-    assert 'strikePrices' in r
-    assert 'info' in r
-    assert 'stocks' in r
+    # Use a symbol with active derivatives (NIFTY or RELIANCE)
+    r = n.stock_quote_fno("RELIANCE")
+    # Validate response structure
+    assert 'data' in r, "Response should have 'data' key"
+    assert 'timestamp' in r, "Response should have 'timestamp' key"
+    # Validate data is not empty
+    assert len(r['data']) > 0, "Derivatives data should not be empty"
+    
+    # Validate first contract structure
+    contract = r['data'][0]
+    assert 'identifier' in contract
+    assert 'instrumentType' in contract
+    assert 'underlying' in contract
+    assert contract['underlying'] == 'RELIANCE', "Underlying symbol should match requested symbol"
+    assert 'expiryDate' in contract
+    assert 'lastPrice' in contract or contract.get('lastPrice') is not None
 
 def test_trade_info():
     r = n.trade_info("HDFC")