The World's Most Comprehensive
Hindu Panchang API

Supports the 1700–3100 date range. Works anywhere in the world: the timezone is resolved from lat/lon and daylight saving is applied, so coordinates alone are enough. Pass tz to name the zone yourself. A named location_id reads that location’s precomputed row and wins over coordinates; coordinates alone are computed for those coordinates. Every response reports the zone it used and the engine version.

Returns Panchang for today (server time, IST). Accepts all optional params except date.

Returns Panchang for tomorrow. Useful for apps that show a next-day preview widget.

Returns every available section in one response: core panchang, timings, hora, choghadiya, astronomical, shastric conditions, event suitability, festivals, panchak, bhadra, disha shool, special yogas.

Returns Tithi number, name, paksha (Shukla/Krishna), nature (Nanda/Bhadra/Jaya/Rikta/Purna), start/end times.

Returns Nakshatra number, name, pada (quarter), deity, gana (Deva/Manushya/Rakshasa), nature, ruling planet, period times.

Lightweight Panchang for mobile apps. Returns only essential data: date, tithi, nakshatra, sunrise, sunset, paksha. Response size < 1KB. For full data use /v1/panchang.

Get Panchang for current moment with live running tithi/nakshatra info. Shows what's active RIGHT NOW.

Panchang for each date from start to end inclusive (end - start <= 30 days, i.e. at most 31 dates). Requires the Starter plan; single dates are available on Free from /v1/panchang. Location: location_id > lat/lon > region's canonical location > Ujjain (the historical default).

Get Panchang for yesterday.

Killer endpoint: Returns today's complete Panchang data in a single call. Includes: panchang, festivals, muhurat, rahukaal, moon phase — everything. Optimized for mobile apps and dashboard widgets.

Returns: 🌅 Sunrise/Sunset · 🌙 Moonrise/Moonset · 🔴 Rahu Kaal · ⚫ Yamagandam · 🟠 Gulika Kaal · ⭐ Brahma Muhurta · ✨ Abhijit Muhurat · 💫 Amrit Kaal · ❌ Durmuhurta (×2) · 🚫 Varjyam.

Get inauspicious timings (Rahu Kaal, Yamagandam, Gulika Kaal, Durmuhurta, Varjyam).

24 Hora periods from sunrise to next sunrise. Each ruled by a planet (Sun→Venus→Mercury→Moon→Saturn→Jupiter→Mars). Duration = (next_sunrise − today_sunrise) / 24. Nepal uses +05:45 correctly.

North/West Indian tradition. 8 day slots from sunrise→sunset and 8 night slots from sunset→sunrise. Each ~1.5 hours (dynamically computed), rated: Amrit ✅ · Shubh ✅ · Labh ✅ · Char ⚠️ · Rog ❌ · Kaal ❌ · Udveg ❌.

Inauspicious 1.5-hour window. Varies by weekday — computed from actual sunrise, not fixed times.

Another inauspicious daily period. Avoid new ventures during Yamagandam.

Third inauspicious daily window in the Vedic timekeeping system.

Abhijit Muhurat — near solar noon, ~48 minutes. Most universally auspicious window. Not applicable on Wednesdays by traditional rule.

Sun longitude/rashi, Moon longitude/rashi/nakshatra, sankranti day flag, amavasya/purnima flags, planetary positions.

Returns phase name (Waxing Crescent/Gibbous/Full/Waning etc.), illumination percentage, paksha (Shukla/Krishna), days to next full/new moon.

Lagna (ascendant) changes every ~2 hours. Returns current lagna rashi + udaya lagna (fixed at sunrise). For real-time widgets, refresh every 5 minutes.

Get sun position and timing data.

Returns complete daily spiritual intelligence in a single response: panchang (5 limbs + hindu calendar), festivals (stored + rule-derived), conditions (panchak, bhadra, ganda_mool), and astronomical.eclipse. Internally calls the same engine functions as the individual endpoints — no logic duplication, no extra HTTP overhead. Any sub-block that cannot be computed returns null instead of failing.

