Announcements API

Overview

The Announcements API retrieves live corporate announcements and events for stocks. This endpoint provides real-time information about upcoming and recent corporate events including AGMs, dividends, and other material announcements. Source File: fetch_new_announcements.py

Endpoint Details

URL

string

required

https://ow-static-scanx.dhan.co/staticscanx/announcements

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.isin

string

required

ISIN code of the company

Example Payload

{
  "data": {
    "isin": "INE002A01018"
  }
}

Example Request

curl -X POST https://ow-static-scanx.dhan.co/staticscanx/announcements \
  -H "Content-Type: application/json" \
  -H "User-Agent: Mozilla/5.0" \
  -d '{
    "data": {
      "isin": "INE002A01018"
    }
  }'

Response Structure

data

array

Array of announcement objects

Announcement Object Fields

events

string

Event name or announcement title

date

string

Event date in YYYY-MM-DD format

type

string

Announcement type/category

Example Response

{
  "data": [
    {
      "events": "Annual General Meeting",
      "date": "2024-06-15",
      "type": "AGM"
    },
    {
      "events": "Dividend - Rs 8 per share",
      "date": "2024-03-20",
      "type": "Dividend"
    },
    {
      "events": "Board Meeting for Q4 Results",
      "date": "2024-05-10",
      "type": "Board Meeting"
    }
  ]
}

Implementation Details

Configuration

Max Threads

integer

default:"40"

Concurrent threads for parallel processing (higher than filings due to smaller payloads)

Timeout

integer

default:"10"

Request timeout in seconds

Input File

string

required

master_isin_map.json

Output File

string

all_company_announcements.json

Processing Flow

Load Master Map: Read ISINs from master_isin_map.json
Parallel Fetch: Use ThreadPoolExecutor with 40 workers
Enrich Data: Add Symbol and Name to each announcement
Consolidate: Merge all results into single array
Sort: Order by date descending (latest first)
Save: Write to all_company_announcements.json

Code Implementation

import requests
import json
from concurrent.futures import ThreadPoolExecutor, as_completed

api_url = "https://ow-static-scanx.dhan.co/staticscanx/announcements"

def fetch_announcements(item):
    symbol = item.get("Symbol")
    isin = item.get("ISIN")
    name = item.get("Name")
    
    payload = {"data": {"isin": isin}}
    
    try:
        response = requests.post(api_url, json=payload, headers=headers, timeout=10)
        if response.status_code == 200:
            announcements = response.json().get("data")
            if announcements and isinstance(announcements, list):
                return [
                    {
                        "Symbol": symbol,
                        "Name": name,
                        "Event": ann.get("events"),
                        "Date": ann.get("date"),
                        "Type": ann.get("type")
                    } for ann in announcements
                ]
        return None
    except:
        return None

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

all_results = []

# Parallel processing
with ThreadPoolExecutor(max_workers=40) as executor:
    future_to_stock = {executor.submit(fetch_announcements, stock): stock 
                       for stock in master_list}
    
    for future in as_completed(future_to_stock):
        res = future.result()
        if res:
            all_results.extend(res)

# Sort by date descending
all_results.sort(key=lambda x: x.get("Date", ""), reverse=True)

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

Output Structure

The output file contains a flat array of enriched announcements:

[
  {
    "Symbol": "RELIANCE",
    "Name": "Reliance Industries Ltd.",
    "Event": "Annual General Meeting",
    "Date": "2024-06-15",
    "Type": "AGM"
  },
  {
    "Symbol": "TCS",
    "Name": "Tata Consultancy Services Ltd.",
    "Event": "Dividend - Rs 12 per share",
    "Date": "2024-06-10",
    "Type": "Dividend"
  }
]

Performance Metrics

Total Stocks: ~2,775
Threads: 40 concurrent requests
Time per Stock: ~1-2 seconds
Total Time: ~2-4 minutes for full market
Avg Announcements per Stock: 3-5 (varies significantly)
Total Announcements: ~8,000-12,000
Success Rate: >98%

Progress Tracking

