The World's Most Comprehensive
Hindu Panchang API

Start Here

Build your first feature in 5 minutes. Follow this simple flow.

# Get a compatibility score in one call
curl "https://api.tathaastuapi.com/v1/compatibility/score?bride_dob=1992-07-18&bride_time=10:30&bride_lat=28.6139&bride_lon=77.2090&groom_dob=1989-11-25&groom_time=16:45&groom_lat=19.0760&groom_lon=72.8777" \
  -H "X-API-Key: YOUR_API_KEY"

Recommended Flows

Three common integration patterns. Pick the one that matches your app.

Popular Use Cases

Authentication

Every /v1/ request requires a valid API key in the header. Public endpoints (/v1/status, /v1/health) are exempt.

Header Authentication

# Using X-API-Key header (recommended)
curl "https://api.tathaastuapi.com/v1/panchang?date=2025-03-01&lat=28.6&lon=77.2" \
  -H "X-API-Key: tatha_live_xxxxxxxxxxxx"

# Error response when key is missing or invalid
{
  "error": "Unauthorized",
  "message": "Missing or invalid API key. Pass X-API-Key header.",
  "docs": "https://tathaastuapi.com/docs#authentication",
  "get_key": "https://tathaastuapi.com/#pricing"
}

Languages & localization

One rule for every /v1 endpoint: canonical fields never change; localized text is added as <field>_local. Match your code on the canonical field and display the _local one.

# GET /v1/festivals?date=2026-11-08&location_id=1&lang=hi
{ "festival_key": "FESTIVAL_DIWALI", "name": "Diwali", "name_local": "दिवाली" }

# GET /v1/choghadiya?date=2026-11-08&lat=19.076&lon=72.8777&lang=hi
{ "type": "Kaal", "type_local": "काल", "auspicious": false }

Never localized: ids and codes (festival_key, paksha), numbers, dates and times, coordinates, and text you send (such as name and place). Timestamps such as instant_local keep their older meaning: local wall-clock time. Endpoint reference: Languages (i18n).

Quick Start

First API call in under 2 minutes. Choose your language.

# Today's Panchang for Delhi
curl "https://api.tathaastuapi.com/v1/panchang?date=2025-03-01&lat=28.6139&lon=77.2090" \
  -H "X-API-Key: YOUR_API_KEY"

# With timings, hora, choghadiya in one call
curl "https://api.tathaastuapi.com/v1/panchang?date=2025-03-01&lat=28.6&lon=77.2&include=timings,hora,choghadiya" \
  -H "X-API-Key: YOUR_API_KEY"

# Full shastric conditions + event ratings
curl "https://api.tathaastuapi.com/v1/shastra/conditions?date=2025-03-01&lat=28.6&lon=77.2" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

API_KEY = "tatha_live_xxxxxxxxxxxx"
BASE    = "https://api.tathaastuapi.com/v1"
HDR     = {"X-API-Key": API_KEY}

# Core Panchang
r = requests.get(f"{BASE}/panchang", headers=HDR,
    params={"date":"2025-03-01","lat":28.6139,"lon":77.2090})
p = r.json()
print(p["tithi"]["name"])   # → "Ashtami"

# Event suitability for marriage
s = requests.get(f"{BASE}/events/suitability", headers=HDR,
    params={"date":"2025-03-01","lat":28.6,"lon":77.2,"event":"marriage"}).json()
print(s["rating"])   # → "AVOID" | "NEUTRAL" | "GOOD" | "EXCELLENT"

const API_KEY = 'tatha_live_xxxxxxxxxxxx';
const BASE    = 'https://api.tathaastuapi.com/v1';
const HDR     = { 'X-API-Key': API_KEY };

async function getPanchang(date, lat, lon) {
  const r = await fetch(
    `${BASE}/panchang?date=${date}&lat=${lat}&lon=${lon}`,
    { headers: HDR }
  );
  return r.json();
}

// Always call from server-side to protect your API key
const p = await getPanchang('2025-03-01', 27.7172, 85.3240);
console.log(p.tithi.name);    // → "Chaturdashi"
console.log(p.engine.version); // → "7.8.1"

<?php
define('API_KEY', 'tatha_live_xxxxxxxxxxxx');
define('BASE',    'https://api.tathaastuapi.com/v1');

function tathaApi($path) {
  $ctx = stream_context_create(['http' => [
    'header' => 'X-API-Key: ' . API_KEY
  ]]);
  return json_decode(
    file_get_contents(BASE . $path, false, $ctx), true
  );
}

$p = tathaApi('/panchang?date=2025-03-01&lat=28.6&lon=77.2');
echo $p['tithi']['name']; // → "Chaturdashi"

Example Response — /v1/panchang

{
  "date": "2025-02-21",
  "vara": { "name": "Friday", "name_sa": "Shukravāra", "lord": "Venus" },
  "tithi": {
    "number": 8, "name": "Ashtami", "paksha": "Krishna",
    "period": { "start": "2025-02-20 10:13", "end": "2025-02-21 12:13" }
  },
  "nakshatra": { "number": 17, "name": "Anuradha", "deity": "Mitra", "gana": "Deva" },
  "yoga": { "number": 13, "name": "Vyaghata" },
  "karana": { "number": 46, "name": "Garija", "auspicious": true },
  "hindu_calendar": { "amanta": "Magha", "purnimanta": "Phalguna", "samvat": 2081 },
  "timings": {
    "sunrise": "06:52:14", "sunset": "18:23:11",
    "moonrise": "02:14:00", "moonset": "13:44:00"
  },
  "engine": {
    "name": "TathaAstu Panchang", "version": "7.8.1",
    "calculation": "Drik", "ayanamsa": "Lahiri (Chitrapaksha)"
  }
}

Panchang Endpoints FREE TIER

The five limbs of Panchang — Vara, Tithi, Nakshatra, Yoga, Karana — plus Hindu calendar identity, special day flags, and engine attribution on every response.

All-Timings Endpoint FREE TIER

All auspicious and inauspicious windows for a date in one call — sunrise/sunset, all malefic periods, muhurtas, and moon times.

Hora & Choghadiya

Planetary hours and auspicious/inauspicious day segments. Durations dynamically computed from actual sunrise/sunset — never hardcoded to 60 minutes.

Astronomical Data

Sun/moon positions, zodiac, sankranti, moon phase and lagna — all computed via Swiss Ephemeris with Lahiri ayanamsa.

Unified Daily Context FLAGSHIP

A single B2B call returns the complete daily spiritual context — Panchang, festivals, shastric conditions, and eclipses. Built for clients who want one endpoint instead of stitching together /v1/panchang + /v1/festivals + /v1/panchak + /v1/eclipse.

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."
}

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