curl "https://api.tathaastuapi.com/v1/day-context?date=2026-04-11&lat=28.6139&lon=77.2090" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx"

{
  "date": "2026-04-11",
  "location": { "lat": 28.6139, "lon": 77.2090, "region": "NORTH_INDIA", "location_id": 2 },
  "panchang": { /* tithi, nakshatra, yoga, karana, hindu_calendar, ... */ },
  "festivals": [ /* stored + rule-derived festivals */ ],
  "conditions": {
    "panchak":    { "is_panchak": false, "type": null, /* ... */ },
    "bhadra":     { "is_bhadra": false, /* ... */ },
    "ganda_mool": { "is_ganda_mool": false, "nakshatra_num": 12, "nakshatra_name": "Uttara Phalguni", "gana": "Manushya" }
  },
  "astronomical": {
    "eclipse": null
  },
  "_note": "Panchak, Bhadra, and Ganda Mool are NOT festivals. They are shastric conditions surfaced separately from /v1/festivals."
}

Returns a personalised Isht Devta recommendation based on the caller's birth data, computed via the production Vedic astrology engine. Deterministic and explainable — no hardcoded charts.

Request body:

{
  "date_of_birth": "1992-07-18",
  "time_of_birth": "10:30",
  "location": { "lat": 28.6139, "lon": 77.2090 },
  "timezone": "Asia/Kolkata"
}

Response:

{
  "isht_devta": {
    "name": "Mahalakshmi",
    "basis": "lagna_lord=Venus; moon_sign_lord=Venus; nakshatra_lord=Sun; → dominant planet: Venus",
    "confidence": "medium"
  },
  "methodology": "lagna + moon + nakshatra convergence",
  "supporting_factors": {
    "nakshatra":       "Punarvasu",
    "nakshatra_deity": "Aditi",
    "rashi":           "Taurus",
    "lagna":           "Libra",
    "lagna_lord":      "Venus",
    "moon_sign_lord":  "Venus",
    "nakshatra_lord":  "Sun",
    "dominant_planet": "Venus"
  },
  "engine": {
    "name": "TathaAstu Vedic Astrology Engine",
    "ayanamsa": "Lahiri",
    "rule": "convergence(lagna_lord, moon_sign_lord, nakshatra_lord)"
  },
  "disclaimer": "Isht Devta is a personal devotional choice. This recommendation is a deterministic computation based on classical lordships and is intended as guidance, not prescription. Consult your family guru or priest for personal sadhana decisions."
}

curl -X POST https://api.tathaastuapi.com/v1/isht-devta \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"date_of_birth":"1992-07-18","time_of_birth":"10:30","location":{"lat":28.6139,"lon":77.2090}}'

Bulk endpoint for calendar grids / monthly views / annual sync jobs.

Accepts a date range (up to 62 days per call) and returns an array of day_context payloads — avoids the 60 req/min rate limit when syncing full months or years.

Usage patterns:

• Mobile monthly calendar: 1 call per month × 7 regions = 7 calls/year
• Annual sync (single region): 12 calls (one per month)
• Annual sync (all regions): 84 calls (vs ~2,555 with daily endpoint)

Region parameter: If region=NORTH_INDIA is passed, canonical coords are auto-resolved. If region is omitted, lat + lon are required.

Response shape: ``json { "from": "2026-04-01", "to": "2026-04-30", "region": "NORTH_INDIA", "count": 30, "days": [ {"date": "2026-04-01", ...full day_context...}, ... ] } ``

Explainability endpoint — returns the exact astronomical rule that triggered a derived festival, with per-condition match details.

{
  "festival": "FESTIVAL_MAHA_SHIVARATRI",
  "date": "2026-02-16",
  "matched": true,
  "rule_code": "SHIVARATRI",
  "conditions": [
    { "field": "paksha", "expected": "KRISHNA", "actual": "KRISHNA", "matched": true },
    { "field": "tithi_num", "expected": 14, "actual": 14, "matched": true },
    { "field": "purnimanta_month", "expected": "Phalguna", "actual": "Phalguna", "matched": true }
  ],
  "human_readable": "This festival was derived because the conditions in rule 'SHIVARATRI' matched the Panchang facts for 2026-02-16."
}

