Merge pull request #117 from jugaad-py/fix/issue-97-derivatives-api

[Fix] Issue #97 - derivatives_df() API endpoint fix

Author: sevakram

CHANGELOG.md

@@ -5,6 +5,20 @@ 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.1] - 2026-03-16
+
+### Fixed
+- Issue #97: `derivatives_df()` and `derivatives_csv()` returning empty or failing with 404 error
+  - NSE deprecated `/api/historical/fo/derivatives` endpoint
+  - Now uses updated `/api/historicalOR/foCPV` endpoint
+  - Added `year` parameter to API requests as required by new endpoint
+  - Historical data availability limited to recent periods per NSE data retention
+
+### Added
+- Test coverage for `derivatives_df()` with both futures (FUTIDX) and options (OPTIDX) data
+- Test coverage for `derivatives_raw()` with different instrument types
+- Documentation note about historical data availability for derivatives
+
 ## [0.33.0] - 2026-03-16
 
 ### Changed

docs/API_REFERENCE.md

@@ -385,6 +385,12 @@ Download derivatives data and save to CSV.
 - Same as `derivatives_df()`
 - `output` (str): Path for output CSV file
 
+**Note on Historical Data:**
+- As of v0.34.0+, the derivatives API endpoint has been updated to use NSE's new `/api/historicalOR/foCPV` endpoint
+- Historical data is available for recent periods (typically current and past few months)
+- Data availability depends on NSE's data retention policies
+- For very old historical data (prior to ~6 months), data may not be available
+
 ### NSE Daily Reports
 
 #### `list_available_reports()`

jugaad_data/nse/history.py

@@ -46,7 +46,7 @@ def __init__(self):
             }
         self.path_map = {
             "stock_history": "/api/historicalOR/generateSecurityWiseHistoricalData",
-            "derivatives": "/api/historical/fo/derivatives",
+            "derivatives": "/api/historicalOR/foCPV",
             "equity_quote_page": "/report-detail/eq_security",
         }
         self.base_url = "https://www.nseindia.com"
@@ -95,7 +95,8 @@ def _derivatives(self, symbol, from_date, to_date, expiry_date, instrument_type,
             'from': from_date.strftime('%d-%m-%Y'),
             'to': to_date.strftime('%d-%m-%Y'),
             'expiryDate': expiry_date.strftime('%d-%b-%Y').upper(),
-            'instrumentType': instrument_type
+            'instrumentType': instrument_type,
+            'year': from_date.year
             }
         if "OPT" in instrument_type:
             if not(strike_price and option_type):

pyproject.toml

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

tests/test_nse.py

@@ -167,6 +167,62 @@ class TestDerivatives(TestCase):
     def setUp(self):
         setup_test(self)
 
+    def test_derivatives_raw_futures(self):
+        """Test fetching futures derivatives data"""
+        symbol = "NIFTY"
+        from_date = date(2026, 3, 9)
+        to_date = date(2026, 3, 16)
+        expiry_date = date(2026, 3, 30)
+        instrument_type = "FUTIDX"
+        
+        raw = nse.derivatives_raw(symbol, from_date, to_date, expiry_date, instrument_type,
+                                  strike_price=None, option_type=None)
+        assert len(raw) > 0
+        # Verify required fields for futures
+        assert 'FH_TIMESTAMP' in raw[0]
+        assert 'FH_SYMBOL' in raw[0]
+        assert 'FH_CLOSING_PRICE' in raw[0]
+        assert raw[0]['FH_SYMBOL'] == symbol
+    
+    def test_derivatives_raw_options(self):
+        """Test fetching options derivatives data"""
+        symbol = "NIFTY"
+        from_date = date(2026, 3, 9)
+        to_date = date(2026, 3, 16)
+        expiry_date = date(2026, 3, 30)
+        instrument_type = "OPTIDX"
+        strike_price = 23000
+        option_type = "PE"
+        
+        raw = nse.derivatives_raw(symbol, from_date, to_date, expiry_date, instrument_type, 
+                                   strike_price=strike_price, option_type=option_type)
+        assert len(raw) > 0
+        # Verify required fields for options
+        assert 'FH_TIMESTAMP' in raw[0]
+        assert 'FH_OPTION_TYPE' in raw[0]
+        assert 'FH_STRIKE_PRICE' in raw[0]
+        assert raw[0]['FH_OPTION_TYPE'] == option_type
+        assert raw[0]['FH_STRIKE_PRICE'] == strike_price
+    
+    def test_derivatives_df(self):
+        """Test fetching derivatives as dataframe"""
+        symbol = "NIFTY"
+        from_date = date(2026, 3, 9)
+        to_date = date(2026, 3, 16)
+        expiry_date = date(2026, 3, 30)
+        instrument_type = "OPTIDX"
+        strike_price = 23000
+        option_type = "PE"
+        
+        df = nse.derivatives_df(symbol, from_date, to_date, expiry_date, instrument_type,
+                               strike_price=strike_price, option_type=option_type)
+        assert len(df) > 0
+        # Verify required columns for options
+        assert 'DATE' in df.columns
+        assert 'EXPIRY' in df.columns
+        assert 'STRIKE PRICE' in df.columns
+        assert 'OPTION TYPE' in df.columns
+        assert 'CLOSE' in df.columns
 
 class TestIndexHistory(TestCase):
     def setUp(self):