Fundamental Data API

Overview

The Fundamental Data API retrieves comprehensive financial statements, quarterly results, and key financial ratios for stocks. This endpoint processes ISINs from the master map and returns balance sheets, P&L statements, and ratio analysis. Source File: fetch_fundamental_data.py

Endpoint Details

URL

string

required

https://open-web-scanx.dhan.co/scanx/fundamental

Method

string

required

POST

Content-Type

string

required

application/json

Request Headers

{
  "Content-Type": "application/json",
  "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "Accept": "application/json, text/plain, */*"
}

Request Payload

data.isins

array

required

Array of ISIN codes (up to 100 per request for optimal performance)

Batch Processing

The implementation uses batching for efficiency:

{
  "data": {
    "isins": [
      "INE002A01018",
      "INE467B01029",
      "INE040A01034"
    ]
  }
}

Example Request

curl -X POST https://open-web-scanx.dhan.co/scanx/fundamental \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{
    "data": {
      "isins": [
        "INE002A01018",
        "INE467B01029"
      ]
    }
  }'

Response Structure

status

string

API response status - “success” or error message

data

array

Array of fundamental data objects for each ISIN

Data Object Fields

isin

string

ISIN code of the security

Symbol

string

Trading symbol (enriched from master_isin_map.json)

Name

string

Company display name (enriched from master_isin_map.json)

results

array

Quarterly financial results

ratios

object

Financial ratios including P/E, P/B, ROE, ROCE, Debt/Equity, etc.

balanceSheet

object

Balance sheet items

profitLoss

object

P&L statement items

cashFlow

object

Cash flow statement items

Example Response

{
  "status": "success",
  "data": [
    {
      "isin": "INE002A01018",
      "Symbol": "RELIANCE",
      "Name": "Reliance Industries Ltd.",
      "results": [
        {
          "quarter": "Q3 FY24",
          "revenue": 245000,
          "netProfit": 18500,
          "eps": 27.5
        }
      ],
      "ratios": {
        "pe": 25.3,
        "pb": 2.1,
        "roe": 9.2,
        "roce": 12.5,
        "debtToEquity": 0.45
      }
    }
  ]
}

Implementation Details

Configuration

Batch Size

integer

default:"100"

Number of ISINs processed per API request

Timeout

integer

default:"30"

Request timeout in seconds

Delay

float

default:"0.5"

Delay between batches in seconds to avoid rate limiting

Input File

string

required

master_isin_map.json - Generated by Dhan ScanX API

Output File

string

fundamental_data.json (~35 MB for full market)

Processing Flow

Load Master Map: Read ISINs from master_isin_map.json
Create Batches: Split ~2,775 ISINs into batches of 100
API Requests: Send POST requests for each batch
Enrich Data: Add Symbol and Name from master map
Consolidate: Merge all batch results
Save Output: Write to fundamental_data.json

Code Example

import requests
import json
import time

api_url = "https://open-web-scanx.dhan.co/scanx/fundamental"
batch_size = 100

# Load master map
with open("master_isin_map.json", "r") as f:
    master_map = json.load(f)

isin_lookup = {item['ISIN']: {"Symbol": item["Symbol"], "Name": item["Name"]} 
                for item in master_map}
all_isins = list(isin_lookup.keys())

all_fundamental_data = []

# Process in batches
for i in range(0, len(all_isins), batch_size):
    batch_isins = all_isins[i:i + batch_size]
    
    payload = {"data": {"isins": batch_isins}}
    
    response = requests.post(api_url, json=payload, headers=headers, timeout=30)
    
    if response.status_code == 200:
        data = response.json()
        if data.get('status') == 'success':
            batch_results = data.get('data', [])
            
            # Enrich with Symbol and Name
            for item in batch_results:
                item_isin = item.get('isin')
                if item_isin in isin_lookup:
                    item['Symbol'] = isin_lookup[item_isin]['Symbol']
                    item['Name'] = isin_lookup[item_isin]['Name']
            
            all_fundamental_data.extend(batch_results)
    
    time.sleep(0.5)  # Rate limiting

# Save results
with open("fundamental_data.json", "w") as f:
    json.dump(all_fundamental_data, f, indent=4)

Error Handling

The API returns different status codes:

200: Success - data returned in response
400: Bad request - invalid ISIN format
500: Server error - retry with exponential backoff
Timeout: Request exceeded 30 seconds

Retry Logic

try:
    response = requests.post(api_url, json=payload, headers=headers, timeout=30)
    
    if response.status_code == 200:
        data = response.json()
        if data.get('status') == 'success':
            # Process data
            pass
        else:
            print(f"API Error: {data.get('message')}")
    else:
        print(f"HTTP Error: {response.status_code}")
except Exception as e:
    print(f"Exception: {e}")

Performance Metrics

Total ISINs: ~2,775 (entire NSE equity market)
Total Batches: ~28 (at 100 per batch)
Total Time: ~15-20 seconds (with 0.5s delay)
Output Size: ~35 MB
Success Rate: >99% for valid ISINs

Output File Structure

The fundamental_data.json file contains an array of enriched fundamental data objects:

[
  {
    "isin": "INE002A01018",
    "Symbol": "RELIANCE",
    "Name": "Reliance Industries Ltd.",
    "results": [...],
    "ratios": {...},
    "balanceSheet": {...},
    "profitLoss": {...},
    "cashFlow": {...}
  }
]

Use Cases

Fundamental Screening: Filter stocks by financial ratios
Quarterly Results Analysis: Track revenue and profit growth
Financial Health Check: Analyze debt ratios and cash flows
Valuation Models: Use P/E, P/B for relative valuation
Earnings Tracking: Monitor EPS trends across quarters

Dependencies

Required Files:

master_isin_map.json (generated by Dhan ScanX API)

Used By:

Earnings performance processors
Advanced metrics calculators
Stock screening tools

Notes

Some ISINs may not have fundamental data available (newly listed stocks, delisted stocks)
Quarterly results are updated within 24-48 hours of official filing
Historical data availability varies by company (typically 5-10 years)
TTM (Trailing Twelve Months) metrics are automatically calculated
The API is rate-limited - use batch processing with delays as shown in implementation

Endpoints

Output Fields

Overview

Endpoint Details

Request Headers

Request Payload

Batch Processing

Example Request

Response Structure

Data Object Fields

Example Response

Implementation Details

Configuration

Processing Flow

Code Example

Error Handling

Retry Logic

Performance Metrics

Output File Structure

Use Cases

Dependencies

Notes

Build docs developers (and LLMs) love

Endpoints

Output Fields

​Overview

​Endpoint Details

​Request Headers

​Request Payload

​Batch Processing

​Example Request

​Response Structure

​Data Object Fields

​Example Response

​Implementation Details

​Configuration

​Processing Flow

​Code Example

​Error Handling

​Retry Logic

​Performance Metrics

​Output File Structure

​Use Cases

​Dependencies

​Notes

Build docs developers (and LLMs) love

Overview

Endpoint Details

Request Headers

Request Payload

Batch Processing

Example Request

Response Structure

Data Object Fields

Example Response

Implementation Details

Configuration

Processing Flow

Code Example

Error Handling

Retry Logic

Performance Metrics

Output File Structure

Use Cases

Dependencies

Notes