{
  "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}}'

Festivals & Vrats NEW: Explainable Engine

Festivals derived on-the-fly with full explainability — every result tells you exactly why it falls on a given date.

Stories, significance and observance (content=)

142 festivals carry content: 57 kathas (the story told for the festival), 93 significance notes and an observance (vidhi) note. Read one festival with GET /v1/festivals/content/{subject} (for example karva-chauth, rishi-panchami, indira-ekadashi; GET /v1/festivals/content lists them all), or add content=story — also katha, significance, vidhi, all, comma-separated — to /v1/festivals, /v1/festivals/date, /range, /month, /year, /search, /v1/calendar/day and /v1/calendar/month: every festival in the response then has a content block (null where none is held). Without content= the responses are unchanged.

Each piece has type, title, body_html (simple HTML: paragraphs, emphasis, lists), the language actually served and provenance. The texts are original adaptations by TathaAstu and are drafts until reviewed: review_status says so, source_reference names the scriptural or traditional source adapted where one could be named, and source_reference_verified stays false until a reviewer confirms it. Folk kathas (Karva Chauth, Ahoi Ashtami, Bhai Dooj) are labelled traditional and claim no scripture. With lang, a translated piece is served in that language with its translation provenance; one not yet translated is served in English with language_note. Hindi is available for every katha; other languages are being added.

Ekadashi: Smarta and Vaishnava days (sampradaya=)

Smarta householders and Vaishnavas (with ascetics) sometimes keep the same Ekadashi on different days. Where they do, the Ekadashi item (festival_key VRAT_EKADASHI) carries an observance block: schools.smarta and schools.vaishnava, each with date and label; pattern (DVADASHI_KSHAYA_TRISPARSHA, EKADASHI_KSHAYA, DVADASHI_VRIDDHI, ARUNODAYA_VEDHA, EKADASHI_VRIDDHI_DVADASHI_KSHAYA); default_date and default_follows; and sources. Ekadashis on which the schools agree carry no block.

Default unchanged. Without the parameter, date is the canonical day it has always been: the Ekadashi at sunrise. Add sampradaya=smarta or sampradaya=vaishnava to receive that school's day instead. The day is computed from the rules of Dharmasindhu (1888, pp.11-12) and Nirnayasindhu (1940, pp.30-31), not relabelled. The parameter is accepted by /v1/festivals, /v1/festivals/date, /range, /month, /year, /explain, /v1/vrat, /v1/calendar/month and /v1/calendar/year. Only the Ekadashi vrat moves; every other festival ignores it. Items it chose are marked sampradaya with confidence_label SAMPRADAYA_RULE. Any other value is a 422 (invalid_sampradaya).

Example, Pausha Putrada Ekadashi 2027 at New Delhi:
GET /v1/festivals?date=2027-01-19: Ekadashi on 2027-01-19, with observance.schools.smarta.date 2027-01-18.
GET /v1/festivals?date=2027-01-18&sampradaya=smarta: Ekadashi on 2027-01-18.
GET /v1/festivals/year?year=2027&sampradaya=vaishnava: every Ekadashi on its Vaishnava day.

Migrating. Nothing breaks: observance is an added field, and a client that ignores it sees the same dates as before. To follow a school, pass sampradaya on every festival or vrat call you make, including range and year calls. /v1/panchang special_day_flags.is_ekadashi still means "Ekadashi at sunrise"; it is a Panchang fact, not an observance day.

Bengal Durga Puja rites (West Bengal)

For the West Bengal tradition (region=IN-WB, or a West Bengal location such as Kolkata) the Durga Puja rites are festivals of their own, beside Maha Shashthi to Vijayadashami: FESTIVAL_BILVA_NIMANTRAN (the evening of Shashthi), FESTIVAL_KALPARAMBHA (Kalparambha, Akal Bodhon, Amantran and Adhivas; the day before the Navapatrika), FESTIVAL_NAVAPATRIKA_PUJA (Kola Bou; Saptami at sunrise), FESTIVAL_KUMARI_PUJA (Maha Ashtami), FESTIVAL_SANDHI_PUJA and FESTIVAL_DURGA_VISARJAN (Bijoya Dashami, Sindoor Khela). Other regions are unchanged.

Sandhi Puja carries its time. Its item has an observance block: window.start and window.end (local time, the last 24 minutes of Ashtami and the first 24 of Navami), junction (the moment Ashtami ends) and basis. Its date is the sunrise-to-sunrise day holding the junction, so a junction before dawn is listed under the previous date. Example: GET /v1/festivals?date=2026-10-19&region=IN-WB gives Sandhi Puja with the window 10:28 to 11:16. The rules cite Nirnayasindhu (1940) pp.125-137 and Dharmasindhu (1888) pp.70-71 (see /v1/festivals/explain) and reproduce Drik Panchang’s Kolkata dates for 2021-2030.

{
  "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."
}

Shastric Conditions BUSINESS — Unique in Market

Your competitive differentiator. Complete classical guidance layer based on Dharma Sindhu and Nirnaya Sindhu — not available in any other Panchang API.

Event Suitability

Is today good for a wedding? Can I start a business? Should I buy land? The engine applies the full Shastric hierarchy and returns a verdict with explicit reasons and blocking/supporting factors.

{
  "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..."
}

Chakra Calculation APIs FREE

Kota, Saptaśalāka, Sarvatobhadra and Śūla chakras as calculation-only endpoints. Every response carries the ruleset and a verification level for each individual rule.

Panchak, Bhadra & Sankranti

Granular endpoints for checking specific classical conditions.

Calendar APIs

Bulk queries for calendar UI components — month, year, and custom ranges.

Muhurat Finder

Find the most auspicious date-time windows for a specific event type within a date range, ranked by classical shastric score.

New: Muhurat Search (/v1/muhurat/search) returns clock windows with the book, verse and page behind every reason. Start with the guide below.

Muhurat Search guide: /v1/muhurat/search

What it is. Give it an event, a place and a date range (up to 92 days). It returns the dates and clock windows in which the classical rules for that event hold, and every reason carries its reference: the book, chapter and verse, the printed page, the edition, the Sanskrit line, and whether the page image or only the OCR text was read. A rule with no passage behind it is labelled convention and says so. Where the books disagree, the date is allowed, flagged, and the disagreement is shown. It never picks a side silently. Available on the Pro plan, as GET or POST, one API request per call.

How it differs from /v1/muhurat/find

Supported events

Parameters

Examples: marriage

curl -s "https://api.tathaastuapi.com/v1/muhurat/search?event=vivaha&start=2027-01-14&end=2027-01-31&location_id=1" \
  -H "X-API-Key: YOUR_API_KEY"

const r = await fetch(
  "https://api.tathaastuapi.com/v1/muhurat/search?event=vivaha&start=2027-01-14&end=2027-01-31&location_id=1",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await r.json();
for (const d of data.dates) {
  const w = d.windows[0];
  console.log(d.date, d.weekday, w.start, "to", w.end, d.quality);
}

A real response (Delhi, 11 dates found in 18 days), shortened:

{
  "event": "vivaha",
  "event_label": "Marriage (Vivāha)",
  "start": "2027-01-14",
  "end": "2027-01-31",
  "basis": "cited",
  "profile": "panchang",
  "dates_checked": 18,
  "dates_with_windows": 11,
  "location": {
    "lat": 28.6139,
    "lon": 77.209,
    "location_id": 1,
    "region": "NORTH_INDIA",
    "timezone_offset_hours_at_start": 5.5
  },
  "dates": [
    {
      "date": "2027-01-15",
      "weekday": "Friday",
      "sunrise": "2027-01-15T07:14:47+05:30",
      "sunset": "2027-01-15T17:46:15+05:30",
      "tithi_at_sunrise": {
        "number": 7,
        "paksha": "Shukla",
        "name": "Saptami"
      },
      "nakshatra_at_sunrise": "Revati",
      "lunar_month": "Pausha",
      "lunar_month_adhika": false,
      "quality": "recommended",
      "windows": [
        {
          "start": "2027-01-15T07:14:47+05:30",
          "end": "2027-01-15T14:14:09+05:30",
          "duration_minutes": 419,
          "states": [
            {
              "from": "2027-01-15T07:14:47+05:30",
              "to": "2027-01-15T14:14:09+05:30",
              "tithi": 7,
              "paksha": "Shukla",
              "tithi_name": "Saptami",
              "nakshatra": "Revati"
            }
          ],
          "reasons": [
            {
              "key": "muhurat.reason.vivaha.hari_shayana.pass",
              "rule": "vivaha.hari_shayana",
              "text": "It is outside the Hari-śayana (Chāturmāsya) period.",
              "basis": "cited",
              "status": "pass",
              "values": {},
              "source": {
                "work": "Muhūrta Cintāmaṇi",
                "author": "Rāma Daivajña",
                "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                "chapter": "Vivāha-prakaraṇa (6), Pīyūṣadhārā",
                "verse": "6.13",
                "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                "page": "316",
                "verification": "image-verified (leaf 369)"
              },
              "quote_original": "आषाढशुक्लदशम्यनन्तरं हरिशयने च सति विवाहो न स्यात्",
              "also_cited": [
                {
                  "work": "Muhūrta Cintāmaṇi",
                  "author": "Rāma Daivajña",
                  "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                  "chapter": "Vivāha-prakaraṇa (6), Pīyūṣadhārā",
                  "verse": "6.13",
                  "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                  "page": "316",
                  "verification": "image-verified (leaf 369)",
                  "quote_original": "तुलायां कार्तिको देवोत्थानादुत्तरः, वृश्चिके मार्गशीर्ष शुभ"
                }
              ],
              "coverage": "whole_window"
            },
            {
              "key": "muhurat.reason.vivaha.nakshatra.pass",
              "rule": "vivaha.nakshatra",
              "text": "The Moon is in one of the nakshatras approved by all authorities for marriage.",
              "basis": "cited",
              "status": "pass",
              "values": {
                "nakshatra": "Revati"
              },
              "source": {
                "work": "Dharmasindhu(sāra)",
                "author": "Kāśīnātha Upādhyāya",
                "commentary": "",
                "chapter": "Tṛtīya-pariccheda, vivāha-nirṇaya §75",
                "verse": "III §75",
                "edition": "Nirṇaya Sāgara Press, Bombay, 1888",
                "page": "181",
                "verification": "image-verified"
              },
              "quote_original": "रोहिणीमृगमघास्तिस्त्रउत्तराहस्तस्वातीमूलानुराधारेवत्यःसर्वसंमतनक्षत्राणि हरदत्तमतेचित्राश्रवणधनिष्ठाश्विन्य इत्यधिकानि चत्वारि",
              "also_cited": [
                {
                  "work": "Muhūrta Cintāmaṇi",
                  "author": "Rāma Daivajña",
                  "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                  "chapter": "Vivāha-prakaraṇa (6)",
                  "verse": "6.55",
                  "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                  "page": "375",
                  "verification": "image-verified (leaf 428)",
                  "quote_original": "निर्वेधैः शशिकरमूलमैत्र्य-ब्राह्मान्त्योत्तरपवनैः शुभो विवाहः । रिक्तामारहिततिथौ शुभेऽह्नि"
                }
              ],
              "note": "Magha is in Dharmasindhu's list and the Pīyūṣadhārā quotes it, but the printed Muhūrta Cintāmaṇi verse in this edition omits it; the 1907 edition appears to include it.",
              "coverage": "whole_window"
            }
          ],
          "general_checks": [
            {
              "key": "muhurat.reason.common.adhika.pass",
              "rule": "common.adhika",
              "text": "It is not an Adhika (extra) month.",
              "basis": "cited",
              "status": "pass",
              "values": {
                "month": "Pausha"
              },
              "source": {
                "work": "Muhūrta Cintāmaṇi",
                "author": "Rāma Daivajña",
                "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                "chapter": "Śubhāśubha-prakaraṇa (1)",
                "verse": "1.46-47",
                "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                "page": "52",
                "verification": "image-verified (leaf 105)"
              },
              "quote_original": "वाप्यारामतडागकूपभवनारम्भप्रतिष्ठे व्रतारम्भोत्सर्गवधूप्रवेशनमहादानानि … दीक्षामौञ्जिविवाहमुण्डनमपूर्वं देवतीर्थेक्षणं … गमम् । चातुर्मास्यसमावर्तौ श्रवणयोर्वेधं परीक्षां त्यजेद्वृद्धत्वास्तशिशुत्व इज्यसितयोर्न्यूनाधिमासे तथा",
              "coverage": "whole_window"
            }
          ],
          "cautions": [],
          "bad_periods_inside": [
            {
              "key": "rahu_kaal",
              "name": "Rahu Kāla",
              "start": "2027-01-15T11:11:35+05:30",
              "end": "2027-01-15T12:30:31+05:30",
              "basis": "convention",
              "note": "Popular panchang practice; Rāhu Kāla, Yamagaṇḍa and Gulika are not found in the Muhūrta Cintāmaṇi, Dharmasindhu or Nirṇayasindhu editions read."
            }
          ],
          "quality": "recommended"
        }
      ]
    },
    "..."
  ],
  "excluded_periods": "[]  (none in this range)",
  "unsupported": [],
  "rules_not_evaluated": [
    {
      "id": "vivaha.lagna_rules",
      "text_en": "Marriage-lagna rules: kartarī, aṣṭama-lagna, lagna-gaṇḍānta, andha/badhira/paṅgu lagnas, Moon and malefic placements (MC 6.43-6.48, 6.81-6.91)",
      "reason": "Windows are the hours in which the kāla rules (tithi, nakshatra, weekday, month, bala, yoga, karaṇa) hold. The choice of lagna inside a window is not made for you; the lagna sequence is not returned for marriage."
    },
    "..."
  ]
}

GET or POST

Both run the same search and return the same response. Use GET for a plain query. Use POST when you send birth details, so they travel in the JSON body and stay out of URLs, access logs and browser history. The POST body takes exactly the parameters above, with the same names. If lang is given in both the query string and the body, the query wins.

Each date is a Panchang day: sunrise to sunrise

A date is the Panchang day that begins at that date’s local sunrise and ends at the next sunrise. For marriage and travel the windows can therefore run past midnight: in the example below the window of 14 February ends at 06:59 on 15 February. Windows are ISO 8601 times with the place’s UTC offset, so never re-attach a date to them. The early hours of a civil date (before sunrise) belong to the previous Panchang day. House entry, vehicle, business, naming, tonsure and learning use the daylight part of the day.

Examples: marriage with partner birth details, in Hindi (POST)

curl -s -X POST "https://api.tathaastuapi.com/v1/muhurat/search" \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"event":"vivaha","start":"2027-02-01","end":"2027-02-14","location_id":1,"lang":"hi",
       "birth_date":"1996-05-14","birth_time":"06:30","birth_tz":"Asia/Kolkata",
       "partner_birth_nakshatra":"Hasta","partner_birth_rashi":"Kanya"}'

const r = await fetch("https://api.tathaastuapi.com/v1/muhurat/search", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    event: "vivaha", start: "2027-02-01", end: "2027-02-14", location_id: 1, lang: "hi",
    birth_date: "1996-05-14", birth_time: "06:30", birth_tz: "Asia/Kolkata",   // first person: the Moon is computed from this
    partner_birth_nakshatra: "Hasta", partner_birth_rashi: "Kanya"             // second person: given directly
  })
});
const data = await r.json();
console.log(data.personal.persons);          // the Moon used for each person
for (const d of data.dates) console.log(d.date, d.windows[0].start, d.windows[0].end);