Alias for /v1/festivals?date=X

Auspicious muhurat window for a festival at a specific date and location.

TathaAstuAPI owns all festival / muhurat / regional computation; the consuming app renders recommended + explanation directly and implements NO religious or regional logic. The response contains everything needed to display the answer:

• festival (id, key, name, date)
• location (region, lat, lon, timezone_offset)
• recommended {start, end, label} (null when unsupported / not applicable)
• avoid [{start, end, reason, label}] (Bhadra Mukha, Rahu Kaal, ...)
• conditions {tithi, sunrise, sunset, rahu_kaal, bhadra?, moonrise?}
• explanation {rule, kala, reason, source}
• verification : "verified" | "computed" | "unsupported"
• source

verification is honest: Tier-1 festivals are source-traced ("verified"), Tier-2 are computed from the authored kala ("computed"), and unsupported festivals return recommended: null rather than a fabricated time. Times are local ISO-8601 (the location's timezone, see location.timezone_offset).

Get all festivals in a date range using the rule engine.

Every day is evaluated exactly as /v1/festivals evaluates it, with the same region rule. A listed location without precomputed rows is computed from its coordinates; an unknown location_id is a 404; any other failure surfaces instead of silently dropping that day's festivals.

Search festivals by name or tag.

Get all festivals for a specific year.

The śrāddha kālas of one civil day at your coordinates: aparāhṇa (4th of 5 parts of daylight), Kutapa (8th of 15 day-muhūrtas), Gāndharva and Rauhiṇa (7th and 9th), and the kālas in which pārvaṇa is forbidden — prātaḥ, saṅgava and sāyāhna (Dharmasindhu ch. 26).

tithis_in_aparahna lists every tithi present in that day's aparāhṇa with the overlap in minutes, which is what an annual (pratyābdika) śrāddha is decided on. Two tithis appear when one ends inside the aparāhṇa.

The fifteen tithis of Mahālaya Pakṣa — amānta Bhādrapada Kṛṣṇa Pratipadā to Amāvāsyā — with the civil day each tithi's śrāddha falls on at your coordinates.

The day rule is the Dharmasindhu's: pārvaṇa śrāddha "has to be of Aparaahna Praapti" — the tithi must be present in the aparāhṇa, the fourth of five equal parts of daylight (ch. 26). Every rule in the response carries its verbatim quotation, chapter and URL under sources.

Where the text does not decide, neither does the API. When a tithi is present in the aparāhṇa on two days, or on neither, observance_date is null, decision_status is REQUIRES_SOURCE_CERTIFICATION, and both candidate days are returned with their overlap in minutes. The consulted text gives no pūrva/para ruling for pārvaṇa Mahālaya, and borrowing one would put authority on a rule the source did not state.

Also returned: Kutapa muhūrta per day, Śastrahata Caturdaśī, the Bharaṇī and Maghā-Trayodaśī occasions, the stated phala of each tithi, and the Kanyā-to-Vṛścika extension window. Avidhavā Navamī and Yati Dvādaśī are reported as convention, because the consulted translation does not state them.

Because sunrise and sunset set the aparāhṇa, the result depends on where you are.

Vrat and fasting observances for a date.

This used to read vrat_observance, joined to vrats and panchang_day_core. vrats holds 24 definitions; vrat_observance holds ZERO rows, in the active slot, the standby slot and the DB_NAME schema alike. It was never populated, so the join could not match and the endpoint returned {"vrats": [], "count": 0} for every date ever requested. July 2025 has two Ekadashis, two Pradosh, a Purnima, an Amavasya and a Sankashti; all thirty-one days came back empty, including 6 July, Devshayani Ekadashi, which /v1/festivals reported correctly as VRAT_EKADASHI on the same call.

It now resolves through canonical_festivals, like every other festival-producing endpoint. That was already the stated rule -- "one festival cannot come back on two different dates depending on which endpoint a client happened to call" -- and this endpoint was simply never brought across. Doing so also means it inherits the kala-aware rules, including the Caturthi-nirnaya fix, rather than a table nobody fills.

The {code, category, name} shape callers parsed is preserved; rule_code and confidence are added so a caller can see which rule decided the day.

Returns all classical conditions affecting the date:

Applies hierarchy: Eclipse → Ekadashi → Amavasya → Purnima → Bhadra → Panchak → Shool → Special Yogas. Returns AVOID / NEUTRAL / GOOD / EXCELLENT rating.

{
  "event": "marriage",
  "rating": "AVOID",
  "score": 18,
  "blocking_factors": ["Bhadra active until 15:30", "Panchak — Mritu Panchak"],
  "supporting_factors": ["Abhijit Muhurat available 11:52–12:40"],
  "hierarchy_applied": ["BHADRA", "PANCHAK"],
  "disclaimer": "Guidance is based on classical shastric rules..."
}

Given a date range and event type, returns only the GOOD and EXCELLENT rated dates sorted by score. Ideal for muhurat calendar builders.

Params: janma_nakshatra, transit_nakshatra (required); planet, transit_motion, moon_rashi, pala_variant. Zones are cross-verified across two independent sources; Kota Pāla is PROVISIONAL and the variant used is named in the response.

Params: nakshatra (required), sun_nakshatra. Returns the vedha partner and line orientation. Verification: DIAGRAM_VERIFIED_SECONDARY — the 14 pairs were read from a source diagram, not a manuscript.

Params: nakshatra (required), planet, motion, dignity, variant. Directions are OPPOSITE, FORWARD and BACKWARD, named by direction of travel rather than left/right, which no source fixes. Lattice and geometry are VERIFIED; consonant, vowel and tithi placement are DERIVED.

Params: reference_nakshatra (required), transit_nakshatra, variant, include_trident_parts. SUN_4POINT counts from the Sun and is the sourced reading; JANMA_3POINT is retained but unsupported. The variant used is always named in the response.

The 28 nakshatra names these endpoints accept, Abhijit included. Abhijit’s longitude arc is disputed between sources and is deliberately not resolved here.

Returns whether date falls in Panchak (5 inauspicious nakshatras: Dhanistha, Shatabhisha, Purva/Uttara Bhadrapada, Revati). Returns type (Mritu/Agni/Raja/Chora/Roga), severity, avoided activities, and specific remedies.

Bhadra is the most inauspicious Karana. Returns exact start/end time if active, and the activities to avoid (new business, haircut, auspicious ceremonies).

Checks whether the date falls in Ganda Mool nakshatras (Ashwini, Ashlesha, Magha, Jyeshtha, Mula, Revati) — considered inauspicious for birth and ceremonies.

Returns all 12 solar sankranti dates for a year with exact time, rashi transition, significance, and recommended observances.

Get detailed calendar view for a single day.

Get Panchang summary for an entire year.

Returns monthly summaries with key dates (Ekadashi, Purnima, Amavasya) and festival_count: the number of festivals /v1/festivals/month returns for that month and location (the same engine and regional rules).

Get Hindu month information (Amanta, Purnimanta, Saura Maasa).

Get Ritu (Hindu season) for a date.

Get Samvatsara (Hindu year name) and year details.

GET /v1/timings — all auspicious and inauspicious periods for a date. Equivalent to /v1/muhurat/day. Use this for a complete timing overview.

Whether a given eclipse is visible from a location, and when.

A thin layer over the engine's own local-circumstances calculation (get_eclipse_for_date, which drives Swiss Ephemeris sol_eclipse_when_loc / lun_eclipse_how and checks that the body is actually above the horizon). No astronomy is implemented here: the same code that produces eclipse data everywhere else in the API produces it here, so the two can never disagree.

magnitude and obscuration_percent are deliberately NOT returned. The engine does not compute them, and inventing a plausible number is worse than omitting a field.

local_times are clock times in the tz offset supplied (UTC by default).

Get all eclipses for a specific year.

Get detailed eclipse information.

Generates a full Vedic birth chart. Pass the native's birth date, time, and location. Returns planetary positions in signs and nakshatras, house placements, Vimshottari Dasha periods, and notable Yogas.

curl -X POST https://api.tathaastuapi.com/v1/birth-chart \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Arjun",
    "date": "1990-05-15",
    "time": "06:30",
    "lat": 28.6139,
    "lon": 77.2090
  }'

