Docs
Vedic Astrology
Panchang
Festivals

POST · VEDIC

Festivals

Endpoint POST https://starsapi.com/api/v3/vedic/panchang/festivals

Returns the Hindu festival calendar for a year — 155 festivals and vrats, computed from the actual panchang for the supplied location. Nothing is a static lookup: every date is derived from its defining tithi and the kaal at which the observance is decided.

Most festivals fall on the day their tithi touches sunrise (udaya), but many do not. Diwali is fixed by Amavasya during pradosh; Maha Shivaratri by Chaturdashi at nishita; Karva Chauth by Chaturthi between sunset and moonrise; Krishna Janmashtami by Ashtami and Rohini together. Each rule is applied per festival, so the returned dates match observed practice rather than a naive sunrise lookup.

Responses include English and Hindi names and descriptions, days-until labels, adhik-maas handling, kshaya-tithi notes, Bhadra windows, and dual dates where Smarta and Vaishnava traditions differ.

Authentication

Method	Example
Header (recommended)	`X-Api-Key: sa_live_xxxxxxxxxxxx`
Bearer	`Authorization: Bearer sa_live_xxxxxxxxxxxx`
Query	`?api_key=sa_live_xxxxxxxxxxxx`

Request body

Field	Type	Required	Description
`year`	integer	Yes	Calendar year, 1800–2400.
`timezone`	string	Yes	IANA timezone (e.g. `Asia/Kolkata`). Also fixes what “today” means for `days_until`.
`latitude`	number	Yes	Decimal degrees, −90 to 90.
`longitude`	number	Yes	Decimal degrees, −180 to 180.
`month`	integer	No	1–12. Narrows the list to one calendar month.
`category`	string	No	`major`, `important` or `vrat`. Comma-separated for several: `"major,vrat"`.
`key`	string	No	One or more festival keys: `"diwali"` or `"diwali,holi"`. Keys that do not occur in that year come back in `not_found`.
`place`	string	No	Free-text label, echoed back in `location.place`.

Location matters. Sunrise, sunset and moonrise decide most festival dates, so the same year can resolve differently for two cities. Always send the user's real coordinates.

Response shape

Top level

Field	Type	Description
`year` `month` `month_name`	—	Echo of the request. `month` and `month_name` are `null` when no month filter was sent.
`adhik_maas`	object	`has_adhik_maas`, and when true the month name plus its full start–end window. Always present; `has_adhik_maas: false` in ordinary years.
`next_festival`	object \| null	The next festival from the returned list. Filter to March and it will be the next one in March — `null` if that month has already passed.
`total_count`	integer	Festivals after all filters.
`festivals`	object	Grouped by English month name. Always an object, `{}` when nothing matches.
`not_found`	array	Only when `key` was sent. Keys that do not occur in that year — e.g. `padmini_ekadashi` outside an adhik-maas year.

Festival object

Field	Type	Description
`key`	string	Stable identifier — use this, not the name.
`name` `name_hindi`	string	Display names.
`date` `day` `day_hindi`	string	ISO date and weekday.
`category`	string	`major`, `important` or `vrat`.
`hindu_month`	string	Purnimant month. `"Adhik Jyeshtha"` for adhik-maas entries.
`description` `description_hindi`	string	One-line explanation.
`region`	string	Primary observing region.
`days_until`	integer	Days from today. Negative once past (`-134`). Independent of any filter.
`days_label` `days_label_hindi`	string	Ready to display: `"in 2 days"`, `"Today"`, `"134 days ago"`.
`tradition`	string \| null	`"smarta"`, `"vaishnava"`, or `"smarta,vaishnava"` when both fall together.
`alternate`	object \| null	Second date when the traditions differ — see below.
`bhadra`	object \| null	Bhadra window for festivals where it is relevant — see below.
`is_kshaya`	boolean	True when the tithi never touched a sunrise.
`tithi_note` `tithi_note_hindi`	string \| null	Explains the kshaya case. `null` otherwise.

Smarta and Vaishnava dates

Ram Navami and Krishna Janmashtami are decided differently by the two traditions and can land on different days. Rather than emit two entries that the date sort would separate, the endpoint returns one entry with an alternate block.

{
  "key": "ram_navami",
  "date": "2026-03-26",
  "tradition": "smarta",
  "alternate": {
    "date": "2026-03-27",
    "day": "Friday",
    "tradition": "vaishnava",
    "days_until": -109,
    "days_label": "109 days ago"
  }
}