Both people must pass Chandra-bala; a house that passes only by the extra Shukla-paksha rule is returned as a variant caution, not hidden. A real response (Delhi, 1-14 February 2027), shortened:

{
  "event": "vivaha",
  "language": "hi",
  "profile": "panchang",
  "personal": {
    "available": true,
    "persons": [
      {
        "nakshatra": "Revati",
        "rashi": "Meena",
        "source": "birth_date_time",
        "nakshatra_local": "रेवती",
        "rashi_local": "मीन"
      },
      {
        "nakshatra": "Hasta",
        "rashi": "Kanya",
        "source": "birth_nakshatra_rashi",
        "nakshatra_local": "हस्त",
        "rashi_local": "कन्या"
      }
    ],
    "notes": []
  },
  "dates_checked": 14,
  "dates_with_windows": 1,
  "dates": [
    {
      "date": "2027-02-14",
      "weekday": "Sunday",
      "sunrise": "2027-02-14T07:00:28+05:30",
      "sunset": "2027-02-14T18:10:32+05:30",
      "tithi_at_sunrise": {
        "number": 8,
        "paksha": "Shukla",
        "name": "Ashtami",
        "name_local": "अष्टमी",
        "paksha_local": "शुक्ल"
      },
      "nakshatra_at_sunrise": "Krittika",
      "nakshatra_at_sunrise_local": "कृत्तिका",
      "lunar_month": "Magha",
      "lunar_month_adhika": false,
      "lunar_month_local": "माघ",
      "quality": "acceptable",
      "windows": [
        {
          "start": "2027-02-15T04:47:02+05:30",
          "end": "2027-02-15T06:59:39+05:30",
          "duration_minutes": 133,
          "states": [
            {
              "from": "2027-02-15T04:47:02+05:30",
              "to": "2027-02-15T06:59:39+05:30",
              "tithi": 9,
              "paksha": "Shukla",
              "tithi_name": "Navami",
              "nakshatra": "Rohini",
              "tithi_name_local": "नवमी",
              "paksha_local": "शुक्ल",
              "nakshatra_local": "रोहिणी"
            }
          ],
          "reasons": [
            {
              "key": "muhurat.reason.vivaha.nakshatra.pass",
              "rule": "vivaha.nakshatra",
              "text": "The Moon is in one of the nakshatras approved by all authorities for marriage.",
              "basis": "cited",
              "status": "pass",
              "values": {
                "nakshatra": "Rohini",
                "nakshatra_local": "रोहिणी"
              },
              "text_local": "चन्द्रमा विवाह के लिए सर्वसम्मत नक्षत्र में है।",
              "source": {
                "work": "Dharmasindhu(sāra)",
                "author": "Kāśīnātha Upādhyāya",
                "commentary": "",
                "chapter": "Tṛtīya-pariccheda, vivāha-nirṇaya §75",
                "verse": "III §75",
                "edition": "Nirṇaya Sāgara Press, Bombay, 1888",
                "page": "181",
                "verification": "image-verified"
              },
              "quote_original": "रोहिणीमृगमघास्तिस्त्रउत्तराहस्तस्वातीमूलानुराधारेवत्यःसर्वसंमतनक्षत्राणि हरदत्तमतेचित्राश्रवणधनिष्ठाश्विन्य इत्यधिकानि चत्वारि",
              "note": "Magha is in Dharmasindhu's list and the Pīyūṣadhārā quotes it, but the printed Muhūrta Cintāmaṇi verse in this edition omits it; the 1907 edition appears to include it.",
              "note_local": "मघा धर्मसिन्धु की सूची में है और पीयूषधारा उसे उद्धृत करती है, पर इस संस्करण के छपे मुहूर्तचिन्तामणि श्लोक में वह नहीं है; १९०७ का संस्करण उसे सम्मिलित करता प्रतीत होता है।",
              "coverage": "whole_window"
            }
          ],
          "general_checks": [
            "..."
          ],
          "cautions": [
            {
              "key": "muhurat.reason.vivaha.tithi.variant",
              "rule": "vivaha.tithi",
              "text": "Kṛṣṇa 11th–13th: Dharmasindhu counts it middling; Muhūrta Cintāmaṇi stops at the 10th.",
              "basis": "cited",
              "status": "variant",
              "values": {
                "tithi": 9,
                "paksha": "Shukla",
                "paksha_local": "शुक्ल"
              },
              "text_local": "कृष्ण ११–१३: धर्मसिन्धु इसे मध्यम मानता है; मुहूर्तचिन्तामणि दशमी पर रुकता है।",
              "source": {
                "work": "Muhūrta Cintāmaṇi",
                "author": "Rāma Daivajña",
                "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                "chapter": "Vivāha-prakaraṇa (6)",
                "verse": "6.55",
                "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                "page": "375",
                "verification": "image-verified (leaf 428)"
              },
              "quote_original": "निर्वेधैः शशिकरमूलमैत्र्य-ब्राह्मान्त्योत्तरपवनैः शुभो विवाहः । रिक्तामारहिततिथौ शुभेऽह्नि",
              "also_cited": [
                {
                  "work": "Muhūrta Cintāmaṇi",
                  "author": "Rāma Daivajña",
                  "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                  "chapter": "Vivāha-prakaraṇa (6), Pīyūṣadhārā",
                  "verse": "6.55",
                  "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                  "page": "376",
                  "verification": "image-verified (leaf 429)",
                  "quote_original": "शुक्लद्वितीयादित एव कृष्णे पक्षे दशम्यन्तर्गताः प्रशस्ताः । तास्वष्टमीस्कन्दगणेशदुर्गाचतुर्दशी चापि तिथिर्विवर्ज्या"
                },
                {
                  "work": "Dharmasindhu(sāra)",
                  "author": "Kāśīnātha Upādhyāya",
                  "commentary": "",
                  "chapter": "Tṛtīya-pariccheda, vivāha-nirṇaya §75",
                  "verse": "III §75",
                  "edition": "Nirṇaya Sāgara Press, Bombay, 1888",
                  "page": "181",
                  "verification": "image-verified",
                  "quote_original": "अमावास्यानिषिद्धा रिक्ताष्टमीषष्ठ्योपफलाः अन्यास्तिथयोबहुफलाः शुक्लपक्षःश्रेष्ठः कृष्णश्चयोदशीपर्यन्तोमध्यमः"
                }
              ],
              "coverage": "whole_window"
            },
            {
              "key": "muhurat.reason.vivaha.chandra_bala.variant",
              "rule": "vivaha.chandra_bala",
              "text": "The Moon is in one of the extra Shukla-paksha houses from the birth rashi (counted good by the text).",
              "basis": "cited",
              "status": "variant",
              "values": {
                "person1": {
                  "house": 3,
                  "moon_sign": "Vrishabha",
                  "moon_sign_local": "वृषभ"
                },
                "person2": {
                  "house": 9,
                  "moon_sign": "Vrishabha",
                  "moon_sign_local": "वृषभ"
                }
              },
              "text_local": "चन्द्रमा जन्मराशि से शुक्लपक्ष के अतिरिक्त शुभ भाव में है (ग्रन्थ इसे शुभ मानता है)।",
              "source": {
                "work": "Muhūrta Cintāmaṇi",
                "author": "Rāma Daivajña",
                "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                "chapter": "Vivāha-prakaraṇa (6)",
                "verse": "6.12",
                "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                "page": "314",
                "verification": "image-verified (leaf 367)"
              },
              "quote_original": "गुरुशुद्धिवशेन कन्यकानां समवर्षेषु षडब्दकोपरिष्टात् । रविशुद्धिवशाच्छुभो वराणामुभयोश्चन्द्रविशुद्धितो विवाहः",
              "also_cited": [
                {
                  "work": "Dharmasindhu(sāra)",
                  "author": "Kāśīnātha Upādhyāya",
                  "commentary": "",
                  "chapter": "Tṛtīya-pariccheda, vivāha-nirṇaya §75",
                  "verse": "III §75",
                  "edition": "Nirṇaya Sāgara Press, Bombay, 1888",
                  "page": "181",
                  "verification": "image-verified",
                  "quote_original": "चन्द्रताराबलंकन्यावरयोरुभयोरपि । अन्यतरस्यचन्द्रबलाभावेरजतादिदानंकार्यम्"
                },
                {
                  "work": "Muhūrta Cintāmaṇi",
                  "author": "Rāma Daivajña",
                  "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                  "chapter": "Gocara-prakaraṇa (4)",
                  "verse": "4.1-4",
                  "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                  "page": "193",
                  "verification": "image-verified (leaf 246)",
                  "quote_original": "चन्द्रोऽम्बराब्धौ गुणनन्दयोश्च लाभाष्टमे चाद्यशरे रसान्त्ये नागद्वये … क्रमाच्छुभो विद्ध इति ग्रहः स्यात् पितुः सुतस्यात्र न वेधमाहुः । दुष्टोऽपि खेटो विपरीतवेधाच्छुभो द्विकोणे शुभदः सितेऽजः"
                }
              ],
              "coverage": "whole_window"
            }
          ],
          "bad_periods_inside": [],
          "quality": "acceptable"
        }
      ],
      "weekday_local": "रविवार"
    }
  ]
}