Retrieve a previously generated birth chart by its profile ID. Returns the same full chart data without re-computing.

Provide birth details for two individuals. Returns Ashtakoot Guna score (out of 36), individual Kuta scores, Manglik Dosha analysis, Nadi Dosha check, and an overall compatibility assessment.

curl -X POST https://api.tathaastuapi.com/v1/compatibility \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person1": {"name": "Arjun", "date": "1990-05-15", "time": "06:30", "lat": 28.6, "lon": 77.2},
    "person2": {"name": "Priya", "date": "1992-08-22", "time": "14:15", "lat": 28.6, "lon": 77.2}
  }'

Retrieve a previously computed compatibility analysis by its ID.

Full human-readable compatibility report in JSON. Supports lang=en/hi.

Lightweight compatibility score API.

Multi-religion world festival calendar. Query by date, year, month, religion, or search by name. Returns paginated results sorted by date.

# All Islamic festivals for 2025
curl "https://api.tathaastuapi.com/v1/festivals/world?year=2025&religion=islamic" \
  -H "X-API-Key: YOUR_KEY"

# Search for Eid festivals
curl "https://api.tathaastuapi.com/v1/festivals/world?search=eid&year=2025" \
  -H "X-API-Key: YOUR_KEY"

# Jewish festivals in March 2025
curl "https://api.tathaastuapi.com/v1/festivals/world?year=2025&month=3&religion=jewish" \
  -H "X-API-Key: YOUR_KEY"

