Hindu calendar: festivals for a year and place

POST

/vedic/calendar/festivals

curl -X POST https://api.astroway.info/v1/vedic/calendar/festivals \
  -H "X-Api-Key: aw_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "year": 2026, "latitude": 28.6139, "longitude": 77.209, "timezone": "Asia/Kolkata", "festivals": [ "diwali", "makar-sankranti" ] }'

const res = await fetch('https://api.astroway.info/v1/vedic/calendar/festivals', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.ASTROWAY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "year": 2026,
    "latitude": 28.6139,
    "longitude": 77.209,
    "timezone": "Asia/Kolkata",
    "festivals": [
      "diwali",
      "makar-sankranti"
    ]
  }),
});
const { ok, data, error } = await res.json();
if (!ok) throw new Error(error.message);
console.log(data);

import os, requests

r = requests.post(
    'https://api.astroway.info/v1/vedic/calendar/festivals',
    headers={'X-Api-Key': os.environ['ASTROWAY_API_KEY'], 'Content-Type': 'application/json'},
    json={
      'year': 2026,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': "Asia/Kolkata",
      'festivals': [
        "diwali",
        "makar-sankranti"
      ]
    },
)
result = r.json()
if not result['ok']:
    raise RuntimeError(result['error']['message'])
print(result['data'])

<?php
use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://api.astroway.info/v1/']);
$r = $client->post('vedic/calendar/festivals', [
    'headers' => ['X-Api-Key' => getenv('ASTROWAY_API_KEY')],
    'json' => [
        'year' => 2026,
        'latitude' => 28.6139,
        'longitude' => 77.209,
        'timezone' => 'Asia/Kolkata',
        'festivals' => ['diwali', 'makar-sankranti'],
    ],
]);
$result = json_decode($r->getBody(), true);
if (!$result['ok']) throw new \RuntimeException($result['error']['message']);
print_r($result['data']);

About 55 pan-Indian festivals dated for the place: Makar Sankranti, Maha Shivaratri, Holika Dahan and Holi, Ugadi, Rama Navami, Hanuman Jayanti, Akshaya Tritiya, Guru Purnima, Raksha Bandhan, Janmashtami, Ganesh Chaturthi, Navratri, Dussehra, Karva Chauth, Dhanteras, Diwali, Govardhan Puja, Bhai Dooj, Chhath, Onam, Puthandu, Vishu, Pohela Boishakh and more. Each entry carries the rule that defines it (month, tithi and the kala it must hold at: sunrise, madhyahna, aparahna, pradosha, nishita, moonrise), the source, how the day was decided (basis: vyapti on one day, vriddhi on two and the tie-break, kshaya on none), the tithi with its local start and end, the amanta and purnimanta month and the kala window. tradition: smarta (default) or vaishnava where they differ (Rama Navami, Janmashtami). timezone (IANA or auto) is followed day by day, summer time included. Checked against drikpanchang for New Delhi, Chennai and New York 2025 and 2026: 323 of 325 dates.

Authorizations

ApiKeyAuth

Parameters

Query Parameters

fields

string

Comma-separated dotted paths, relative to data, to keep in the response. A path is applied to every element of an array, so planets.name means the name of each planet. Paths that match nothing come back in _fields_unmatched; a list where nothing matches at all is a 400, because an empty object would be a confident wrong answer.

Example

planets.name,planets.longitude

precision

integer

<= 15

Round every non-integer number in the response to this many decimal places. Integers are left alone, because an id is not a measurement. Ecliptic longitudes ship with fourteen decimals by default; 2 is about a tenth of an arcminute.

Example

Header Parameters

Idempotency-Key

string

>= 1 characters <= 255 characters /^[\x21-\x7E]+$/

Unique per logical operation, kept across retries. For 24 hours from the first request, a repeat with the same key, method, path, body and query string returns the stored response with Idempotent-Replayed: true and costs 0 credits. The same key with a different body or query string is a 409 IDEMPOTENCY_KEY_REUSED; a repeat while the first is still running is a 409 IDEMPOTENCY_IN_PROGRESS. Only 2xx responses are kept. See /idempotency/.

Example

01HXY2A7ZM0ABCDEF

Request Body^required

application/json

A Gregorian year and a place for the Hindu festival calendar.

object

year required

Gregorian year, 1900 to 2100. Entries are those whose date falls in this year.

integer

>= 1900 <= 2100

latitude required

Latitude in decimal degrees, north positive. Between -66 and 66: further out the Sun does not rise on some days and a Hindu day has no start.

number

nullable >= -66 <= 66

longitude required

Longitude in decimal degrees, east positive.

number

nullable >= -180 <= 180

timezone

IANA zone name such as Asia/Kolkata, America/New_York or Europe/Kyiv, or auto (default) to look it up from the coordinates. Resolved day by day: each day is read on the offset that zone kept that day, so summer time is followed.

string

>= 1 characters <= 64 characters

timezoneOffset

A fixed offset in hours instead of a zone, for the whole year. Ignored when timezone is sent.

number

nullable >= -14 <= 14

ayanamsaId

number

nullable

ayanamsa

Sidereal school by name. Lahiri when omitted. Equivalent to ayanamsaId; send either.

string

Allowed values: fagan-bradley lahiri de-luce raman krishnamurti kp yukteshwar jn-bhasin true-citra djwhal-khul

tradition