Examples: vehicle purchase with your birth details, in Hindi

curl -s "https://api.tathaastuapi.com/v1/muhurat/search?event=vehicle_purchase&start=2026-12-01&end=2026-12-14&location_id=1&lang=hi&birth_nakshatra=Rohini&birth_rashi=Vrishabha&avoid=rahu_kaal" \
  -H "X-API-Key: YOUR_API_KEY"

const r = await fetch("https://api.tathaastuapi.com/v1/muhurat/search", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    event: "vehicle_purchase", start: "2026-12-01", end: "2026-12-14", location_id: 1,
    birth_date: "1996-05-14", birth_time: "06:30", birth_tz: "Asia/Kolkata",
    lang: "hi", avoid: "rahu_kaal"
  })
});
const data = await r.json();

The Hindi sentence sits beside the English one as text_local; the book name, verse and Sanskrit line are never translated. A real marriage response with lang=hi and birth Moon in Rohini/Vrishabha, shortened:

{
  "event": "vivaha",
  "language": "hi",
  "event_label": "Marriage (Vivāha)",
  "event_label_local": "विवाह",
  "labels_local": {
    "dates": "तिथियाँ",
    "windows": "समय-खण्ड",
    "reasons": "यह क्यों उपयुक्त है",
    "cautions": "सावधानियाँ"
  },
  "personal": {
    "available": true,
    "persons": [
      {
        "nakshatra": "Rohini",
        "rashi": "Vrishabha",
        "source": "birth_nakshatra_rashi",
        "nakshatra_local": "रोहिणी",
        "rashi_local": "वृषभ"
      }
    ],
    "notes": []
  },
  "dates": [
    {
      "date": "2027-01-14",
      "weekday": "Thursday",
      "sunrise": "2027-01-14T07:14:52+05:30",
      "sunset": "2027-01-14T17:45:26+05:30",
      "tithi_at_sunrise": {
        "number": 6,
        "paksha": "Shukla",
        "name": "Shashthi",
        "name_local": "षष्ठी",
        "paksha_local": "शुक्ल"
      },
      "nakshatra_at_sunrise": "Uttara Bhadrapada",
      "nakshatra_at_sunrise_local": "उत्तर भाद्रपद",
      "lunar_month": "Pausha",
      "lunar_month_adhika": false,
      "lunar_month_local": "पौष",
      "quality": "recommended",
      "windows": [
        {
          "start": "2027-01-14T21:10:29+05:30",
          "end": "2027-01-15T07:14:47+05:30",
          "duration_minutes": 604,
          "states": [
            {
              "from": "2027-01-14T21:10:29+05:30",
              "to": "2027-01-14T23:20:29+05:30",
              "tithi": 7,
              "paksha": "Shukla",
              "tithi_name": "Saptami",
              "nakshatra": "Uttara Bhadrapada",
              "tithi_name_local": "सप्तमी",
              "paksha_local": "शुक्ल",
              "nakshatra_local": "उत्तर भाद्रपद"
            }
          ],
          "reasons": [
            {
              "key": "muhurat.reason.vivaha.sun_sign.pass",
              "rule": "vivaha.sun_sign",
              "text": "The Sun is in a sign in which the text allows marriage.",
              "basis": "cited",
              "status": "pass",
              "values": {
                "sun_sign": "Makara",
                "sun_sign_local": "मकर"
              },
              "text_local": "सूर्य ऐसी राशि में है जिसमें ग्रन्थ विवाह की अनुमति देता है।",
              "source": {
                "work": "Muhūrta Cintāmaṇi",
                "author": "Rāma Daivajña",
                "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                "chapter": "Vivāha-prakaraṇa (6)",
                "verse": "6.13",
                "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                "page": "316",
                "verification": "image-verified (leaf 369)"
              },
              "quote_original": "मिथुनकुम्भमृगालिवृषाजगे मिथुनगेऽपि रवौ त्रिलवे शुचेः । अलिमृगाजगते करपीडनं भवति कार्तिकपौषमधुष्वपि",
              "coverage": "whole_window"
            }
          ],
          "general_checks": [
            "..."
          ],
          "cautions": [],
          "bad_periods_inside": [],
          "quality": "recommended"
        }
      ],
      "weekday_local": "गुरुवार"
    },
    "..."
  ]
}