{
  "total": 28,
  "limit": 100,
  "offset": 0,
  "festivals": [
    {
      "year": 2025,
      "religion": "islamic",
      "festival_id": "ramadan_start",
      "festival_name": "Ramadan Begins",
      "gregorian_date": "2025-03-01",
      "display_date": "2025-03-01",
      "day_of_week": "Saturday",
      "calendar_ref": "1 Ramadan 1446 AH",
      "notes": "Astronomical new moon calculation"
    }
  ],
  "filters": { "year": 2025, "religion": "islamic" }
}

Returns all available religions with total festival counts, unique festival types, and year coverage range. Use this to discover what data is available.

curl "https://api.tathaastuapi.com/v1/festivals/world/religions" \
  -H "X-API-Key: YOUR_KEY"

{
  "religions": [
    { "religion": "islamic", "total_festivals": 24843, "unique_festivals": 36, "min_year": 1700, "max_year": 2400 },
    { "religion": "christian", "total_festivals": 21861, "unique_festivals": 31, "min_year": 1700, "max_year": 2400 },
    { "religion": "jewish", "total_festivals": 19245, "unique_festivals": 28, "min_year": 1700, "max_year": 2400 },
    { "religion": "sikh", "total_festivals": 14700, "unique_festivals": 21, "min_year": 1700, "max_year": 2400 },
    { "religion": "orthodox", "total_festivals": 13700, "unique_festivals": 20, "min_year": 1700, "max_year": 2400 }
  ],
  "total_records": 94349,
  "year_range": { "min": 1700, "max": 2400 }
}

Returns upcoming world festivals from the current date, across all religions or filtered by a specific religion. Ideal for calendar widgets and notifications.

# Upcoming Sikh festivals
curl "https://api.tathaastuapi.com/v1/festivals/world/upcoming?religion=sikh&limit=10" \
  -H "X-API-Key: YOUR_KEY"

Returns festivals for a date range (start_date..end_date, up to 366 days) in one call, from the same festival engine and regional rules as /v1/festivals/range. Accepts location_id, region and lang.