When both traditions agree on the day, there is a single date and alternate is null:

{
  "key": "krishna_janmashtami",
  "date": "2026-09-04",
  "tradition": "smarta,vaishnava",
  "alternate": null
}

Bhadra

Bhadra (Vishti karana) is inauspicious for Holika Dahan, so the window is reported wherever it is relevant. It is informational — the returned date already accounts for the tithi rules.

"bhadra": {
  "present": true,
  "in_pradosh": true,
  "start": "2026-03-02 17:56",
  "end": "2026-03-03 05:28",
  "vaas": "mrityu"
}

vaas is swarga, patala or mrityu, from the Moon's sidereal rashi during Bhadra.

Kshaya tithi

A tithi can begin after one sunrise and end before the next — touching no sunrise at all. The festival is not dropped; it is placed by the rule its observance demands (usually the day the tithi begins), and flagged:

"is_kshaya": true,
"tithi_note": "Kshaya tithi — the tithi does not touch any sunrise. Observed on the day the tithi begins."

Gudi Padwa 2026 is one such case, which is why some calendars disagree on it.

Monthly vrats

Three observances repeat every lunar month and are returned with category: "vrat". Their names change with the day or month:

Key	Per year	Names
`pradosh_vrat`	~25	By weekday — Ravi, Soma, Bhauma, Budha, Guru, Shukra, Shani Pradosh Vrat.
`sankashti_chaturthi`	12–13	By month — Lambodara, Dwijapriya, Bhalachandra … and Vibhuvana in an adhik month.
`masik_shivratri`	12–13	Maha Shivaratri in Phalguna, Sawan Shivaratri in Shravana, Masik Shivaratri otherwise.

Every entry shares the same key, so filter on date or hindu_month, not key, when you need a specific occurrence.

Adhik maas

In an adhik-maas year the festivals stay with the nija month, but the adhik month has observances of its own — Padmini and Parama Ekadashi, plus its own Pradosh, Sankashti and Masik Shivaratri. These appear with hindu_month: "Adhik Jyeshtha".

adhik_maas is present every year; check has_adhik_maas before reading the rest.

Errors

HTTP	Code	Cause
400	`MISSING_FIELD`	Required field absent.
400	`INVALID_DATE`	Year outside 1800–2400, or month outside 1–12.
400	`INVALID_VALUE`	Unknown `category`, or malformed `key`.
400	`INVALID_TIMEZONE`	Non-IANA timezone.
400	`INVALID_COORDINATE`	Lat/lon out of range.
405	`METHOD_NOT_ALLOWED`	Non-POST request.

An unknown key is not an error — it comes back in not_found with an empty festivals object.

# Replace YOUR_API_KEY with the key from your dashboard
curl -X POST "https://starsapi.com/api/v3/vedic/panchang/festivals" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "year": 2026,
        "month": 3,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata"
    }'

const response = await fetch(
  'https://starsapi.com/api/v3/vedic/panchang/festivals',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      year: 2026,
      month: 3,
      latitude: 28.6139,
      longitude: 77.209,
      timezone: 'Asia/Kolkata'
    })
  }
);
const result = await response.json();

if (result.success) {
  console.log(result.data);
}

import requests
import os

response = requests.post(
    'https://starsapi.com/api/v3/vedic/panchang/festivals',
    headers={'X-Api-Key': os.environ['STARSAPI_KEY']},
    json={
        'year': 2026,
        'month': 3,
        'latitude': 28.6139,
        'longitude': 77.209,
        'timezone': 'Asia/Kolkata'
    }
)
result = response.json()

if result['success']:
    print(result['data'])

<?php
$payload = [
    'year' => 2026,
    'month' => 3,
    'latitude' => 28.6139,
    'longitude' => 77.209,
    'timezone' => 'Asia/Kolkata',
];

$ch = curl_init('https://starsapi.com/api/v3/vedic/panchang/festivals');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Api-Key: ' . getenv('STARSAPI_KEY'),
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    print_r($data['data']);
}

import 'package:http/http.dart' as http;
import 'dart:convert';

Future<Map<String, dynamic>> getAscendant() async {
  final response = await http.post(
    Uri.parse('https://starsapi.com/api/v3/vedic/panchang/festivals'),
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: jsonEncode({
      'year': 2026,
      'month': 3,
      'latitude': 28.6139,
      'longitude': 77.209,
      'timezone': 'Asia/Kolkata',
    }),
  );
  return jsonDecode(response.body);
}