A vehicle search (cited by analogy) returned 5 dates for 1-14 December 2026; its applicability_note reads: “Muhūrta Cintāmaṇi gives rules for goods, animals and shops, not for this act itself; they are applied here by analogy and each reason says so.”

Examples: travel in a direction

curl -s "https://api.tathaastuapi.com/v1/muhurat/search?event=travel&start=2026-11-25&end=2026-11-30&location_id=1&direction=north" \
  -H "X-API-Key: YOUR_API_KEY"

const url = new URL("https://api.tathaastuapi.com/v1/muhurat/search");
url.search = new URLSearchParams({
  event: "travel", start: "2026-11-25", end: "2026-11-30", location_id: "1", direction: "north"
});
const data = await (await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } })).json();
// each window.states[] says which directions are blocked and which are open for that stretch
console.log(data.dates[0].windows[0].states[0].open_directions);

The day is not blocked; the direction is. The texts name the weekday (Mon/Sat East, Thu South, Sun/Fri West, Tue/Wed North) and four nakshatras, and the commentary says the bar is on that direction “not everywhere”. A real response, shortened:

{
  "event": "travel",
  "inputs_used": {
    "direction": "NORTH",
    "house_type": "new"
  },
  "personal": {
    "available": false,
    "how": "Pass birth_nakshatra and birth_rashi, or birth_date + birth_time (+ birth_tz), to apply Chandra-bala and Tara-bala. For marriage a second person can be given as partner_birth_*."
  },
  "dates": [
    {
      "date": "2026-11-26",
      "weekday": "Thursday",
      "sunrise": "2026-11-26T06:52:02+05:30",
      "sunset": "2026-11-26T17:24:30+05:30",
      "tithi_at_sunrise": {
        "number": 2,
        "paksha": "Krishna",
        "name": "Dwitiya"
      },
      "nakshatra_at_sunrise": "Mrigashira",
      "lunar_month": "Kartika",
      "lunar_month_adhika": false,
      "quality": "good",
      "windows": [
        {
          "start": "2026-11-26T06:52:02+05:30",
          "end": "2026-11-26T12:16:44+05:30",
          "duration_minutes": 325,
          "states": [
            {
              "from": "2026-11-26T06:52:02+05:30",
              "to": "2026-11-26T08:32:02+05:30",
              "tithi": 2,
              "paksha": "Krishna",
              "tithi_name": "Dwitiya",
              "nakshatra": "Mrigashira",
              "lagna": "Vrishchika",
              "blocked_directions": {
                "South": [
                  "vara_shula"
                ]
              },
              "open_directions": [
                "East",
                "West",
                "North"
              ]
            },
            {
              "from": "2026-11-26T08:32:02+05:30",
              "to": "2026-11-26T10:42:02+05:30",
              "tithi": 2,
              "paksha": "Krishna",
              "tithi_name": "Dwitiya",
              "nakshatra": "Mrigashira",
              "lagna": "Dhanu",
              "blocked_directions": {
                "South": [
                  "vara_shula"
                ]
              },
              "open_directions": [
                "East",
                "West",
                "North"
              ]
            }
          ],
          "reasons": [
            {
              "key": "muhurat.reason.travel.tithi.pass",
              "rule": "travel.tithi",
              "text": "The tithi is not one of those barred for starting a journey.",
              "basis": "cited",
              "status": "pass",
              "values": {
                "tithi": 2,
                "paksha": "Krishna"
              },
              "source": {
                "work": "Muhūrta Cintāmaṇi",
                "author": "Rāma Daivajña",
                "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                "chapter": "Yātrā-prakaraṇa (11)",
                "verse": "11.9",
                "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                "page": "452",
                "verification": "image-verified (leaf 505)"
              },
              "quote_original": "न षष्ठी न च द्वादशी नाष्टमी नो सिताद्या तिथिः पूर्णिमाऽमा न रिक्ता … यात्रा प्रशस्ता",
              "coverage": "whole_window"
            },
            {
              "key": "muhurat.reason.travel.direction.pass",
              "rule": "travel.direction",
              "text": "Travelling in this direction is not blocked by the weekday's or nakshatra's direction-śūla.",
              "basis": "cited",
              "status": "pass",
              "values": {
                "direction": "North"
              },
              "source": {
                "work": "Muhūrta Cintāmaṇi",
                "author": "Rāma Daivajña",
                "commentary": "Pīyūṣadhārā (Govinda); Pītāmbarā (Kedāradatta Joshī)",
                "chapter": "Yātrā-prakaraṇa (11)",
                "verse": "11.10",
                "edition": "DPB Publications, Delhi, 3rd printing (archive.org: muhurta-chintamani-kedar-datt-joshi)",
                "page": "454",
                "verification": "image-verified (leaf 507)"
              },
              "quote_original": "न पूर्वदिशि शक्रभे … न पाशिदिशि धातृभे … न सौम्यककुभि व्रजेत् … विधुसौरिवारे … गुरौ यमदिशि … इनदैत्येज्ययोः … कुजबुधे",
              "note": "The commentary says the direction-śūla is a bar on that direction, not on the whole day (MC 11.111).",
              "coverage": "whole_window"
            }
          ],
          "general_checks": [
            "..."
          ],
          "cautions": [],
          "bad_periods_inside": [
            {
              "key": "yamaganda",
              "name": "Yamagaṇḍa",
              "start": "2026-11-26T06:52:02+05:30",
              "end": "2026-11-26T08:11:06+05:30",
              "basis": "convention",
              "note": "Popular panchang practice; Rāhu Kāla, Yamagaṇḍa and Gulika are not found in the Muhūrta Cintāmaṇi, Dharmasindhu or Nirṇayasindhu editions read."
            }
          ],
          "quality": "good"
        }
      ]
    },
    "..."
  ]
}

Reading the response

Showing it in an app

• Shubh Muhurat list. One row per dates[] entry: the date and weekday, the best window as “start to end” in the place’s clock, a badge from quality, and the nakshatra/tithi from states[0]. Offer the other windows of the day on tap. Sort by date, not by quality.
• The “why” sheet. On tap, show each reasons[] sentence (text_local if present, else text) with its source line — “Muhūrta Cintāmaṇi 6.55, p.375” — and the quote_original behind a “show the verse” toggle. Show cautions[] in amber with the same source line. Show a basis: convention reason with a visibly different style and its convention_note.
• Travel. Render open_directions and blocked_directions as four compass chips for the chosen stretch; if the user picked a direction, pass direction and the list already excludes the dates where it is blocked.
• Excluded periods. Draw excluded_periods as grey bands on the calendar with the reason sentence on tap (“Hari-shayana: marriage barred until Devotthana”), so an empty month explains itself.
• Personal. Ask for the birth nakshatra and rashi once, store them, and send them on every call. If personal.available is false show a one-line prompt using personal.how.
• Honesty line. Show disclaimer and, for basis: cited_by_analogy, the applicability_note. List rules_not_evaluated under “What this does not check” so users do not assume more than was done.
• Payload size. A 92-day house-entry search is about 800 kB because every window carries its citations (252 kB with detail=compact; a 2.5-week marriage search is 190 kB full and 77 kB compact). Use detail=compact for the list screen and fetch the full response only for the date the user opens.

Errors, plan and limits

Billing. One API request per call, whatever the range (up to 92 days). Limits: a range of 92 days; dates between 1700 and 3100; a 92-day search takes about half a second. Marriage defaults to profile=panchang; use profile=classical to see every cited rule applied as a bar.

Not a prediction. The windows are the hours in which the books’ kala rules hold. Choosing a lagna inside a marriage window, family facts (first-born, mourning) and many lagna-placement rules are not evaluated, and rules_not_evaluated says which. Translations in other languages are machine translations pending native review.

Eclipses

Solar and lunar eclipse data with Sutak timings and visibility by location.

Birth Chart (Kundli) PRO

Generate a complete Vedic birth chart (Kundli) with planetary positions, Lagna, Nakshatras, Dashas, and Yogas based on Swiss Ephemeris + Lahiri ayanamsa. Supports profiles for retrieval.

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
  }'

Compatibility (Kundli Matching) PRO

Ashtakoot (8-fold) Gun Milan compatibility matching. Computes Varna, Vashya, Tara, Yoni, Graha Maitri, Gana, Bhakoot, and Nadi scores with Manglik analysis and Dasha compatibility.

curl -X POST "https://api.tathaastuapi.com/v1/compatibility?lang=hi"   -H "X-API-Key: YOUR_KEY"   -H "Content-Type: application/json"   -d '{
    "person_a": {"name": "Arjun", "name_local": "अर्जुन", "date_of_birth": "1990-05-15", "time_of_birth": "06:30", "latitude": 28.6, "longitude": 77.2},
    "person_b": {"name": "Priya", "name_local": "प्रिया", "date_of_birth": "1992-08-22", "time_of_birth": "14:15", "latitude": 28.6, "longitude": 77.2}
  }'

World Festivals FREE TIER