Get list of all supported languages (50+).

No parameters.

Get transliteration strings for a category and language.

Get detailed Karana information for a date.

Get special yogas (Sarvartha Siddhi, Amrita Siddhi, Dwipushkar, Tripushkar).

Get detailed Yoga information for a date.

The Bhinnashtakavarga of the seven grahas and the Lagna, with the contributors of every point; the Samudaya with its favourable / middling / difficult bands; and Trikona and Ekadhipatya reduction with Rashi, Graha and Yoga Pinda. The point table is decoded from the karana verses of BPHS 66 and checked against their counts, the fixed totals and Santhanam's worked example. Ekadhipatya reduction is read differently by the editions; all three readings are returned and the primary one is named.

Evaluates the birth moment against BPHS ch. 85-96: Amāvasyā, the six parts of Kṛṣṇa Caturdaśī, Viṣṭi karaṇa, Vyatīpāta yoga, a kṣaya tithi, tithi / nakṣatra / lagna Gaṇḍānta, Abhukta Mūla, saṅkrānti and solar or lunar eclipse, with the junction times and the Sanskrit verse for each. Family nakṣatra and birth-order conditions are evaluated only when supplied. Names the text lists but does not define (Yamaghaṇṭa, Dagdha yoga, Pāta) are listed as not computed. Remedies are returned as text, not advice.

The avasthas of BPHS ch. 45 for every graha: Baladi, Jagradadi, Deeptadi, Lajjitadi and Shayanadi with Drishti / Cheshta / Vicheshta, together with the natural, temporary and compound relationships of ch. 3 they depend on. Every state carries its verse. Where the Pathak edition, the transcription and Santhanam's translation read a rule differently, each reading is returned; the effect verses are returned as text, not as a prediction.

Kuja (Mangal) dosha from BPHS 80.47-49 and Phaladeepika XI.3, and the serpent's and father's curse yogas of BPHS ch. 83 judged by the Sanskrit text, each with its verse. Where R. Santhanam's translation reads a verse differently, that reading is evaluated and returned beside the verdict. Conditions the text does not let a chart decide (strength without a stated threshold, Gulika) are returned as null, never guessed. Kaal Sarp and Sade Sati have no classical locus; they are returned under conventions.

Complete Vedic calculation from one canonical chart: lagna, grahas, whole-sign houses with Placidus cusps alongside, validated vargas (D1/D7/D9/D10/D30) and Vimshottari dasha to three levels. Every response echoes the exact calculation conventions used. /v1/birth-chart is unchanged and remains available.

Generate a comprehensive 60+ page Vedic Birth Chart (Kundli) PDF report.

Includes: Personality analysis, Rashi chart, 9 planets detailed analysis, 12 house analysis, Vimshottari Dasha with Antardasha, Classical Yogas, Life Journey narrative, Hidden Truths, Career/Marriage/Finance insights, Shadbala strength, Dosha analysis, 10-year predictions, Remedies.

Returns: PDF download URL + JSON summary

Free teaser preview of the Kundli report. Returns: Lagna, Moon sign, 2 key insights. Full report requires premium API key.

The five aprakāśa grahas (Dhūma, Vyatīpāta, Pariveṣa, Indracāpa, Upaketu) from BPHS ch. 3 and the five kālavelās (Kāla, Mṛtyu, Ardhaprahara, Yamaghaṇṭaka, Gulika) from BPHS ch. 4, each with its Sanskrit verse from the Pathak edition and R. Santhanam's translation. Kālavelās are counted from the vāra that began at the sunrise before the birth, and the longitude rising at the start and at the end of each part are both returned. Above the polar circles on days without sunrise or sunset the kālavelās are reported unavailable.

Get list of predefined locations with coordinates.

No parameters.

Get details for a specific location.

What changed in the API, when, and what it used to do.

Entries are append-only and newest first. A modified endpoint gets a new entry rather than an edit to the old one, so the previous contract stays readable — which is what you need if a change broke you.