Whose reckoning decides the day where they differ (Rama Navami, Janmashtami). smarta (default): the tithi at the rite’s kala, as Dharmasindhu gives it; vaishnava: the ISKCON rule, the tithi at sunrise unmixed with the one before.

string

Allowed values: smarta vaishnava

festivals

Only these festival ids. All when omitted.

Array<string>

<= 56 items

Allowed values: makar-sankranti pongal vasant-panchami ratha-saptami bhishma-ashtami maha-shivaratri holika-dahan holi ugadi chaitra-navratri rama-navami hanuman-jayanti akshaya-tritiya narasimha-jayanti buddha-purnima ganga-dussehra rath-yatra guru-purnima hariyali-teej nag-panchami raksha-bandhan kajari-teej janmashtami hartalika-teej ganesh-chaturthi rishi-panchami radha-ashtami anant-chaturdashi sarva-pitru-amavasya sharad-navratri durga-ashtami maha-navami dussehra sharad-purnima karva-chauth ahoi-ashtami dhanteras narak-chaturdashi diwali govardhan-puja bhai-dooj chhath tulasi-vivah kartika-purnima kalabhairav-jayanti vivah-panchami gita-jayanti dattatreya-jayanti sakat-chauth mauni-amavasya sheetala-ashtami gangaur onam puthandu vishu pohela-boishakh

Example

{
  "year": 2026,
  "latitude": 28.6139,
  "longitude": 77.209,
  "timezone": "Asia/Kolkata",
  "festivals": [
    "diwali",
    "makar-sankranti"
  ]
}

Responses

200

Successful calculation

application/json

object

boolean

data

object

year

number

nullable

place

object

latitude

number

nullable

longitude

number

nullable

timezone

string

nullable

timezoneOffset

nullable

ayanamsaId

number

nullable

tradition

string

nullable

count

number

nullable

festivals

Array<object>

nullable

object

string

nullable

name

string

nullable

date

string

nullable

rule

string

nullable

source

string

nullable

basis

string

nullable

kala

nullable

observedWindow

nullable

tithi

nullable

month

nullable

sankranti

object

sign

string

nullable

string

nullable

tradition

nullable

conventions

object

day

string

nullable

kalas

string

nullable

months

string

nullable

Example

{
  "ok": true,
  "data": {
    "year": 2026,
    "place": {
      "latitude": 28.6139,
      "longitude": 77.209,
      "timezone": "Asia/Kolkata",
      "timezoneOffset": null,
      "ayanamsaId": 1
    },
    "tradition": "smarta",
    "count": 2,
    "festivals": [
      {
        "id": "makar-sankranti",
        "name": "Makar Sankranti",
        "date": "2026-01-14",
        "rule": "Sun enters sidereal Makara. Kept on the day of the transit when it falls before sunset; after sunset, the next day (punya kala after the transit).",
        "source": "Dharmasindhu, pariccheda 2 (Makara sankranti); Nirnayasindhu, pariccheda 2",
        "basis": "sankranti",
        "kala": null,
        "observedWindow": null,
        "tithi": null,
        "month": null,
        "sankranti": {
          "sign": "Makara",
          "at": "2026-01-14T15:07:00+05:30"
        },
        "tradition": null
      },
      {
        "id": "diwali",
        "name": "Diwali (Lakshmi Puja)",
        "date": "2026-11-08",
        "rule": "Amavasya of amanta Ashwina (Kartika in purnimanta) in force at pradosha; on two days, the one it covers longer.",
        "source": "Dharmasindhu, pariccheda 2 (Dipavali); Nirnayasindhu, pariccheda 2",
        "basis": "vyapti",
        "kala": "pradosha",
        "observedWindow": {
          "start": "2026-11-08T17:31:00+05:30",
          "end": "2026-11-08T20:09:00+05:30"
        },
        "tithi": {
          "number": 30,
          "name": "Amavasya",
          "paksha": "krishna",
          "start": "2026-11-08T11:28:00+05:30",
          "end": "2026-11-09T12:32:00+05:30"
        },
        "month": {
          "amanta": "Ashwina",
          "purnimanta": "Kartika"
        },
        "sankranti": null,
        "tradition": null
      }
    ],
    "conventions": {
      "day": "A Hindu day runs from local sunrise to the next sunrise (upper limb, standard refraction).",
      "kalas": "Day in five parts (pratahkala, sangava, madhyahna, aparahna, sayahna); pradosha is the first fifth of the night, nishita its eighth muhurta, arunodaya the 96 minutes before sunrise, purvaratri the first half of the night.",
      "months": "Each entry carries the amanta month (new moon to new moon: South and West India) and the purnimanta month (full moon to full moon: North India). They differ only in the Krishna paksha."
    }
  }
}

400

Validation error

application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "Validation failed: date: Date must be YYYY-MM-DD",
    "details": [
      {
        "path": "date",
        "message": "Date must be YYYY-MM-DD"
      }
    ]
  }
}

401

Missing or invalid API key

application/json

Example

{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API key"
  }
}

Suggest an edit

// Previous

Panchang: Pancha Pakshi (five birds)

Next //

Hindu calendar: vrats (Ekadashi with parana, Pradosh, Sankashti, Purnima, Amavasya, Masik Shivaratri)

Hindu calendar: festivals for a year and place

Authorizations

Parameters

Query Parameters

Example

Example

Header Parameters

Example

Request Body required

Example

Responses

200

Example

400

Example

401

Example

Request Body^required