Skip to content
Occult API
POST/api/festivals/1 credit

Festival calendar

Precomputed festival dates across four traditions, read straight from a table rather than calculated on the request, so a whole year comes back in one indexed query. `keys` chooses which lists you want: `festivals` is the main Hindu calendar, `ekadashis` the twenty-four or twenty-six named Ekadashis of the year, and `jain_festivals`, `sikh_festivals` and `christian_festivals` the corresponding calendars. `year` is required and `month` (1-12) is optional; omit the month to get the whole year. The response is `{data}` keyed by each requested category, each holding a chronological list of events. An event carries `name`, `name_hi` (a Hindi rendering, currently populated only for the main Hindu category and null elsewhere), `month` (the lunar month name), `paksha`, `tithi` (used by the Sikh list), `date` (used where the observance is on a fixed civil date, as the Christian festivals are) and `start_time`/`end_time`, which are the exact instants the governing tithi begins and ends. Dates are precomputed for the years 2006 to 2046 inclusive. Anything outside that range returns empty lists rather than an error. Because the underlying rows are stored rather than derived per request, this endpoint takes no coordinates; if you need a location-sensitive observance day, use the regional calendar endpoints, which resolve each festival to a civil day using local sunrise and sunset.

https://yogataraapi.prahlad.app/api/festivals/
Test Request

Authentication

Send your key in the X-API-Key header. Keys are server-side credentials — never put one in browser JavaScript or a mobile app.

X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/json

Request fields

FieldTypeRequiredNotes
keysarrayrequired

Which calculations to return, as a list of names. See the key table for this endpoint; an unrecognised name rejects the whole request. One call costs one credit however many keys you ask for, so request everything you need at once rather than making several calls.

festivalsekadashisjain_festivalssikh_festivalschristian_festivals

Which festival calendars to return. 'festivals' is the main Hindu calendar; the others are separate traditions. Ask for several in one call - the response is keyed by category and the cost is the same.

yearintegerrequired

Year of birth as a number, e.g. 1990. Four digits.

Four-digit year. Dates are precomputed for 2006 to 2046; outside that range the response is empty.

monthintegeroptional

Month of birth as a number, 1-12. January is 1.

Optional 1-12. Omit it to get the whole year.

min 1 · max 12

Example request

curl -X POST https://yogataraapi.prahlad.app/api/festivals/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"month":9,"keys":["festivals","ekadashis"]}'

Response

{
  "_truncated": true,
  "_note": "Response shortened for the catalogue.",
  "preview": "{\"data\": {\"festivals\": [{\"name\": \"Janmashtami\", \"name_hi\": \"जन्माष्टमी\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-04T02:26:25+05:30\", \"end_time\": \"2026-09-05T00:14:34+05:30\"}, {\"name\": \"Gugga Navmi\", \"name_hi\": \"गूगा नवमी\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-05T00:14:34+05:30\", \"end_time\": \"2026-09-05T21:54:40+05:30\"}, {\"name\": \"Vatsa Dvadashi\", \"name_hi\": \"वत्स द्वादशी\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-07T17:05:07+05:30\", \"end_time\": \"2026-09-08T14:43:55+05:30\"}, {\"name\": \"Kushotpaatini Ama\", \"name_hi\": \"कुशोत्पाटिनी अमावस्या\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-09T12:31:45+05:30\", \"end_time\": \"2026-09-10T10:34:16+05:30\"}, {\"name\": \"Hartalika Teej\", \"name_hi\": \"हरतालिका तीज\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-13T07:09:27+05:30\", \"end_time\": \"2026-09-14T07:08:00+05:30\"}, {\"name\": \"Varaha Jayanti\", \"name_hi\": \"वराह जयंती\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-13T07:09:27+05:30\", \"end_time\": \"2026-09-14T07:08:00+05:30\"}, {\"name\": \"Rishi Tarpana (Samvedic)\", \"name_hi\": \"ऋषि तर्पण (सामवेदिक)\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-13T07:09:27+05:30\", \"end_time\": \"2026-09-14T07:08:00+05:30\"}, {\"name\": \"Siddhi Vinayaka Vrata\", \"name_hi\": \"सिद्धि विनायक व्रत\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-14T07:08:00+05:30\", \"end_time\": \"2026-09-15T07:45:17+05:30\"}, {\"name\": \"Ganesh Chaturthi\", \"name_hi\": \"गणेश चतुर्थी\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-14T07:08:00+05:30\", \"end_time\": \"2026-09-15T07:45:17+05:30\"}, {\"name\": \"Rishi Panchami\", \"name_hi\": \"ऋषि पंचमी\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-15T07:45:17+05:30\", \"end_time\": \"2026-09-16T09:00:28+05:30\"}, {\"name\": \"Balarama Jayanti\", \"name_hi\": \"बलराम जयंती\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-16T09:00:28+05:30\", \"end_time\": \"2026-09-17T10:49:00+05:30\"}, {\"name\": \"Radhashtami\", \"name_hi\": \"राधाष्टमी\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-18T13:02:12+05:30\", \"end_time\": \"2026-09-19T15:28:04+05:30\"}, {\"name\": \"Radha Ashtami\", \"name_hi\": \"राधा अष्टमी\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-18T13:02:12+05:30\", \"end_time\": \"2026-09-19T15:28:04+05:30\"}, {\"name\": \"Mahaluxmi Vrata begins\", \"name_hi\": \"महालक्ष्मी व्रत प्रारंभ\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-18T13:02:12+05:30\", \"end_time\": \"2026-09-19T15:28:04+05:30\"}, {\"name\": \"Vishnu Parivartanotsava\", \"name_hi\": \"विष्णु परिवर्तनोत्सव\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-22T21:44:20+05:30\", \"end_time\": \"2026-09-23T22:51:32+05:30\"}, {\"name\": \"Vamana Jayanti\", \"name_hi\": \"वामन जयंती\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-22T21:44:20+05:30\", \"end_time\": \"2026-09-23T22:51:32+05:30\"}, {\"name\": \"Anant Chaturdashi\", \"name_hi\": \"अनंत चतुर्दशी\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-24T23:19:27+05:30\", \"end_time\": \"2026-09-25T23:07:49+05:30\"}, {\"name\": \"Ganesh Visarjan\", \"name_hi\": \"गणेश विसर्जन\", \"month\": \"Bhadrapada\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-24T23:19:27+05:30\", \"end_time\": \"2026-09-25T23:07:49+05:30\"}, {\"name\": \"Pitrupaksha Begins\", \"name_hi\": \"पितृपक्ष प्रारंभ\", \"month\": \"Ashwin\", \"paksha\": null, \"tithi\": null, \"date\": null, \"start_time\": \"2026-09-26T22:19:32+05:30\", \"end_time\": \"2026-09"
}

Captured from a real call using the exact request above. Results sit under data.

Errors

Metering errors return { "error": "…", "message": "<code>", "is_error": true }. Show error to people and branch on message. See the error reference.