breaking is true only where a request that worked before now fails or means something different. The same source feeds the NEW/MODIFIED badges in the API reference, so a badge and this list cannot disagree.

Detailed health check.

No parameters.

PRO. A personalized daily reading computed from the caller's natal chart and the transits of an explicit target date.

Historical and future dates are supported identically — the target date is required and nothing in the calculation reads the clock.

This is a traditional, rule-based reading, not a prediction. It applies classical Jyotish factors and explicitly declared engine conventions. It is not a scientifically validated prediction or guarantee of future events. reading_basis on each domain says how many factors contributed and is not a confidence, accuracy, likelihood or probability.

Every domain reading references factor_ids in the factors array, and every factor carries the rule and source it came from, so a reading can always be traced back to what produced it. The weights that turn factors into domain scores are engine decisions, published in the response and carrying no classical authority; the rules they weigh do carry sources.

Natal data comes from the stored birth profile. The observer block is where the user is now and fixes the daily Panchang, the sunrise that anchors Tara Bala, and the transit ascendant — it is not the birthplace.

Every plan the website shows, priced in one currency. Read from the same plans table the admin panel edits, so a price change needs no deploy. No API key required.

Get API status and statistics.

No parameters.

PRO. Find Tara Asta (heliacal setting) and Tara Udaya (heliacal rising) events for Budh (Mercury), Shukra (Venus), Mangal (Mars), Guru (Jupiter) or Shani (Saturn).

The calculation follows Sūrya Siddhānta IX.2–IX.9: the kālāṃśa — the interval between the Sun's and the planet's horizon crossings — is compared against the classical threshold. Mars 17, Saturn 15 and Jupiter 11 each have a single limit (IX.6). Mercury and Venus have two, and which applies is fixed by the conjunction the apparition belongs to, not by the planet's motion on the day: Venus 8 approaching or leaving inferior conjunction and 10 for superior (IX.7), Mercury 12 and 14 respectively (IX.8). The limit is set at the Asta and held until the Udaya, so a retrograde station occurring inside a disappearance cannot change it.

It is not an ecliptic longitude separation, and it is not the chart-combustion orb.

The Moon is deliberately not served here: Sūrya Siddhānta treats its heliacal rising and setting at the head of chapter X, under a different rule, so answering for it under this one would apply the wrong rule.

Because the criterion is a horizon relationship, the result depends on where you are. New Delhi and Lima differ by about a week for Shukra Asta 2026. Supplying a timezone does not substitute for supplying coordinates.

astronomical_date is the local civil date *containing* the calculated event instant. It is not an assertion of the date printed by any particular Panchang or almanac; see provenance.date_assignment in the response.

Range is limited to 366 days per request.

PRO. Is the planet currently Asta?

The verdict is read off this engine's own Asta/Udaya events: the instant is Asta when it falls at or after an Asta and before the Udaya that closes it, and visible otherwise. governing_event names the event the answer came from, so it can be checked against /v1/tara/events directly.

This endpoint does not evaluate visibility independently, and that is deliberate. Sūrya Siddhānta IX specifies event computation and provides no separate point-in-time visibility rule, so deriving the state from the event stream keeps one implementation of the criterion rather than two that can disagree. It is an engineering architecture chosen to stay faithful to the source's event-oriented model; the text is not claimed to prescribe it.

kalamsa is descriptive, not the verdict. Comparing it against threshold will disagree with is_asta near opposition, where the kālāṃśa folds through ±180° — a superior planet twelve hours from the Sun is as visible as it ever gets, and the folded value can read negative. That is the fold, not a contradiction.

Resolving the enclosing apparition costs a bounded scan, so this is not a single-sample lookup: expect roughly 100–500 ms depending on the planet's synodic period. If no governing event is found inside the search, the response is status: "indeterminate" rather than an assumption of visibility — absence of an Asta in the searched span is not evidence that none occurred.

Omitting at uses the current moment in the resolved zone, via the same now_in_zone helper the /now family already uses — this endpoint does not invent its own idea of "now".