Multi-religion world festival calendar covering Christian, Orthodox, Islamic, Sikh, Jewish, Buddhist, Jain, Bahá'í, Zoroastrian and Shinto observances, together with the Chinese and East Asian festival year. Where a tradition is not unanimous, the variants are returned as separate entries with their own festival_id — Sunni and Shia, Svetambara and Digambara, and the two Orthodox reckonings of the fixed feasts. Currently covers 2024–2030; call /v1/festivals/world/religions for the exact range in force.

# 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" }
}

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 }
}

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

Bulk APIs

Process multiple dates or locations in a single HTTP request. Ideal for pre-computing calendar data or batch analysis.

{
  "dates": ["2025-03-01", "2025-03-02", "2025-03-15"],
  "lat": 28.6139,
  "lon": 77.2090
}

Languages (i18n)

All names are phonetically transliterated — not machine translated. "एकादशी" renders with the same sound in every script.

Localized values: _local fields

Requesting lang never changes a value you already receive. It adds a <field>_local beside each field it can localize, holding the requested-language value (a field named <base>_key gains <base>_local). Display the _local value; keep matching on the original. The same field name serves every language: lang=hi, lang=ta and lang=de all fill name_local.

{
  "festival_key":        "FESTIVAL_DIWALI",
  "name":                "Diwali",
  "name_local":          "दिवाली",
  "display_name":        "Diwali",
  "display_name_local":  "दिवाली",
  "category":            "SHASTRIC"
}

{
  "type":           "Kaal",
  "type_local":     "काल",
  "meaning":        "Inauspicious - Avoid important work",
  "meaning_local":  "अशुभ - महत्वपूर्ण कार्य न करें"
}

Localized values appear throughout the API: Panchang limbs, festival and vrat names, choghadiya and hora, muhurat labels, signs, grahas and nakshatras on chart routes, rashifal content, the Compatibility Report (summary_local, sections.*.text_local, kootas[].kuta_local / detail_local) and error messages (message_local beside the stable error code). Never localized: ids and codes, numbers, dates and times, coordinates, your own text (name, place), Sanskrit sources and citations. Timestamp fields such as instant_local predate this contract and mean local time; their values are always ISO-8601. Locations return their native-script name as name_native.

Individual Limb Calculators

One limb at a time, when a full Panchang response is more than you need. Each returns the same values the full endpoint would, computed by the same engine.

Kundli Reports

A free teaser for preview, and the full Birth Report: a signed PDF link from POST /v1/kundli/birth-report, in 13 languages.

What /v1/kundli returns

The response is {"data": {…}, "meta": {…}}. meta carries engine_version, calculation_version and generated_at. Everything in data is computed from one chart, so the blocks always agree with each other.

Optional additions. ?include_yogas=true adds yogas from the legacy yoga detector (not source-reviewed; its known defects are listed in yogas_known_defects). ?include_shadbala=true adds shadbala. lang (query or body) adds *_local companion fields in that language; the English values never change.

Request body. Required: date_of_birth (YYYY-MM-DD), time_of_birth (HH:MM or HH:MM:SS, local time), latitude, longitude. Optional: name, timezone (IANA, default Asia/Kolkata), profile (default vedic-lahiri), node_type (mean or true), dasha_levels (1–3), lang.

/v1/kundli or /v1/birth-chart? /v1/birth-chart is the older endpoint: a flatter chart (planets keyed by name, house_cusps, four divisional_charts: D9, D7, D10, D30) that can be stored as a profile and fetched again by profile_id. /v1/kundli is the complete calculation: all 16 vargas, the dasha timeline, karakas, special lagnas, aspects and the rest. Both are kept; use /v1/kundli for new work.

A real response for 15 May 1990, 14:30, New Delhi, shortened (“…” marks what was cut):

{
  "data": {
    "birth": {
      "date": "1990-05-15",
      "time": "14:30:00",
      "latitude": 28.6139,
      "longitude": 77.209,
      "timezone": "Asia/Kolkata",
      "julian_day_ut": 2448026.875
    },
    "calculation": {
      "profile": "vedic-lahiri",
      "zodiac": "sidereal",
      "house_system": "whole_sign",
      "node_type": "mean",
      "ephemeris_actual": "swiss_ephemeris",
      "calculation_version": "1.2.0"
    },
    "lagna": {
      "longitude": 151.904621,
      "sign": "Virgo",
      "degree": 1.904621,
      "nakshatra": "Uttara Phalguni",
      "pada": 2,
      "lord": "Mercury"
    },
    "planets": [
      {
        "name": "Sun",
        "longitude": 30.549776,
        "sign": "Taurus",
        "degree": 0.549776,
        "house": 9,
        "nakshatra": "Krittika",
        "pada": 2,
        "nakshatra_lord": "Sun",
        "sign_lord": "Venus",
        "retrograde": false,
        "stationary": false,
        "dignity": "Neutral",
        "dignity_reason": null,
        "speed": 0.964203,
        "navamsa_sign": "Capricorn"
      },
      "… 8 more grahas"
    ],
    "houses": {
      "system": "whole_sign",
      "houses": [
        {
          "number": 1,
          "sign": "Virgo",
          "lord": "Mercury",
          "planets": []
        },
        "… 11 more"
      ]
    },
    "vargas": {
      "D9_Navamsa": {
        "Lagna": "Capricorn",
        "Sun": "Capricorn",
        "Moon": "Capricorn",
        "Mars": "Taurus",
        "Mercury": "Leo",
        "Jupiter": "Aquarius",
        "Venus": "Sagittarius",
        "Saturn": "Capricorn",
        "Rahu": "Gemini",
        "Ketu": "Sagittarius"
      },
      "…": "D1 to D60, 16 charts"
    },
    "varga_metadata": {
      "D9_Navamsa": {
        "code": "D9",
        "name": "Navamsa",
        "divisions": 9,
        "convention": "movable from itself, fixed from the 9th, dual from the 5th",
        "tradition": "Parashari"
      }
    },
    "dashas": {
      "vimshottari": {
        "start_lord": "Sun",
        "balance_at_birth": {
          "lord": "Sun",
          "years": 3.647829
        },
        "current": {
          "mahadasha": {
            "lord": "Sun",
            "start": "1988-01-07T11:22:09.676349",
            "end": "1994-01-06T23:22:09.676349"
          },
          "antardasha": {
            "lord": "Jupiter",
            "start": "1990-01-25T05:40:09.676349",
            "end": "1990-11-13T10:28:09.676349"
          },
          "pratyantardasha": {
            "lord": "Mercury",
            "start": "1990-04-20T11:04:09.676349",
            "end": "1990-05-31T20:32:57.676349"
          }
        },
        "mahadashas": [
          {
            "lord": "Sun",
            "start": "1988-01-07T11:22:09",
            "end": "1994-01-06T23:22:09",
            "years": 6.0,
            "antardasha": [
              {
                "lord": "Sun",
                "start": "1988-01-07T11:22:09",
                "end": "1988-04-26T01:10:09",
                "pratyantardasha": [
                  "…"
                ]
              },
              "…"
            ]
          },
          "… 8 more"
        ]
      }
    },
    "karakas": {
      "default_convention": "seven_with_rahu",
      "karakas": {
        "Atmakaraka": {
          "planet": "Mars",
          "degree_in_sign": 24.515207,
          "ranking_degree": 24.515207,
          "sign": "Aquarius",
          "house": 6,
          "retrograde": false,
          "reversed_for_ranking": false
        },
        "…": "Amatyakaraka … Darakaraka"
      }
    },
    "special_lagnas": {
      "arudha_lagna": {
        "sign": "Scorpio",
        "house_from_lagna": 3
      },
      "…": "upapada_lagna, badhaka, maraka, gulika_mandi"
    },
    "aspects": {
      "system": "parashari_graha_drishti",
      "aspects": [
        {
          "from": "Sun",
          "from_sign": "Taurus",
          "to_sign_index": 7,
          "distance": 7,
          "to_house": 3,
          "to_planets": [],
          "type": "graha_drishti",
          "basis": "rashi",
          "rule": "all grahas aspect the 7th"
        },
        "…"
      ]
    },
    "dispositors": {
      "Sun": {
        "dispositor": "Venus",
        "chain": [
          "Sun",
          "Venus",
          "Jupiter",
          "Mercury",
          "Mars",
          "Saturn"
        ],
        "final_dispositor": "Saturn"
      },
      "…": "one per graha"
    },
    "planetary_relationships": {
      "combustion": "{…}",
      "planetary_war": "{…}"
    },
    "planetary_nature": {
      "lagna": "Virgo",
      "planets": {
        "Sun": {
          "natural": "malefic",
          "functional": {
            "nature": "neutral",
            "houses_owned": [
              12
            ]
          }
        }
      }
    },
    "argala": {
      "convention": "bphs_argala",
      "from_lagna": "{…}",
      "from_planets": "{…}"
    }
  },
  "meta": {
    "engine_version": "tathaastu-chart_generator-1",
    "calculation_version": "1.2.0"
  }
}

Birth time unknown (time_unknown)