import Foundation

func getAscendant() async throws -> [String: Any] {
    var request = URLRequest(url: URL(string:
        "https://starsapi.com/api/v3/vedic/panchang/festivals"
    )!)
    request.httpMethod = "POST"
    request.setValue("YOUR_API_KEY", forHTTPHeaderField: "X-Api-Key")
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = """
        {
            "year": 2026,
            "month": 3,
            "latitude": 28.6139,
            "longitude": 77.209,
            "timezone": "Asia/Kolkata"
        }
        """.data(using: .utf8)

    let (data, _) = try await URLSession.shared.data(for: request)
    return try JSONSerialization.jsonObject(with: data) as! [String: Any]
}

import okhttp3.*
import org.json.JSONObject

val client = OkHttpClient()
val JSON = "application/json; charset=utf-8".toMediaType()

fun getAscendant(callback: (JSONObject) -> Unit) {
    val payload = """
    {
        "year": 2026,
        "month": 3,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata"
    }
    """.trimIndent()

    val request = Request.Builder()
        .url("https://starsapi.com/api/v3/vedic/panchang/festivals")
        .addHeader("X-Api-Key", "YOUR_API_KEY")
        .post(payload.toRequestBody(JSON))
        .build()

    client.newCall(request).enqueue(object : Callback {
        override fun onResponse(call: Call, response: Response) {
            callback(JSONObject(response.body!!.string()))
        }
        override fun onFailure(call: Call, e: java.io.IOException) {
            e.printStackTrace()
        }
    })
}

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    payload, _ := json.Marshal(map[string]interface{}{
        "year": 2026,
        "month": 3,
        "latitude": 28.6139,
        "longitude": 77.209,
        "timezone": "Asia/Kolkata",
    })

    req, _ := http.NewRequest("POST",
        "https://starsapi.com/api/v3/vedic/panchang/festivals",
        bytes.NewBuffer(payload))
    req.Header.Set("X-Api-Key", os.Getenv("STARSAPI_KEY"))
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Println(result["data"])
}

require 'net/http'
require 'json'

uri = URI('https://starsapi.com/api/v3/vedic/panchang/festivals')
payload = {
  'year' => 2026,
  'month' => 3,
  'latitude' => 28.6139,
  'longitude' => 77.209,
  'timezone' => 'Asia/Kolkata'
}

req = Net::HTTP::Post.new(uri)
req['X-Api-Key'] = ENV['STARSAPI_KEY']
req['Content-Type'] = 'application/json'
req.body = payload.to_json

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
res = http.request(req)

data = JSON.parse(res.body)
puts data['data'] if data['success']

200 RESPONSE

