Timing
Hindu Calendar API for festivals and fasting days
Updated
How the Hindu calendar API works
- 1The Hindu calendar follows the Moon, so each date has a lunar day, from new moon to full moon and back.
- 2Festivals fall on set lunar days, so their dates move each year and can differ by place.
- 3The API returns every day of a month and every festival of a year for the place you give, with the time each festival needs.
GET /v1/festivals/diwali?year=2026&latitude=40.7128&longitude=-74.006&timezone=America/New_York200 OK{
"festival": {
"name": "Diwali (Lakshmi Puja)",
"date": "2026-11-08",
"kaal": "pradosh",
"kaal_window": {
"starts": "2026-11-08T16:44:24-05:00",
"ends": "2026-11-08T19:30:41-05:00"
},
"decided_by": "the only day the tithi holds pradosh"
}
}Call the Hindu calendar API from your code
Send the details as JSON with your API key in the Authorization header. Copy the code, set ASTROLOGY_API_KEY to your key, and run it.
GET /v1/festivals/diwali
# New York
curl "https://apiforastrology.com/api/astrology/v1/festivals/diwali?year=2026&latitude=40.7128&longitude=-74.006&timezone=America/New_York" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY"{
"year": 2026,
"place": {
"latitude": 40.7128,
"longitude": -74.006,
"timezone": -5,
"timezone_info": {
"source": "zone",
"offset_hours": -5,
"zone": "America/New_York",
"abbreviation": "EST",
"dst": false,
"dst_hours": 0,
"ambiguous_resolved_by_fold": null,
"note": "read from the IANA tz database at this instant, so daylight saving and historical offset changes are included"
},
"note": "this zone changes offset during the year; each time uses the offset in force on its own date (UTC-5 in January, UTC-4 in July) and ends with that offset"
},
"convention": "purnimanta",
"festival": {
"date": "2026-11-08",
"kaal": "pradosh",
"decided_by": "the only day the tithi holds pradosh",
"coverage": 1,
"kaal_window": {
"starts": "2026-11-08T16:44:24-05:00",
"ends": "2026-11-08T19:30:41-05:00"
},
"slug": "diwali",
"name": "Diwali (Lakshmi Puja)",
"masa": {
"name": "Kartika",
"purnimanta": "Kartika",
"amanta": "Asvina",
"paksha": "krishna",
"tithi": 15
},
"tithi": {
"starts": "2026-11-08T00:58:22-05:00",
"ends": "2026-11-09T02:02:07-05:00"
}
}
}What the Hindu calendar API returns
- The dates of major Hindu festivals for any year from 1850 to 2149, such as Diwali, Holi, Navratri, Raksha Bandhan and Krishna Janmashtami.
- For each festival: the date, the part of the day it needs (such as early evening for Diwali), and that window's start and end time. Also decided_by, the rule that chose the day.
- Where traditions keep a festival on different days, as with Janmashtami, the response says so and gives the other date.
- Every monthly fasting day (vrat) in a year: Ekadashi, Pradosh, Sankashti Chaturthi, Masik Shivaratri, Purnima and Amavasya. Ask for only the ones you need, such as kind=ekadashi,pradosh.
- A month calendar with one row per day. Each row has the four calendar parts at sunrise: tithi (lunar day), nakshatra (star group), yoga and karana. It also has the lunar month and that day's festivals and fasts.
- Leap months (adhika masa) are found, and a tithi that starts and ends between two sunrises is listed as skipped, as printed calendars mark it.
- Every solar and lunar eclipse (grahan) in a date range, with its contact times. For a place that can see it, you also get sutak, the hours before it that tradition keeps aside.
The first call for a new year and place takes about 8 seconds while the API builds that year's calendar. Later calls are fast. Always send latitude, longitude and timezone: without them, the dates are for Ujjain, India.
Hindu calendar API endpoints
GET /v1/panchang/monthPanchang calendar for a month, with festivals and fastsGET /v1/festivalsHindu festival dates for a year and placeGET /v1/festivals/{slug}One festival's date for a year and placeGET /v1/vratsMonthly fasting days (vrats) for a year and placeGET /v1/eclipsesEclipses (grahan) with local times and sutak
What it uses from your plan
Each call to these endpoints uses 1 call from your monthly allowance. Failed requests are free.
See the plansThe rules behind the Hindu calendar API
A festival falls on a tithi (lunar day) in a named lunar month. It is kept on the day when that tithi is running during the part of the day the festival needs. That is early evening (pradosh) for Diwali, midday for Ganesh Chaturthi and midnight for Janmashtami. Each month comes with its North Indian (purnimanta) and its Maharashtra and Gujarat (amanta) name, and no festival is kept in a leap month. Festivals from the Marathi and Gujarati calendars, such as Gudi Padwa and Bestu Varas, carry a region field. The fasting days were checked against a widely used published calendar: 495 of 496 dates for New Delhi and Beijing matched.
How we check the numbers
Every answer here starts from planet positions worked out from NASA JPL planet data (DE440). We test them against NASA JPL Horizons, NASA's planet position service. On 25,571 positions from 1850 to 2149, the Sun and planets agree within 0.001 arc seconds. The Moon agrees within 0.011. On 2,000 random birth charts, the rising sign agrees with Swiss Ephemeris within 0.004. An arc second is 1/3,600 of a degree. Our tests fail if a result drifts past these figures.
A practicing astrologer reviews the rules behind these answers. Each rule has an ID you can look up in the public rulebook.
See how we test accuracyWho uses it
From the blog
· 9 min read
Hindu Calendar 2027: Festival Dates for App Builders
Hindu calendar 2027 for New York and India.
Read
· 8 min read
Kundli and Panchang for Puja Stores and Temple Websites
Four features that bring visitors back to a puja store or temple site, the API call behind each…
Read
· 8 min read
Why Rahu Kaal Changes by City: A Panchang API Guide
What a panchang API returns for one day, and why each city gets its own answer.
Read
Hindu calendar API questions
All questionsWhy do some dates differ from a calendar printed in India?
A festival day depends on sunrise and on a part of the day, such as early evening for Diwali, and both move with the place. So a city far from India can keep a festival a day earlier or later. The API works out the day for the coordinates you send.
Which festivals are included?
Major Hindu festivals, such as Makar Sankranti, Maha Shivaratri, Holi, Ram Navami and Raksha Bandhan. Also Krishna Janmashtami, Ganesh Chaturthi, the start of Navratri, Dussehra, Karva Chauth and Diwali. GET /v1/festivals returns them all for a year with their IDs, and GET /v1/festivals/diwali returns one.
See the festival endpointsWhat happens when traditions keep a festival on different days?
The response says so. Where sources really differ, as with Janmashtami and Ekadashi, it sets sources_agree to false and adds other_tradition_date. Every date also has decided_by, the rule that chose it, so you can show your users why.
Which lunar month system does the Hindu calendar API use?
Every month comes with both names: purnimanta, where a month ends at the full moon (North India), and amanta, where it ends at the new moon (Maharashtra, Gujarat and South India). Send calendar=amanta or calendar=purnimanta to choose the main one. Dates never change. Leap months are found: no festival is kept in one, but the monthly vrats still are.
What a lunar month isDo festival times follow daylight saving time?
The dates are not affected. But in a zone that changes its clocks, such as America/New_York, clock times from /v1/festivals and /v1/vrats use the January offset, and place.note says so. For exact times on one day, use the daily panchang, which applies the rule in force on that date.
Astrology API
Call it with a free test key
Create an account and a test key, then call any endpoint on this page. Or try a request in the API reference first.
Your first answer
John Doe, New York
- RisingVirgoHast
- SunCancerAshlesha
- MoonTaurusMrigashira
- MarsAriesKrittika
Real API output. A free test key gets the same answer.
01
Test key: 1,000 test calls a month to build with
02
Free plan: 2,000 live calls a month, no card needed
03
Open rules: every rule is published, so you can check any answer