Many people do not know the time they were born. Send "time_unknown": true and leave out time_of_birth: the chart is calculated for 12:00 local time at the birthplace and the Moon’s sign is counted as the first house (Chandra Lagna, चन्द्र लग्न). Chandra Lagna is the traditional fallback when the time is unknown; it is a convention, and this API cites no verse for it. Nothing in the calculation changes: it is an input mode. Without the flag every response is exactly what it was before.

Where it works. time_unknown (boolean, default false) on POST /v1/kundli, POST /v1/birth-chart (nothing is stored or cached for such a chart), POST /v1/kundli/birth-report (JSON and PDF), and POST /v1/compatibility (per person: person_a.time_unknown, person_b.time_unknown). GET /v1/compatibility/score takes bride_time_unknown and groom_time_unknown. The other birth-data endpoints (dosha, ashtakavarga, upagraha and so on) still require time_of_birth. /v1/compatibility/report also still requires the time.

The Moon across the day. The API also computes the Moon at 00:00 and 23:59 local time (and in between). If its sign or nakshatra changes that day the response adds moon_uncertain: {sign: […], nakshatra: […], changes_at: "…", changes: […]} and moon_certain: false. The 12:00 values stay the primary values. Show the warning and offer the user the choice.

Compatibility. Guna Milan needs only the Moon. If a person’s Moon changes nakshatra that day, guna_milan_possible lists every combination with its total, guna_milan_range gives the lowest and highest, and guna_milan_certain is false; guna_milan holds the 12:00 value. Mangal Dosha from the lagna is unavailable; mangal_dosha.person_x is counted from the Moon, with basis: "moon_sign" and labelled a convention. The pair’s overall score, domains and dynamics are null because they read the lagna houses.

Birth Report. The PDF keeps the same design and chart boxes with the label “चन्द्र लग्न / Chandra Lagna” (the local word then the English term, in every report language) and prints “Birth time not known — chart based on Moon sign.” on the cover and the chart page, in the report language (Hindi: जन्म समय ज्ञात न होने के कारण कुंडली चन्द्र राशि पर आधारित है।). The Navamsa and divisional-chart pages and the house-lord interpretation are left out. Only the calculation edition can be honest without a birth time, so a request for edition=predictive returns the calculation edition and says so (edition_requested, edition_note).

How an app should display it. Read lagna_type: "chandra" means the first house is the Moon’s sign. Draw the chart exactly as for a normal chart (same houses[] shape, house 1 = chandra_lagna.sign) but print the label chandra_lagna.label (label_local with lang) where you print “Lagna”, and show notice.note / notice.note_local beside the chart. Do not draw the ascendant, the D9 or other vargas, or house-lord text: those fields are null. When lagna_type is "lagna" or absent, nothing changes. lagna_type: "lagna" is added only when you send time_unknown: false.

Languages. Notes and labels carry a *_local companion (and labels_local) in all 56 languages with lang; Hindi is authored, the rest are machine translated (Google Gemini) and pending native review. The English and machine fields never change with lang.

{
  "name": "Asha",
  "date_of_birth": "2026-08-11",
  "latitude": 28.6139,
  "longitude": 77.209,
  "timezone": "Asia/Kolkata",
  "time_unknown": true
}

Locations

The precomputed locations served from the dataset. Passing a location_id reads that location’s stored row and takes precedence over lat/lon.

How location and region are resolved

Every endpoint answers two separate questions the same way.

Where — whose sunrise, tithi and timings are computed: location_id, else lat+lon, else the canonical location of region, else the endpoint’s default.

Which tradition — which regional festival rules apply: an explicit region, else the location_id’s region and state, else New Delhi’s. Coordinates choose where, never the tradition. Tradition is independent of place, so region=IN-MH&location_id=1 means “Maharashtrian festivals, observed in Delhi”, and region=IN-MH with coordinates means “Maharashtrian festivals, observed there”.

region accepts a canonical region (NORTH_INDIA, SOUTH_INDIA, EAST_INDIA, WEST_INDIA, NEPAL, KASHMIR, SRI_LANKA) or the ISO 3166-2 code of a state recorded on a supported location (e.g. IN-MH Maharashtra, IN-GJ Gujarat), case-insensitive. On /v1/panchang, /v1/day-context and the timing endpoints anything else returns 422 with the supported list. The festival endpoints historically ignored region, so there an unsupported value is still ignored and is named in region_resolution.ignored_region. A state code applies its region’s rules and the state’s own: Gudi Padwa is a Maharashtra rule, so it appears for location_id=8 (Mumbai) or region=IN-MH, but not for region=WEST_INDIA or Ahmedabad. Festival responses report what was used in _engine.region_resolution and _engine.rule_pack_chain; Panchang responses report the served location’s location.region and location.subdivision.

Finding a place

/v1/locations/search takes a name and returns the places that match, each with its exact coordinates, its IANA timezone and its administrative hierarchy. Those coordinates are what you pass to /v1/panchang, /v1/kundli and the rest; they are used as given and are never rounded or moved.

A name is not an answer. India has hundreds of places called Rampur and three called Somnath, only one of which is the temple. When the context you supply does not narrow the field the response sets ambiguous: true and returns the candidates; it does not choose one and present it as the answer. Narrow with state, district or subdistrict: ?q=Somnath returns three, ?q=Somnath&district=Gir Somnath returns one.

Nothing is substituted. A place we do not hold returns an empty result, never the nearest city. An empty search box is recoverable; a Panchang silently computed for somewhere else is not.

Alternate names are searched too. ?q=Cochin finds Kochi and ?q=Khatushyamji finds Khatu in Sikar. The result reports which name matched in matched_on.

Two fields describe how far to trust a result. confidence is about the coordinate: CURATED for a coordinate TathaAstu has verified, HIGH for an ordinary GeoNames position, LOW where its precision is poor or its stored timezone disagrees with the polygon for its own coordinate. selection_risk is about the choice: it is HIGH when several places share the name in the same state and none carries a population, so any automatic pick would be a guess. Treat a risky result as a prompt to ask the user which one they meant.

Where the place data comes from

Place names, coordinates, administrative hierarchy and timezones served by the location endpoints are derived from GeoNames, used under the Creative Commons Attribution 4.0 International licence (CC BY 4.0). GeoNames does not endorse TathaAstu API. Every location response repeats this credit in its attribution field, so an application that surfaces our data can pass the credit on.

Coordinates for a small set of curated locations are TathaAstu’s own and take precedence over the GeoNames value; those rows report confidence: CURATED, and every response names the source it used. Timezone polygons are derived from timezone-boundary-builder, used under the ODbL.

Coverage: India, Nepal and Sri Lanka to village level; every other country to city level

India, Nepal and Sri Lanka are held down to villages and localities (about 664,000 places). Every other country — 243 of them, 163,531 places — is held at city level: every populated place of 1,000 people or more, from GeoNames cities1000. Both come from GeoNames under CC BY 4.0; show the attribution returned with the data.

Search scope. /v1/locations/search without country searches India, Nepal and Sri Lanka, exactly as it always has. Pass country=GB (any ISO 3166-1 alpha-2 code) to search one country, or scope=world to search them all: ?q=Toronto&scope=world, ?q=Edison&country=US&state=US-NJ.

State codes. Outside India, state.code is an ISO 3166-2 code (US-NJ, GB-ENG, CA-ON, DE-BY) only where the GeoNames state matches exactly one ISO subdivision; otherwise it is null and state.name still names it. A code we cannot vouch for is not served.

Calculations. Every place carries latitude, longitude and an IANA timezone; pass them as lat, lon and tz to any Panchang, Kundli or Muhurat endpoint. Festival traditions (region) are defined for India, Nepal and Sri Lanka, so for other countries region is null; pass region explicitly to apply a tradition. A place whose stored timezone disagreed with the timezone map on its UTC offset is held back rather than served with a doubtful zone (354 such places, mostly in Xinjiang, where legal time is Beijing time).

Place names are given in their English/romanised form (name, name_en); name_native is null. lang localizes the surrounding fields, not the place name.

Government Holidays

Civil government holiday calendars for the Indian states, union territories and the Central Government, each date carried with the notification it comes from. This is civil data: it never decides or adjusts a religious festival date, and the Festival Engine does not read it.

Coverage is part of the answer

A year is authoritative only as far as its official notifications have been obtained. Every response carries coverage.status: COMPLETE when the base notification was read on a government host and nothing is open against it, PARTIAL when the list rests on a copy or an item is still open, and NOT_OBTAINED when no notification has been obtained. A short list is never padded from news reports or another state’s calendar, and a year we do not hold answers NOT_OBTAINED rather than an empty success.

Rows whose notification was read from a copy that is not on a government host are provisional. They are left out by default and returned, flagged, with include=provisional.

Every date names its notification

Each holiday carries a source: the issuing authority, the notification number and date, the gazette reference where there is one, the URL it was read at, and evidence_grade — OFFICIAL for the government’s own publication, GOVT_BODY_COPY or THIRD_PARTY_COPY for a copy held elsewhere. /v1/government-holidays/sources lists every document a region’s year rests on.

