Docs / Dates and calendars

Festivals API

Hindu, Tamil, Sikh, Jain, Buddhist, Islamic and Christian festival dates for any year, computed.

Festival dates for 1950 to 2100, worked out from the panchang by each festival's own rule (Diwali by the amavasya at sunset, Ganesh Chaturthi by the chaturthi at midday, Karthigai Deepam by the evening nakshatra), with the rule given beside each date. Islamic dates come from the tabular calendar and are marked expected. Also as a calendar feed. For official holidays, see Holidays.

Base URL https://api.dharun.devNo key needed for most600 units a minute, 3000 with a free keyThis page as Markdown

Festivals in a year

GET/v1/festivals/{year}

Parameter	Description
`year`path, required	1950 to 2100.
`kind`query	Only one kind. One of: hindu, tamil, sikh, jain, buddhist, islamic, christian, national.
`state`query	Leave out regional festivals not kept in this state.
`month`query	1 to 12.

curl

curl "https://api.dharun.dev/v1/festivals/2026?month=11&utm_medium=docs"

JavaScript

const response = await fetch("https://api.dharun.dev/v1/festivals/2026?month=11&utm_medium=docs");
const body = await response.json();
if (!response.ok) throw new Error(body.error.message);
console.log(body.data);

Python

import requests

response = requests.get("https://api.dharun.dev/v1/festivals/2026?month=11&utm_medium=docs", timeout=10)
body = response.json()
if not response.ok:
    raise RuntimeError(body["error"]["message"])
print(body["data"])

Try it here

Change the values and send the request from your browser. Needs JavaScript.

Response, with lists and long text shortened

{
  "data": [
    {
      "date": "2026-11-06",
      "name": "Dhanteras",
      "kind": "hindu",
      "rule": "Krishna trayodashi at sunset, amanta Ashvina"
    },
    {
      "date": "2026-11-08",
      "name": "Naraka Chaturdashi",
      "tamil": "தீபாவளி (தமிழ்நாடு)",
      "kind": "hindu",
      "rule": "Krishna chaturdashi at sunrise, amanta Ashvina: Deepavali in the south"
    },
    {
      "date": "2026-11-08",
      "name": "Diwali (Lakshmi Puja)",
      "tamil": "தீபாவளி",
      "kind": "hindu",
      "rule": "Amavasya at sunset, end of amanta Ashvina"
    }
  ],
  "meta": {
    "total": 8,
    "note": "Computed from the panchang: lunar festivals by the tithi at the time custom names (sunrise for most), reckoned at New Delhi; Tamil festivals by the solar month …"
  }
}

Festivals as a calendar to subscribe to

GET/v1/festivals/{year}.ics

The answer returns an iCalendar file (text/calendar) to subscribe to; errors are JSON as everywhere else.

Parameter	Description
`year`path, required	The year, followed by .ics.
`kind`query	Only one kind. One of: hindu, tamil, sikh, jain, buddhist, islamic, christian, national.
`state`query	State code or name, for example TN or Tamil Nadu.

curl

curl -o holidays.ics "https://api.dharun.dev/v1/festivals/2026.ics?state=TN&utm_medium=docs"

Python

import requests

response = requests.get("https://api.dharun.dev/v1/festivals/2026.ics?state=TN&utm_medium=docs", timeout=60)
response.raise_for_status()
open("holidays.ics", "wb").write(response.content)

Try it here

Change the values and send the request from your browser. Needs JavaScript.

Using an AI assistant? Connect the MCP server and it can call this API by itself. Want every endpoint on one bench? Open the playground.