curl -X POST https://yogataraapi.prahlad.app/api/astro/festival/ \
-H "X-API-Key: $OCCULT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"keys":["calculate_festivals"],"moon_option":"amavas","year":2025,"date_time":"2025-02-12T08:35:00.795Z","latitude":26.9124,"longitude":75.7873,"timezone_as_float":5.5}'Every Hindu festival of a calendar year computed from first principles for the place you give, together with the ekadashis and the Jain, Sikh and Christian observances the engine tracks. Unlike the regional calendar endpoints, which return a curated list per tradition, this is the full pan-Indian set with the exact tithi window attached to each entry. The year is walked tithi by tithi rather than day by day, so a tithi shorter than twenty-four hours cannot slip through unseen and a long one cannot be counted twice. `moon_option` decides how lunar months are named: 'poornima' uses the purnimanta month directly, while anything else — including 'amavas' itself — takes the amanta month and converts it, which is what most North Indian panchangs print. Send `year`, `date_time` and the place. Because each entry carries the governing tithi's start and end rather than a single date, you decide which civil day to show it on; if you would rather have that decision made for you, use one of the regional calendar endpoints, which resolve each observance to its correct observed day.
| Field | Type | Required | Notes |
|---|---|---|---|
| date_time | string (date-time) | required | The moment to calculate for, ISO 8601. ALWAYS include an offset or a trailing Z - a value with no zone is read as Asia/Kolkata (UTC+05:30), not UTC, and can return the previous day's result with a 200. '2026-09-01T06:00:00Z' and '2026-09-01 06:00:00' are different instants and give different answers. FORMAT constraint. DRF DateTimeField: ISO-8601 only (DRF default input formats), e.g. "2026-09-01T06:00:00+05:30", "2026-09-01T06:00:00Z" or "2026-09-01 06:00:00" (no timezone = UTC assumed). |
| keys | array | required | 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. calculate_festivalsArray of strings; only one key exists. |
| latitude | number (double) | required | Latitude of the place, in decimal degrees. Positive is north, negative is south. Example: 26.9124 for Jaipur, 40.7128 for New York. Minutes and seconds are not accepted - convert first. min -89.9 · max 89.9 |
| longitude | number (double) | required | Longitude of the place, in decimal degrees. Positive is east, negative is west. Example: 75.7873 for Jaipur, -74.0060 for New York. Note the sign: a missing minus puts New York in China. min -180 · max 180 |
| moon_option | string | required | amavaspoornimaCase-sensitive lowercase. 'poornima' uses the purnimanta lunar month directly; ANY other value - including 'amavas' itself and any typo - takes the else branch (amanta month converted to purnimanta), so misspellings silently behave as 'amavas'. Forwarded at. |
| timezone_as_float | number (double) | required | UTC offset of the place, in hours, as a decimal. Example: 5.5 for India (UTC+05:30), -5 for New York in winter, 5.75 for Nepal. This is NOT validated against date_time - if the two disagree you get a successful response for the wrong moment, so derive both from the same source. Use the offset in force on that date, not today's: a summer birth in a country with daylight saving needs the summer offset. min -12 · max 14 |
| year | integer | required | Year of birth as a number, e.g. 1990. Four digits. |
Ask for exactly the calculations you want by listing them in keys. An unknown key rejects the whole request, and you are charged 1 credit however many you ask for — so batch them.
| Key | Extra fields needed | Description | |
|---|---|---|---|
| calculate_festivals | year | The whole year's observances, as an object with five lists: `festivals`, `ekadashis`, `jain_festivals`, `sikh_festivals` and `christian_festivals`. Each entry carries the festival name, the `start` and `end` of the governing tithi as UTC timestamp strings, and the lunar `month`; ekadashi entries also carry the `paksha`. Takes `year`. |