Amendments, and reading the calendar as it stood

Governments move dates during the year. Odisha declared Id-ul-Zuha on 27 May 2026 in notification 42428, then moved it to 28 May in notification 21787 of 25 May 2026. The original row is kept and marked superseded rather than overwritten, and as_of reconstructs what the calendar said on any given day: as_of=2026-04-01 returns 27 May, as_of=2026-07-01 returns 28 May. Both answers are reproducible, which is what makes the change auditable. Add include=amendments to see what a row replaced.

Three fields, because the states do not agree

The documents use their own words: Arunachal says “Gazetted Holidays”, Karnataka and Telangana say “General Holidays”, Kerala and Tamil Nadu say “Public Holidays”, Lakshadweep says “closed holidays”, and Odisha’s main annexure states no class at all. So each row carries category (the class as the document sets it out), category_as_written (its exact wording, including the original script) and canonical_class (the normalised class you can filter on across states: PUBLIC, RESTRICTED, OPTIONAL, LOCAL, BANK, COURT, SPECIAL, OTHER). The canonical class is ours; the other two are the government’s and are never rewritten. Where the evidence does not settle a class, canonical_class is null rather than a guess.

A list is not classified from the law it was issued under. West Bengal, Jharkhand and Andaman & Nicobar publish their main closure list under the Negotiable Instruments Act; because those notifications also close government offices, they are PUBLIC, while a list that binds only banks is BANK.

Who actually closes

Office and bank calendars differ in at least twelve subjects, so applicability is data, not a flag. Each row lists its audiences (STATE_GOVERNMENT_OFFICES, BANKS, COURTS, EDUCATIONAL_INSTITUTIONS, and others), the scope where it applies — whole region, a district such as Kodagu, or a sub-region such as Mahe — any per-employee limit a restricted or optional list sets, and the document’s own wording. Filter with applies_to=BANKS or scope=Kodagu.

Some rows have no date: Arunachal’s local festivals are fixed later by each Deputy Commissioner, and twelve Central holidays are chosen by State Coordination Committees. They are evidence of an entitlement rather than of a day, so they are left out unless you ask for include=undated.

Region codes

ISO 3166-2 is the identity: IN-MH, IN-TS, IN-OD, and IN-CENTRAL for the Central Government list. Short codes (MH) and codes a subject used to carry (IN-OR, IN-TG) resolve to it, and the response says which alias was used. /v1/government-holidays/regions lists them all with their coverage.

Rashifal & Daily Jyotish

Moon-sign readings from the classical transit rule. Each graha is reported against the houses Phaladeepika XXVI calls benefic counted from your rashi, with the Vedha obstruction applied and the sloka on every line. Daily, weekly, monthly and yearly, for one rashi or all twelve, in English or Hindi. A separate life-area reading groups the classical transit results by the areas the text itself names.

What is classical here, and what is ours

Every statement in a Rashifal response carries a basis, because the reading mixes two different kinds of claim and a customer is entitled to know which is which.

PRIMARY_TEXT_VERIFIED — the per-graha transit verdict, the Vedha obstruction, Chandrabala and the XXVI.25/30/31/32 qualifiers. These are Phaladeepika XXVI (tr. V. Subrahmanya Sastri, 2nd ed. 1950) and each names its sloka.

ARITHMETICALLY_DERIVED — grouping consecutive days carrying the same verdict into one stretch, and detecting sign changes. No judgement is involved: the verdicts are the text’s, the grouping is arithmetic.

PRODUCT_SYNTHESIS — which stretches are surfaced as favourable or as ones to watch, the headline, the ordering, and the idea of a weekly, monthly or yearly horoscope at all. Phaladeepika XXVI contains no period horoscope. It gives a verdict for a transit, and a transit has a duration. Arranging those durations into a period reading is TathaAstu’s arrangement, and it is labelled rather than presented as scripture.

What the response deliberately does not contain

The transit reading (/v1/rashifal/vedic, its /all form and the daily, weekly, monthly and yearly routes) carries no overall score, no percentage, no ranking of the grahas and no career, money, love or health breakdown. Phaladeepika XXVI gives a verdict for each graha and no rule for combining them, no categories and no ordering, so supplying any of those would mean presenting a TathaAstu construction as a classical rule. Every response states this in not_included, so the absence reads as a boundary rather than as a missing feature. The life-area reading described below is a separate resource; it does not change these responses.

Where the source is genuinely undecided the response says so instead of choosing. The chapter establishes no precedence between XXVI.30, 31 and 32, so where two apply both are returned with the conflict marked unresolved; and because XXVI.30 does not say at which layer “inimical” is judged, the naisargika and compound readings are both reported, with sensitive_to_grade_reading flagging where they differ.

Periods, dates and languages

period_type is daily, weekly, monthly or yearly. Weeks run Monday to Sunday; months and years are calendar ones. date is any day inside the period you want and accepts YYYY-MM-DD, today, tomorrow or yesterday. Relative dates resolve against tz, default Asia/Kolkata — a request at 02:00 IST is still the previous UTC day, so resolving in UTC would serve the wrong reading every night.

lang is en or hi. Hindi is not a translation of the English text and is not recalculated; both render from the same canonical result, so they cannot disagree about the astrology. On the two daily routes lang is optional — omit it and the response is exactly what it was before content existed.

detail=days adds the exhaustive per-day block and is accepted for daily and weekly only. For a month it is about 950 KB and for a year about 10 MB, all of it duplicating what intervals already carries, so longer periods refuse it with DETAIL_NOT_AVAILABLE.

Life areas: career, money, relationships, wellbeing, fortune, travel

/v1/rashifal/vedic/life-areas/daily (one rashi) and /v1/rashifal/vedic/life-areas/daily/all (all twelve) read the same transits as the daily reading and add, for each graha, the result Phaladeepika XXVI.9–24 states for that graha in that house from your Moon sign. A result is placed under an area only where the text itself names that area; a house is never turned into an area by convention. Every factor carries its graha, its house from the rashi, its direction (POSITIVE or NEGATIVE), its state, its contribution and the verse it comes from.

Factor states. EFFECTIVE counts (+1 or −1). OBSTRUCTED (a favourable result blocked by Vedha), VOIDED and RESCUED (cancelled or relieved by the classical qualifying rules) and UNRESOLVED (the classical rules do not settle it) are shown but count 0. Each area reports signal: PRESENT, NEUTRALISED when factors exist but none counts, or NO_SIGNAL when no transit speaks to that area today — in which case nothing is invented to fill it.

Levels are a presentation convention, not a classical score

Career, money and fortune carry a level: VERY_FAVOURABLE, FAVOURABLE, MIXED, NEUTRAL, CHALLENGING, VERY_CHALLENGING or NO_SIGNAL. It is a TathaAstu PRODUCT CONVENTION (versions.score_model), derived from the effective factors with equal weight per factor, and it is not a classical score: the text gives a verdict per graha and no rule for combining them. The counts and the factors behind every level are in the response. There is no numeric score, no percentage and no overall rating across areas. confidence (LOW or MEDIUM, never higher) describes how much classical evidence agrees, not how likely anything is; Moon-sign transit is by the tradition’s own account a broad reading.

Relationships, wellbeing and travel return their factors with level: null and level_status: NOT_PROVIDED.

Wellbeing, money and withheld statements

Health is wellbeing only. The health area speaks of energy, rest, calm and recovery (wellbeing_themes) and always carries a disclaimer. It never diagnoses, never names a disease or injury and never predicts illness; it is not medical advice. Money is a traditional reading, not financial advice, and carries its own disclaimer.

Some classical statements for a placement concern death, injury, a named disease, or the illness of a spouse, child or other person. These are never rendered. Where one was withheld, the area sets restricted_factors_withheld: true with a restricted_note; withheld statements are not counted towards any level.

Colour and gem

attributes.lucky_color is a product presentation convention (classification: PRODUCT_CONVENTION). The colours are the classical ones Phaladeepika II gives each graha, preserved as written; choosing one for the day is TathaAstu’s rule, named in selection_rule: the colour of the first graha whose favourable result is effective today, in a fixed order, otherwise the colour of the weekday’s ruling graha. The texts do not prescribe a daily colour, and the response says so in note.

attributes.gem_reference is reference information only (classification: REFERENCE_ONLY): the gem Phaladeepika II.29 associates with the same graha. It is not a recommendation to wear or buy any gemstone.

Languages and versions

lang follows the platform localization contract. en and hi are rendered: the English document is always returned, and Hindi is added beside it as <field>_local (prediction_local, name_local, level_label_local, …); machine values never change with the language. The localization block echoes language and gives status. Any other supported language returns English with status: NOT_AVAILABLE_ENGLISH_RETURNED and the X-Localization-Missing header — never a silent fallback; an unsupported code is rejected. versions names the calculation, methodology, level model, admitted interpretation table and content release behind every response, and a change to any of them is a new version.