Muhurat and festival dates API reference
Updated
The muhurat and festival endpoints of API for Astrology (apiforastrology.com) find festival dates and good times for a place. You get every festival and fasting day in a year, and every eclipse (grahan). You also get good windows (muhurat) to buy a vehicle or property, move home, marry or start a business. The group has 5 endpoints.
Call GET /v1/festivals for every Hindu festival date in a year at a place. GET /v1/festivals/{slug} gives one, such as Diwali. Each festival has a fixed id, listed on the Sections and IDs page. GET /v1/vrats gives the fasting days, such as Ekadashi. Always send the place, because a date can differ by city, as why festival dates change by city shows. POST /v1/muhurta/{activity} finds good windows (muhurat) to start an activity.
Dates and good times. The Hindu festival and fasting calendar for a year at a place. Also muhurtas (good times to start an activity): buying a vehicle, buying property, moving into a new home, and marriage, all checked against a published calendar: 161 of 161 festival dates, and all 579 published muhurta windows across those four activities and two years. Starting a business, travel and six child ceremonies (naming, first food, first haircut, ear piercing, start of learning, sacred thread) follow the classical rules and say they are not measured. Every answer names the rule that decided it. Nothing is scored or ranked.
5 endpoints. Paths are relative to https://apiforastrology.com/api/astrology. Send your API key in the Authorization: Bearer header (see authentication). No key yet? Get a key. To send test requests from the browser, open the interactive reference.
Overview: Hindu calendar and festivals, Panchang and muhurat.
Which muhurat or festival endpoint to call
| What you need | Endpoint | Cost |
|---|---|---|
| Good times to start an activity, such as buying a vehicle | POST /v1/muhurta/{activity} | 1 call |
| Every Hindu festival date in a year, for a place. Start here | GET /v1/festivals | 1 call |
| Monthly fasting days, such as Ekadashi and Pradosh, for a year | GET /v1/vrats | 1 call |
| One festival's date, such as Diwali, for a year and place | GET /v1/festivals/{slug} | 1 call |
| Solar and lunar eclipses for a place, with local times and sutak | GET /v1/eclipses | 1 call |
Muhurta: good times to start an activity
POST /v1/muhurta/{activity}
Returns every time window in the date range that passes the rules for an activity, in date order. A muhurta is a good time to start something, chosen from the Hindu calendar. Each window lists the rules it passed. It also lists any periods inside it that the rules do not exclude on purpose. Examples are rahu kaal and bhadra (periods traditionally avoided for new starts).
Nothing is scored or ranked. If two windows both pass, both are returned, and the choice is yours.
Add birth to make it personal. Each window then has for_you. It gives tara bala and chandra bala for that person (daily ratings based on the birth Moon). It also says whether the window suits them, and why not if it does not. It adds:
eighth: the parts of the window to avoid for this person. That is when the Moon is in the 8th sign from the birth Moon (chandrashtama). It is also when the rising sign is the 8th from the birth lagna or the birth Moon sign.clearis the time left, and can be empty. It is the classical rule and not measured against a published calendar, someasuredisfalse.in_short: the plain answer.statusisgood,partly(usebest_times) ornot_for_you, withtextandreasons, each acodeand its text, in the language asked for.
A window that is good for everyone at the place but poor for the person is marked, never hidden. count_for_you is how many windows are good or partly. For vivah (marriage), add partner too: each window then also has for_partner and suits_both.
Activities: vehicle (buying a vehicle), property (buying property), griha-pravesh (moving into a new home) and vivah (marriage). Also business (starting a business or launching a product) and travel (setting out on a journey).
Child ceremonies: namkaran (naming), annaprashan (first solid food), mundan (first haircut), karnavedha (ear piercing), vidyarambha (start of learning) and upanayana (sacred thread). For these, birth is the child's.
The age window comes first. Send the child's birth and only the time inside the right age is searched. Days run sunrise to sunrise, with the day of birth as day 1 (a birth before sunrise counts from the day before). Months and years are solar: a month is the Sun moving 30 degrees from where it was at birth, and a year runs from one return of the Sun to its birth position to the next.
namkaran: the 11th or 12th day.annaprashan: the 6th, 8th or 10th month for a boy, the 5th, 7th or 9th for a girl. Sendchild_sex(maleorfemale), or both sets are searched.mundan: the 1st, 3rd or 5th year.karnavedha: the 10th, 12th or 16th day, the 6th, 7th or 8th month, or the 1st, 3rd or 5th year.vidyarambha: the 5th year.upanayana: the 5th or 8th year, the 11th, or the 12th, as the texts give them for different traditions. All are searched and each window names its tradition; no caste or varna is asked for.
age_window gives each window's start and end and which your dates touched; each kept window has age_window.in. If your dates miss every window, no days come back and age_window.why_empty says why. Without birth, the dates you send are the age window kept, and age_window.applied is false.
Days that set checks aside. A window on such a day has override, naming what was waived and what was kept, and the waived rules show status: "waived". On the child's 11th and 12th days, namkaran waives the day checks and the child's tara and chandra bala. Only the rising sign is judged (the 8th sign from it must be empty and no harsh planet may sit in it), and rahu kaal and gulika kaal are cut. preferred marks windows with benefic planets in strong houses; nothing is ranked on it. Jupiter and Venus always count; the Moon only while bright (Shukla Ashtami to Krishna Panchami); Mercury only with no harsh planet in its sign. For vidyarambha, Vasant Panchami waives the tithi, weekday and nakshatra, and still cuts eclipses, sandhikala and an afflicted rising sign. special_days lists each Vasant Panchami in your dates, and, with birth, the 5th day of the 5th month of the 5th year (five_five_five).
If no time on the 11th or 12th day is safe, namkaran never forces a bad lagna to make that window work. postponed_to then names the next day, found by scanning forward: every ordinary check applies in full (nothing is waived past day 12), plus the same clean-lagna check. It searches up to 60 days (cap_days); hit_cap: true with found: null means none turned up. postponed_to is null whenever a time on day 11 or 12 is found.
For travel, each window has disha_shool: the direction to avoid setting out in that day. It is not cut, because the search is not told where you are going.
about is a short reading on the activity and what its rules look at, in the language asked for.
Where the rules come from. For vehicle, property, griha-pravesh and vivah they were read from a published calendar and checked against a second year. The others state the classical rules and have not been measured against a calendar; their provenance.measured is false and not_claimed says so. For business the fixed (sthira) lagna is cut, not just reported, and so is rahu kaal. The response gives each activity's source and how closely it matched.
Cost: Each successful request counts as 1 call toward your monthly calls.
Required inputs
| Name | In | What it is |
|---|---|---|
| activity | path | The activity: vehicle, property, griha-pravesh, vivah, business, travel, namkaran, annaprashan, mundan, karnavedha, vidyarambha or upanayana. An unknown value returns 404 with the list of valid ones. |
| from | body | First day to search, YYYY-MM-DD. |
| to | body | Last day to search, YYYY-MM-DD, inclusive. At most 366 days after from. |
| latitude | body | Latitude of the place where the activity happens, in degrees, negative for south. |
| longitude | body | Longitude of that place in degrees, negative for west. |
| timezone | body | Time zone of that place. Send an IANA time zone name such as America/New_York, or a fixed offset from UTC in hours such as -5. With a zone name, each window uses the offset in force on its own date. So daylight saving time is followed. |
Optional inputs (5), with their defaults
| Name | In | What it does |
|---|---|---|
| lang | query | Language of the reading text, such as en (English, the default) or hi (Hindi). GET /v1/meta lists the languages available. If a passage is not written in that language yet, the English passage is returned instead and marked with fell_back_to_en. Names in the response, such as planets and signs, are translated too. |
| detail | query | Length of the reading text: standard (the default) or expanded, which is about 1.8 times longer. If a passage has no expanded version yet, the standard one is returned. Each text block reports the length it got in its detail field. |
| birth | body | Optional. Birth data of the person the activity is for. Adds tara bala and chandra bala (daily ratings based on the birth Moon) for this person to every window. For a child ceremony (such as namkaran or mundan), send the child's. It also keeps only the time inside the child's age window (age_window). |
| child_sex | body | Optional, for annaprashan (first solid food): the child's sex, male or female. A boy's first food is in the 6th, 8th or 10th month, a girl's in the 5th, 7th or 9th. Without it both sets are searched and age_window.needs says child_sex. Ignored by the other activities. |
| partner | body | Optional, for a marriage (vivah): the other person's birth data. Each window then also has for_partner, and suits_both when birth is given too. |
Main response fields
activity(object): holds slug, name.place(object): holds latitude, longitude, timezone, timezone_info.from(string)to(string)windows(array of objects): each item holds date, weekday, starts, ends, minutes, nakshatras, tithis, rules, within_it.count(number)personal(boolean)see_also(null)about(object): holds text, gaps, language, detail.age(null)age_window(null)special_days(null)postponed_to(null)not_applied(object): holds rahu_kaal, bhadra, panchaka, yoga, lagna.not_computed(object): holds varjyam, amrit_kaal, godhuli.provenance(object): holds source, derived_from, checked_on, agreement.not_claimed(array of strings)
# New York, Nov 2, 2026 to Jan 31, 2027
curl -X POST "https://apiforastrology.com/api/astrology/v1/muhurta/vehicle" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"from":"2026-11-02","to":"2027-01-31","latitude":40.7128,"longitude":-74.006,"timezone":"America/New_York"}'{
"activity": {
"slug": "vehicle",
"name": "Buying a vehicle (car, bike)"
},
"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"
}
},
"from": "2026-11-02",
"to": "2027-01-31",
"windows": [
{
"date": "2026-11-06",
"weekday": "Friday",
"starts": "2026-11-06T06:32:19-05:00",
"ends": "2026-11-07T00:18:24-05:00",
"minutes": 1066,
"nakshatras": [
"Hast",
"Chitra"
],
"tithis": [
"Trayodashi"
],
"rules": [
{
"id": "MS-01",
"status": "pass",
"rule": "the nakshatra is one the activity allows",
"seen": [
"Hast",
"Chitra"
]
},
{
"id": "MS-02",
"status": "pass",
"rule": "the tithi is one the activity allows",
"seen": [
"Trayodashi (krishna)"
]
},
{
"id": "MS-03",
"status": "pass",
"rule": "the weekday (sunrise to sunrise) is one the activity allows",
"seen": [
"Friday"
]
}
],
"within_it": {
"rahu_kaal": {
"starts": "2026-11-06T10:22:38-05:00",
"ends": "2026-11-06T11:39:24-05:00"
}
}
},
{
"date": "2026-11-15",
"weekday": "Sunday",
"starts": "2026-11-15T12:59:06-05:00",
"ends": "2026-11-15T15:31:40-05:00",
"minutes": 153,
"nakshatras": [
"Shravan"
],
"tithis": [
"Shashthi"
],
"rules": [
{
"id": "MS-01",
"status": "pass",
"rule": "the nakshatra is one the activity allows",
"seen": [
"Shravan"
]
},
{
"id": "MS-02",
"status": "pass",
"rule": "the tithi is one the activity allows",
"seen": [
"Shashthi (shukla)"
]
},
{
"id": "MS-03",
"status": "pass",
"rule": "the weekday (sunrise to sunrise) is one the activity allows",
"seen": [
"Sunday"
]
}
],
"within_it": {
"rahu_kaal": {
"starts": "2026-11-15T15:23:34-05:00",
"ends": "2026-11-15T16:37:56-05:00"
}
}
},
{
"date": "2026-11-16",
"weekday": "Monday",
"starts": "2026-11-16T17:50:08-05:00",
"ends": "2026-11-17T06:45:16-05:00",
"minutes": 775,
"nakshatras": [
"Dhanishtha"
],
"tithis": [
"Ashtami"
],
"rules": [
{
"id": "MS-01",
"status": "pass",
"rule": "the nakshatra is one the activity allows",
"seen": [
"Dhanishtha"
]
},
{
"id": "MS-02",
"status": "pass",
"rule": "the tithi is one the activity allows",
"seen": [
"Ashtami (shukla)"
]
},
{
"id": "MS-03",
"status": "pass",
"rule": "the weekday (sunrise to sunrise) is one the activity allows",
"seen": [
"Monday"
]
}
],
"within_it": {
"bhadra": [
{
"starts": "2026-11-16T17:50:08-05:00",
"ends": "2026-11-17T06:47:49-05:00"
}
]
}
}
],
"count": 25,
"personal": false,
"see_also": null,
"about": {
"text": [
"These are good times to buy a car, a bike or any vehicle. Each time is chosen from the Hindu calendar. They look at the nakshatra (the star the Moon is in), the tithi (the lunar day) and the weekday.",
"The rules come from a published calendar and were checked against it, window by window. Pick any window that fits your plans."
],
"gaps": [],
"language": "en",
"detail": "standard"
},
"age": null,
"age_window": null,
"special_days": null,
"postponed_to": null,
"not_applied": {
"rahu_kaal": "published windows run straight through rahu kaal; it is returned beside each window, not cut out",
"bhadra": "163 hours of Vishti karana fall inside the published 2026 windows, including bhadra with the Moon in Karka, Kumbha and Meena -- so neither bhadra nor \"bhadra on earth\" is an exclusion here",
"panchaka": "Dhanishtha, Shatabhisha and Revati appear in the published windows",
"yoga": "every one of the 27 yogas, Vyatipata and Vaidhriti included, appears inside a published window",
"lagna": "the page names chara and dvisvabhava lagnas as good, but windows run for up to a day across every lagna; it is reported per window, not used to cut"
},
"not_computed": {
"varjyam": "read from a 27-row table of ghati offsets per nakshatra; not reproduced until the table is verified against a source",
"amrit_kaal": "same table family as varjyam; same reason",
"godhuli": "sources give different spans around sunset"
},
"provenance": {
"source": "A widely used published calendar, vehicle purchase muhurat, New Delhi (geoname 1261481), fetched 2026-09-16",
"derived_from": 2026,
"checked_on": 2027,
"agreement": {
"2026": "every one of the 88 published windows reproduced within 3 minutes at both ends; 96% of the hours returned are published hours",
"2027": "all 112 published windows reproduced within 3 minutes at both ends; 98.8% of the hours returned are published hours. Two of them needed MS-11, found afterwards on the property calendar"
}
},
"not_claimed": [
"no window is ranked above another and none is scored. Every returned window passes every rule of the activity",
"the rules are the published calendar's, measured against it window by window, not a single tradition's final word; a family astrologer may weigh further factors, and the payload names what is not applied so that is visible"
]
}Example from a real call for New York, Nov 2, 2026 to Jan 31, 2027. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Panchang and muhurat.
Hindu festival dates for a year and place
GET /v1/festivals
Each Hindu festival falls on a tithi (lunar day) in a named lunar month. It is kept on the calendar day when that tithi is running during the part of the day the festival needs. That is pradosh (early evening) for Diwali, midday for Ganesh Chaturthi, and midnight for Janmashtami. Each month is named both ways: masa.purnimanta (North India, where a month ends at the full moon) and masa.amanta (Maharashtra, Gujarat and South India, where it ends at the new moon). The two differ only in a month's waning half, and never change a date. calendar chooses which one goes in masa.name; without it, purnimanta (amanta for Marathi and Gujarati). Leap months (adhika masa) are detected, and no festival is kept in one.
Regional festivals from the Marathi and Gujarati calendars (Gudi Padwa, Vat Purnima, Pola, Bestu Varas, Shitala Satam and others) carry region: the calendar each was checked against (Maharashtra, Gujarat or both). Festivals without it are on the all-India list. The Gauri and Saraswati days are set by the Moon's nakshatra, not a tithi, and also carry nakshatra. Every regional date matches a widely used published calendar for Mumbai and Ahmedabad, 2026 to 2028.
Every date has decided_by, the rule that chose it. Where traditions really do differ (Janmashtami, Ekadashi), the response says sources_agree: false and gives other_tradition_date.
The place changes the day. Sunrise and the parts of the day move with longitude. So Delhi and Beijing keep four 2026 festivals a day apart, as published calendars for those cities do.
If the time zone uses daylight saving time, each clock time uses the offset in force on its own date. It ends with that offset; place.note says so. Without latitude, longitude and timezone, the calendar is for Ujjain, India.
Cost: Each successful request counts as 1 call toward your monthly calls.
Every festival id on the Sections and IDs page
Required inputs
| Name | In | What it is |
|---|---|---|
| year | query | Calendar year, from 1850 to 2149. |
Optional inputs (5), with their defaults
| Name | In | What it does |
|---|---|---|
| latitude | query | Latitude in degrees, negative for south. Defaults to Ujjain, India. |
| longitude | query | Longitude in degrees, negative for west. Defaults to Ujjain, India. |
| timezone | query | IANA time zone name such as America/New_York, or a fixed offset from UTC in hours such as -5. Defaults to 5.5 (India time). |
| lang | query | Language for the names in the response, such as planets, signs, nakshatras (lunar mansions), tithis (lunar days), months and festivals. The default is en (English); GET /v1/meta lists the others. Each translated value comes with its English original in a matching <field>_en field; use the English value as a key in your code. Codes (such as result or kaal) and object keys always stay in English. Any name not yet translated stays in English and is listed in localization.untranslated. |
| calendar | query | How to name the lunar months: amanta or purnimanta. In amanta calendars (Maharashtra, Gujarat and South India) a month ends at the new moon. In purnimanta calendars (North India) it ends at the full moon. Only the name of the month in its waning half differs. Dates never change. Both names are always in the response (amanta and purnimanta), and this setting chooses which one goes in name. Other languages keep this endpoint's usual one. convention says which was used. |
Main response fields
year(number)place(object): holds latitude, longitude, timezone, timezone_info, note.convention(string)festivals(array of objects): each item holds slug, name, date, decided_by, sankranti_at.
# New York
curl "https://apiforastrology.com/api/astrology/v1/festivals?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",
"festivals": [
{
"slug": "makar-sankranti",
"name": "Makar Sankranti",
"date": "2026-01-14",
"decided_by": "the day the Sun enters Makara, if it enters before sunset; otherwise the following day",
"sankranti_at": "2026-01-14T04:37:21-05:00"
},
{
"date": "2026-01-22",
"kaal": "madhyahna",
"decided_by": "the only day the tithi holds madhyahna",
"coverage": 1,
"kaal_window": {
"starts": "2026-01-22T11:09:05-05:00",
"ends": "2026-01-22T13:06:34-05:00"
},
"slug": "ganesh-jayanti",
"name": "Ganesh Jayanti",
"masa": {
"name": "Magha",
"purnimanta": "Magha",
"amanta": "Magha",
"paksha": "shukla",
"tithi": 4
},
"tithi": {
"starts": "2026-01-21T16:17:39-05:00",
"ends": "2026-01-22T15:58:52-05:00"
},
"region": [
"Maharashtra"
]
},
{
"date": "2026-01-23",
"kaal": "purvahna",
"decided_by": "the only day the tithi holds purvahna",
"coverage": 1,
"kaal_window": {
"starts": "2026-01-23T07:13:25-05:00",
"ends": "2026-01-23T12:08:05-05:00"
},
"slug": "vasant-panchami",
"name": "Vasant Panchami",
"masa": {
"name": "Magha",
"purnimanta": "Magha",
"amanta": "Magha",
"paksha": "shukla",
"tithi": 5
},
"tithi": {
"starts": "2026-01-22T15:58:52-05:00",
"ends": "2026-01-23T15:16:32-05:00"
}
}
]
}Example from a real call for New York. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Hindu calendar and festivals.
Monthly fasting days (vrats) for a year and place
GET /v1/vrats
Returns every Ekadashi, Pradosh, Sankashti Chaturthi, Masik Shivaratri, Purnima and Amavasya in a calendar year. These are vrats: fasting or observance days that repeat every lunar month. Leap months are included. Festivals skip them but vrats do not, and Padmini and Parama Ekadashi only occur in a leap month.
Each vrat is defined like a festival. It has a tithi (lunar day), the part of the day it must cover, and a rule for breaking ties. The same code as /v1/festivals decides them. Two related dates can be a day apart, and both are given. purnima is the full moon day (the tithi at sunrise). purnima-vrat is the fast (the first day the full moon tithi covers midday). amavasya is the new moon day. darsha-amavasya is the day of its rites (the day with the larger share of the afternoon).
We checked it against a widely used published calendar, for New Delhi 2026 to 2028 and Beijing 2026. 495 of 496 published dates match. The one miss is a Purnima. By this API's calculation it ends 57 seconds after sunrise, and by that calendar at sunrise. Every entry says which rule decided it. The place matters: Delhi and Beijing keep a dozen 2026 vrats a day apart.
Without latitude, longitude and timezone, the calendar is for Ujjain, India. If the time zone uses daylight saving time, each clock time uses the offset in force on its own date; place.note says so.
The first request for a year and place takes about 5 seconds. Later requests are cached.
Cost: Each successful request counts as 1 call toward your monthly calls.
Every fasting-day kind on the Sections and IDs page
Required inputs
| Name | In | What it is |
|---|---|---|
| year | query | Calendar year, from 1850 to 2149. |
Optional inputs (6), with their defaults
| Name | In | What it does |
|---|---|---|
| latitude | query | Latitude in degrees, negative for south. Defaults to Ujjain, India. |
| longitude | query | Longitude in degrees, negative for west. Defaults to Ujjain, India. |
| timezone | query | IANA time zone name such as America/New_York, or a fixed offset from UTC in hours such as -5. Defaults to 5.5 (India time). |
| kind | query | Which vrats to return, as a comma-separated list such as ekadashi,pradosh. Default: all of them. |
| lang | query | Language for the names in the response, such as planets, signs, nakshatras (lunar mansions), tithis (lunar days), months and festivals. The default is en (English); GET /v1/meta lists the others. Each translated value comes with its English original in a matching <field>_en field; use the English value as a key in your code. Codes (such as result or kaal) and object keys always stay in English. Any name not yet translated stays in English and is listed in localization.untranslated. |
| calendar | query | How to name the lunar months: amanta or purnimanta. In amanta calendars (Maharashtra, Gujarat and South India) a month ends at the new moon. In purnimanta calendars (North India) it ends at the full moon. Only the name of the month in its waning half differs. Dates never change. Both names are always in the response (amanta and purnimanta), and this setting chooses which one goes in name. Other languages keep this endpoint's usual one. convention says which was used. |
Main response fields
year(number)place(object): holds latitude, longitude, timezone, timezone_info, note.convention(string)vrats(array of objects): each item holds date, kaal, decided_by, coverage, kaal_at, slug, name, masa, tithi.counts(object): holds ekadashi, pradosh, sankashti-chaturthi, masik-shivaratri, purnima, purnima-vrat, amavasya, darsha-amavasya.
# New York
curl "https://apiforastrology.com/api/astrology/v1/vrats?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",
"vrats": [
{
"date": "2026-01-02",
"kaal": "sunrise",
"decided_by": "the tithi holds sunrise on no day; kept on the civil day it mostly falls in",
"coverage": 0,
"kaal_at": "2026-01-02T07:20:10-05:00",
"slug": "purnima",
"name": "Pausha Purnima",
"masa": {
"name": "Pausha",
"purnimanta": "Pausha",
"amanta": "Pausha",
"adhika": false,
"paksha": "shukla",
"tithi": 15
},
"tithi": {
"starts": "2026-01-02T08:23:58-05:00",
"ends": "2026-01-03T05:02:54-05:00"
}
},
{
"date": "2026-01-02",
"kaal": "madhyahna",
"decided_by": "the only day the tithi holds madhyahna",
"coverage": 1,
"kaal_window": {
"starts": "2026-01-02T11:04:13-05:00",
"ends": "2026-01-02T12:56:14-05:00"
},
"slug": "purnima-vrat",
"name": "Pausha Purnima vrat",
"masa": {
"name": "Pausha",
"purnimanta": "Pausha",
"amanta": "Pausha",
"adhika": false,
"paksha": "shukla",
"tithi": 15
},
"tithi": {
"starts": "2026-01-02T08:23:58-05:00",
"ends": "2026-01-03T05:02:54-05:00"
}
},
{
"date": "2026-01-06",
"kaal": "moonrise",
"decided_by": "the tithi holds moonrise on no day; kept on the civil day it mostly falls in",
"coverage": 0,
"kaal_at": "2026-01-06T20:43:56-05:00",
"slug": "sankashti-chaturthi",
"name": "Lambodara Sankashti",
"masa": {
"name": "Magha",
"purnimanta": "Magha",
"amanta": "Pausha",
"adhika": false,
"paksha": "krishna",
"tithi": 4
},
"tithi": {
"starts": "2026-01-05T21:32:09-05:00",
"ends": "2026-01-06T20:23:03-05:00"
}
}
],
"counts": {
"ekadashi": 24,
"pradosh": 24,
"sankashti-chaturthi": 13,
"masik-shivaratri": 12,
"purnima": 13,
"purnima-vrat": 13,
"amavasya": 12,
"darsha-amavasya": 12
}
}Example from a real call for New York. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Hindu calendar and festivals.
One festival's date for a year and place
GET /v1/festivals/{slug}
Each Hindu festival falls on a tithi (lunar day) in a named lunar month. It is kept on the calendar day when that tithi is running during the part of the day the festival needs. That is pradosh (early evening) for Diwali, midday for Ganesh Chaturthi, and midnight for Janmashtami. Each month is named both ways: masa.purnimanta (North India, where a month ends at the full moon) and masa.amanta (Maharashtra, Gujarat and South India, where it ends at the new moon). The two differ only in a month's waning half, and never change a date. calendar chooses which one goes in masa.name; without it, purnimanta (amanta for Marathi and Gujarati). Leap months (adhika masa) are detected, and no festival is kept in one.
Regional festivals from the Marathi and Gujarati calendars (Gudi Padwa, Vat Purnima, Pola, Bestu Varas, Shitala Satam and others) carry region: the calendar each was checked against (Maharashtra, Gujarat or both). Festivals without it are on the all-India list. The Gauri and Saraswati days are set by the Moon's nakshatra, not a tithi, and also carry nakshatra. Every regional date matches a widely used published calendar for Mumbai and Ahmedabad, 2026 to 2028.
Every date has decided_by, the rule that chose it. Where traditions really do differ (Janmashtami, Ekadashi), the response says sources_agree: false and gives other_tradition_date.
The place changes the day. Sunrise and the parts of the day move with longitude. So Delhi and Beijing keep four 2026 festivals a day apart, as published calendars for those cities do.
If the time zone uses daylight saving time, each clock time uses the offset in force on its own date. It ends with that offset; place.note says so. Without latitude, longitude and timezone, the calendar is for Ujjain, India.
Cost: Each successful request counts as 1 call toward your monthly calls.
Every festival id on the Sections and IDs page
Required inputs
| Name | In | What it is |
|---|---|---|
| slug | path | The festival ID, such as diwali, ganesh-chaturthi or raksha-bandhan. GET /v1/festivals lists every ID. An unknown ID returns 404 with the list of valid ones. |
| year | query | Calendar year, from 1850 to 2149. |
Optional inputs (5), with their defaults
| Name | In | What it does |
|---|---|---|
| latitude | query | Latitude in degrees, negative for south. Defaults to Ujjain, India. |
| longitude | query | Longitude in degrees, negative for west. Defaults to Ujjain, India. |
| timezone | query | IANA time zone name such as America/New_York, or a fixed offset from UTC in hours such as -5. Defaults to 5.5 (India time). |
| lang | query | Language for the names in the response, such as planets, signs, nakshatras (lunar mansions), tithis (lunar days), months and festivals. The default is en (English); GET /v1/meta lists the others. Each translated value comes with its English original in a matching <field>_en field; use the English value as a key in your code. Codes (such as result or kaal) and object keys always stay in English. Any name not yet translated stays in English and is listed in localization.untranslated. |
| calendar | query | How to name the lunar months: amanta or purnimanta. In amanta calendars (Maharashtra, Gujarat and South India) a month ends at the new moon. In purnimanta calendars (North India) it ends at the full moon. Only the name of the month in its waning half differs. Dates never change. Both names are always in the response (amanta and purnimanta), and this setting chooses which one goes in name. Other languages keep this endpoint's usual one. convention says which was used. |
Main response fields
year(number)place(object): holds latitude, longitude, timezone, timezone_info, note.convention(string)festival(object): holds date, kaal, decided_by, coverage, kaal_window, slug, name, masa, tithi.
# 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"
}
}
}Example from a real call for New York. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Hindu calendar and festivals.
Eclipses (grahan) with local times and sutak
GET /v1/eclipses
Lists the solar and lunar eclipses between two dates. They are worked out from the planet positions themselves; no eclipse table is used. For one place, it says whether each one can be seen, when, and when its sutak (the time before an eclipse when rituals pause) begins and ends.
What each eclipse carries. type (total, partial, annular or penumbral); greatest and contacts in UTC and local time (lunar: P1, U1, U2, U3, U4, P4; solar: the worldwide begin and end); the umbral magnitude or gamma; falls_in, the sign and nakshatra the eclipse falls in; and here, the view from your place, with the local contacts C1 to C4, and the magnitude and obscuration of a solar eclipse.
Only an eclipse that can be seen from the place has a sutak, as the classical rule says. Sutak starts 9 hours before a lunar eclipse enters the dark shadow, or 12 hours before a solar eclipse begins, and lasts until the eclipse ends. Two things vary by tradition: the shorter sutak for children, the elderly and the ill, and the count in prahars. Both are named in not_computed. A penumbral lunar eclipse is not observed.
moon_sign adds for_you: the house from your Moon sign that the eclipse falls in. It is read as favorable in the 3rd, 6th, 10th and 11th, the classical rule, which awaits review by the astrologer.
Contact times agree with an independent calculation within about 6 seconds.
Cost: Each successful request counts as 1 call toward your monthly calls.
Required inputs
None.
Optional inputs (8), with their defaults
| Name | In | What it does |
|---|---|---|
| from | query | Start date, YYYY-MM-DD. Defaults to today. |
| to | query | End date, YYYY-MM-DD. Defaults to one year after from, and can be at most five years after it. |
| latitude | query | Latitude of the place. Default Ujjain, as for the daily panchang. |
| longitude | query | Longitude of the place. |
| timezone | query | IANA time zone name such as America/New_York, or a fixed offset from UTC in hours such as -5. Defaults to 5.5 (India time). |
| moon_sign | query | Your Moon sign, in English or Sanskrit, or 1-12. Adds for_you. |
| lang | query | Language of the reading text, such as en (English, the default) or hi (Hindi). GET /v1/meta lists the languages available. If a passage is not written in that language yet, the English passage is returned instead and marked with fell_back_to_en. Names in the response, such as planets and signs, are translated too. |
| detail | query | Length of the reading text: standard (the default) or expanded, which is about 1.8 times longer. If a passage has no expanded version yet, the standard one is returned. Each text block reports the length it got in its detail field. |
Main response fields
from(string)to(string)place(object): holds latitude, longitude, timezone.eclipses(array of objects): each item holds kind, type, greatest, contacts, falls_in, by_moon_sign, here, sutak, gamma, central, reading.basis(string)not_computed(array of strings)provenance(object): holds by_moon_sign.framing(object): holds key, text, language, detail.gaps(array)
# New York
curl "https://apiforastrology.com/api/astrology/v1/eclipses?from=2026-08-01&to=2026-09-30&latitude=40.7128&longitude=-74.006&timezone=America/New_York" \
-H "Authorization: Bearer $ASTROLOGY_API_KEY"{
"from": "2026-08-01",
"to": "2026-09-30",
"place": {
"latitude": 40.7128,
"longitude": -74.006,
"timezone": {
"source": "zone",
"offset_hours": -4,
"zone": "America/New_York",
"abbreviation": "EDT",
"dst": true,
"dst_hours": 1,
"ambiguous_resolved_by_fold": null,
"note": "read from the IANA tz database at this instant, so daylight saving and historical offset changes are included"
}
},
"eclipses": [
{
"kind": "solar",
"type": "total",
"greatest": {
"utc": "2026-08-12T17:45:57Z",
"local": "2026-08-12T13:45:56-04:00"
},
"contacts": {
"begin": {
"utc": "2026-08-12T15:33:57Z",
"local": "2026-08-12T11:33:57-04:00"
},
"end": {
"utc": "2026-08-12T19:58:00Z",
"local": "2026-08-12T15:58:00-04:00"
}
},
"falls_in": {
"longitude": 115.8934,
"sign": "Cancer",
"nakshatra": "Ashlesha",
"nakshatra_lord": "Mercury",
"pada": 3
},
"by_moon_sign": [
{
"moon_sign": "Aries",
"house": 4,
"result": "unfavorable"
},
{
"moon_sign": "Taurus",
"house": 3,
"result": "favorable"
},
{
"moon_sign": "Gemini",
"house": 2,
"result": "unfavorable"
}
],
"here": {
"eclipsed_here": true,
"visible": true,
"type_here": "partial",
"greatest": {
"utc": "2026-08-12T17:54:15Z",
"local": "2026-08-12T13:54:14-04:00"
},
"magnitude": 0.186,
"obscuration": 0.0947,
"contacts": {
"C1": {
"utc": "2026-08-12T17:07:49Z",
"local": "2026-08-12T13:07:48-04:00"
},
"C4": {
"utc": "2026-08-12T18:38:54Z",
"local": "2026-08-12T14:38:53-04:00"
}
},
"sun_altitude_at_greatest": 61.6,
"visible_from": {
"utc": "2026-08-12T17:07:57Z",
"local": "2026-08-12T13:07:56-04:00"
},
"visible_until": {
"utc": "2026-08-12T18:37:57Z",
"local": "2026-08-12T14:37:56-04:00"
}
},
"sutak": {
"observed": true,
"hours_before": 12,
"begins": {
"utc": "2026-08-12T05:07:49Z",
"local": "2026-08-12T01:07:48-04:00"
},
"eclipse_begins": {
"utc": "2026-08-12T17:07:49Z",
"local": "2026-08-12T13:07:48-04:00"
},
"ends": {
"utc": "2026-08-12T18:38:54Z",
"local": "2026-08-12T14:38:53-04:00"
},
"not_computed": [
"the shorter sutak kept for children, the elderly and the ill -- its length varies by tradition",
"sutak counted in prahars of the actual day and night (3 for a lunar eclipse, 4 for a solar one) instead of fixed hours"
]
},
"gamma": 0.8977,
"central": true,
"reading": [
{
"key": "kind:solar:total",
"text": [
"A total solar eclipse: along a narrow track, the Moon covers the whole Sun and the sky goes dark for a few minutes. Elsewhere it is seen as partial."
],
"language": "en",
"detail": "standard"
},
{
"key": "visibility:visible",
"text": [
"It can be seen from your place, so the traditional observances apply here."
],
"language": "en",
"detail": "standard"
},
{
"key": "sutak:observed",
"text": [
"Sutak, the time of care before an eclipse, begins 12 hours before the eclipse and lasts until it ends. In this time people usually avoid cooking and eating, starting anything new and worship with images. Instead, they keep to prayer or…"
],
"language": "en",
"detail": "standard"
}
]
},
{
"kind": "lunar",
"type": "partial",
"greatest": {
"utc": "2026-08-28T04:12:55Z",
"local": "2026-08-28T00:12:55-04:00"
},
"contacts": {
"P1": {
"utc": "2026-08-28T01:24:00Z",
"local": "2026-08-27T21:23:59-04:00"
},
"P4": {
"utc": "2026-08-28T07:01:47Z",
"local": "2026-08-28T03:01:47-04:00"
},
"U1": {
"utc": "2026-08-28T02:33:54Z",
"local": "2026-08-27T22:33:54-04:00"
},
"U4": {
"utc": "2026-08-28T05:52:01Z",
"local": "2026-08-28T01:52:00-04:00"
}
},
"falls_in": {
"longitude": 310.6201,
"sign": "Aquarius",
"nakshatra": "Shatabhisha",
"nakshatra_lord": "Rahu",
"pada": 2
},
"by_moon_sign": [
{
"moon_sign": "Aries",
"house": 11,
"result": "favorable"
},
{
"moon_sign": "Taurus",
"house": 10,
"result": "favorable"
},
{
"moon_sign": "Gemini",
"house": 9,
"result": "unfavorable"
}
],
"here": {
"eclipsed_here": true,
"visible": true,
"moon_altitude_at_contacts": {
"P1": 19.5,
"P4": 32.6,
"U1": 29.4,
"U4": 38.2
},
"visible_from": {
"utc": "2026-08-28T02:33:54Z",
"local": "2026-08-27T22:33:54-04:00"
},
"visible_until": {
"utc": "2026-08-28T05:51:54Z",
"local": "2026-08-28T01:51:54-04:00"
}
},
"sutak": {
"observed": true,
"hours_before": 9,
"begins": {
"utc": "2026-08-27T17:33:54Z",
"local": "2026-08-27T13:33:54-04:00"
},
"eclipse_begins": {
"utc": "2026-08-28T02:33:54Z",
"local": "2026-08-27T22:33:54-04:00"
},
"ends": {
"utc": "2026-08-28T05:52:01Z",
"local": "2026-08-28T01:52:00-04:00"
},
"not_computed": [
"the shorter sutak kept for children, the elderly and the ill -- its length varies by tradition",
"sutak counted in prahars of the actual day and night (3 for a lunar eclipse, 4 for a solar one) instead of fixed hours"
]
},
"umbral_magnitude": 0.9301,
"penumbral_magnitude": 1.965,
"reading": [
{
"key": "kind:lunar:partial",
"text": [
"A partial lunar eclipse: only part of the Moon enters the Earth's dark shadow, so a bite seems to be taken out of it."
],
"language": "en",
"detail": "standard"
},
{
"key": "visibility:visible",
"text": [
"It can be seen from your place, so the traditional observances apply here."
],
"language": "en",
"detail": "standard"
},
{
"key": "sutak:observed",
"text": [
"Sutak, the time of care before an eclipse, begins 9 hours before the eclipse and lasts until it ends. In this time people usually avoid cooking and eating, starting anything new and worship with images. Instead, they keep to prayer or…"
],
"language": "en",
"detail": "standard"
}
]
}
],
"basis": "computed from JPL DE440s; lunar shadow by Danjon; the sign and nakshatra are sidereal, lahiri",
"not_computed": [
"a hybrid solar eclipse is reported by its type at greatest eclipse; none falls between 2024 and 2030",
"the track of totality or annularity on the map",
"the shorter sutak for children, the elderly and the ill, and sutak counted in prahars"
],
"provenance": {
"by_moon_sign": "classical rule (3rd, 6th, 10th and 11th favorable), awaiting the astrologer"
},
"framing": {
"key": "framing",
"text": [
"In Vedic tradition an eclipse (grahan) is a time to pause rather than begin. People avoid starting new work, keep the time for prayer, chanting or quiet, and bathe and give when it ends. The dates and times below are worked out for your…"
],
"language": "en",
"detail": "standard"
},
"gaps": []
}Example from a real call for New York. Long lists and texts are shortened.
Parameters, schemas and a test request in the interactive reference. Feature: Hindu calendar and festivals.
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 arc seconds. An arc second is 1/3,600 of a degree. A practicing astrologer reviews the rules behind these answers. See how we test accuracy.
Related pages
- Features: Hindu calendar and festivals, Panchang and muhurat.
- Used for: Publishers and media, Puja and spiritual stores, Astrology apps, Baby name apps.
- Rules: Muhurat for an activity, Muhurat and times of the day.
- Guides: Quickstart, Conventions, Errors, Changelog, Sections and IDs.
Terms in this group
From the blog
· 10 min read
How Muhurat Is Calculated: How Apps Pick a Good Time
How an app finds a muhurat.
Read
· 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