{
  "status": 200,
  "success": true,
  "data": {
    "year": 2026,
    "month": 3,
    "month_name": "March",
    "timezone": "Asia/Kolkata",
    "location": {
      "latitude": 28.6139,
      "longitude": 77.209
    },
    "adhik_maas": {
      "has_adhik_maas": true,
      "month": "Jyeshtha",
      "start": "2026-05-17",
      "end": "2026-06-15",
      "note": "Adhik Maas: Jyeshtha (extra month)"
    },
    "next_festival": null,
    "total_count": 3,
    "festivals": {
      "March": [
        {
          "key": "holika_dahan",
          "name": "Holika Dahan",
          "name_hindi": "\u0939\u094b\u0932\u093f\u0915\u093e \u0926\u0939\u0928",
          "date": "2026-03-02",
          "day": "Monday",
          "day_hindi": "\u0938\u094b\u092e\u0935\u093e\u0930",
          "category": "major",
          "hindu_month": "Phalguna",
          "description": "Bonfire night before Holi",
          "description_hindi": "\u0939\u094b\u0932\u0940 \u0938\u0947 \u090f\u0915 \u0930\u093e\u0924 \u092a\u0942\u0930\u094d\u0935 \u0905\u0917\u094d\u0928\u093f \u0909\u0924\u094d\u0938\u0935",
          "region": "Pan-India",
          "tradition": null,
          "days_until": -134,
          "days_label": "134 days ago",
          "days_label_hindi": "134 \u0926\u093f\u0928 \u092a\u0939\u0932\u0947",
          "alternate": null,
          "bhadra": {
            "present": true,
            "in_pradosh": true,
            "start": "2026-03-02 17:56",
            "end": "2026-03-03 05:28",
            "vaas": "mrityu"
          },
          "is_kshaya": false,
          "tithi_note": null,
          "tithi_note_hindi": null
        },
        {
          "key": "gudi_padwa",
          "name": "Gudi Padwa / Ugadi",
          "name_hindi": "\u0917\u0941\u0921\u093c\u0940 \u092a\u0921\u093c\u0935\u093e / \u0909\u0917\u093e\u0926\u0940",
          "date": "2026-03-19",
          "day": "Thursday",
          "day_hindi": "\u0917\u0941\u0930\u0941\u0935\u093e\u0930",
          "category": "major",
          "hindu_month": "Chaitra",
          "description": "New Year \u2014 Maharashtra / Karnataka / Andhra",
          "description_hindi": "\u092e\u0939\u093e\u0930\u093e\u0937\u094d\u091f\u094d\u0930, \u0915\u0930\u094d\u0928\u093e\u091f\u0915 \u0935 \u0906\u0928\u094d\u0927\u094d\u0930 \u0915\u093e \u0928\u0935\u0935\u0930\u094d\u0937",
          "region": "Maharashtra/South",
          "tradition": null,
          "days_until": -117,
          "days_label": "117 days ago",
          "days_label_hindi": "117 \u0926\u093f\u0928 \u092a\u0939\u0932\u0947",
          "alternate": null,
          "bhadra": null,
          "is_kshaya": true,
          "tithi_note": "Kshaya tithi \u2014 the tithi does not touch any sunrise. Observed on the day the tithi begins.",
          "tithi_note_hindi": "\u0915\u094d\u0937\u092f \u0924\u093f\u0925\u093f \u2014 \u092f\u0939 \u0924\u093f\u0925\u093f \u0915\u093f\u0938\u0940 \u0938\u0942\u0930\u094d\u092f\u094b\u0926\u092f \u0915\u094b \u0938\u094d\u092a\u0930\u094d\u0936 \u0928\u0939\u0940\u0902 \u0915\u0930\u0924\u0940\u0964 \u0924\u093f\u0925\u093f \u092a\u094d\u0930\u093e\u0930\u0902\u092d \u0915\u0947 \u0926\u093f\u0928 \u092e\u0928\u093e\u092f\u093e \u091c\u093e\u0924\u093e \u0939\u0948\u0964"
        },
        {
          "key": "ram_navami",
          "name": "Ram Navami",
          "name_hindi": "\u0930\u093e\u092e \u0928\u0935\u092e\u0940",
          "date": "2026-03-26",
          "day": "Thursday",
          "day_hindi": "\u0917\u0941\u0930\u0941\u0935\u093e\u0930",
          "category": "major",
          "hindu_month": "Chaitra",
          "description": "Birth of Lord Rama",
          "description_hindi": "\u092d\u0917\u0935\u093e\u0928 \u0930\u093e\u092e \u0915\u093e \u091c\u0928\u094d\u092e\u0926\u093f\u0928",
          "region": "Pan-India",
          "tradition": "smarta",
          "days_until": -110,
          "days_label": "110 days ago",
          "days_label_hindi": "110 \u0926\u093f\u0928 \u092a\u0939\u0932\u0947",
          "alternate": {
            "date": "2026-03-27",
            "day": "Friday",
            "day_hindi": "\u0936\u0941\u0915\u094d\u0930\u0935\u093e\u0930",
            "name": "Ram Navami",
            "name_hindi": "\u0930\u093e\u092e \u0928\u0935\u092e\u0940",
            "tradition": "vaishnava",
            "days_until": -109,
            "days_label": "109 days ago",
            "days_label_hindi": "109 \u0926\u093f\u0928 \u092a\u0939\u0932\u0947",
            "description": "Birth of Lord Rama \u2014 Vaishnava tradition",
            "description_hindi": "\u092d\u0917\u0935\u093e\u0928 \u0930\u093e\u092e \u0915\u093e \u091c\u0928\u094d\u092e\u094b\u0924\u094d\u0938\u0935 \u2014 \u0935\u0948\u0937\u094d\u0923\u0935 \u092a\u0930\u0902\u092a\u0930\u093e"
          },
          "bhadra": null,
          "is_kshaya": false,
          "tithi_note": null,
          "tithi_note_hindi": null
        }
      ]
    }
  },
  "meta": {
    "endpoint": "/api/v3/vedic/panchang/festivals",
    "version": "3.0"
  }
}