Progress: 100/2775 done.
Progress: 200/2775 done.
Progress: 500/2775 done.
...
Successfully saved 10543 announcements to all_company_announcements.json

Announcement Types

Common announcement types:

AGM: Annual General Meeting
EGM: Extraordinary General Meeting
Dividend: Dividend announcements
Board Meeting: Board meeting schedules
Record Date: Record date for corporate actions
Book Closure: Book closure dates
Interest Payment: Interest payment dates (for bonds)
Redemption: Redemption announcements

Error Handling

Timeout Management

try:
    response = requests.post(api_url, json=payload, headers=headers, timeout=10)
    if response.status_code == 200:
        res_json = response.json()
        announcements = res_json.get("data")
        if announcements and isinstance(announcements, list):
            # Process announcements
            pass
    return None
except Exception as e:
    return None  # Graceful failure

Empty Response Handling

Stocks without announcements return None
These are skipped in the consolidation phase
No error is logged for stocks without announcements

Use Cases

Event Calendar: Build upcoming corporate events calendar
Dividend Tracking: Monitor dividend announcements
AGM/EGM Alerts: Track shareholder meetings
Record Date Tracking: Identify ex-dates for corporate actions
Investor Relations: Aggregate event data for portfolio stocks

Data Freshness

Announcements are updated in real-time as companies file with exchanges
Typically includes events from past 3 months to future 6 months
Historical announcements beyond 3 months may not be available
Run daily for up-to-date announcement tracking

Filtering Examples

Filter by Type

# Get only dividend announcements
dividend_announcements = [
    ann for ann in all_results 
    if ann.get("Type") == "Dividend"
]

Filter by Date Range

from datetime import datetime, timedelta

# Get announcements in next 30 days
today = datetime.now()
thirty_days = today + timedelta(days=30)

upcoming = [
    ann for ann in all_results
    if today <= datetime.strptime(ann.get("Date"), "%Y-%m-%d") <= thirty_days
]

Filter by Symbol

# Get announcements for specific stocks
portfolio_symbols = ["RELIANCE", "TCS", "INFY"]
portfolio_events = [
    ann for ann in all_results
    if ann.get("Symbol") in portfolio_symbols
]

Notes

This endpoint returns live/upcoming announcements, not historical filings
For historical regulatory filings, use the Company Filings API
Some stocks may have no upcoming announcements (returns empty array)
The API does not require authentication
Rate limiting is lenient due to small payload size
Announcements are sourced from exchange filings (BSE/NSE)
Event names may vary in format across companies

Endpoints

Output Fields

Overview

Endpoint Details

Request Headers

Request Payload

Example Payload

Example Request

Response Structure

Announcement Object Fields

Example Response

Implementation Details

Configuration

Processing Flow

Code Implementation

Output Structure

Performance Metrics

Progress Tracking

Announcement Types

Error Handling

Timeout Management

Empty Response Handling

Use Cases

Data Freshness

Filtering Examples

Filter by Type

Filter by Date Range

Filter by Symbol

Notes

Build docs developers (and LLMs) love

Endpoints

Output Fields

Documentation Index

​Overview

​Endpoint Details

​Request Headers

​Request Payload

​Example Payload

​Example Request

​Response Structure

​Announcement Object Fields

​Example Response

​Implementation Details

​Configuration

​Processing Flow

​Code Implementation

​Output Structure

​Performance Metrics

​Progress Tracking

​Announcement Types

​Error Handling

​Timeout Management

​Empty Response Handling

​Use Cases

​Data Freshness

​Filtering Examples

​Filter by Type

​Filter by Date Range

​Filter by Symbol

​Notes

Build docs developers (and LLMs) love

Overview

Endpoint Details

Request Headers

Request Payload

Example Payload

Example Request

Response Structure

Announcement Object Fields

Example Response

Implementation Details

Configuration

Processing Flow

Code Implementation

Output Structure

Performance Metrics

Progress Tracking

Announcement Types

Error Handling

Timeout Management

Empty Response Handling

Use Cases

Data Freshness

Filtering Examples

Filter by Type

Filter by Date Range

Filter by Symbol

Notes