/v1/muhurta/vivah

Wedding muhurta composite score.

What this tells you

Classical vivah (wedding) muhurta scoring — blends 9 classical factors into a single 0–100 score. Each factor is weighted per Muhurta Chintamani and scored against vivah-specific tables. Use this to score a single candidate datetime; use /v1/muhurta/best-time to scan a window.

Pass birth details via boy_* and girl_* prefixes for chandra_bala and tarabala to be computed — otherwise those factors are skipped.

Request

All requests require an Authorization header with your dv_live_* API key.

example request

curl "https://api.divyastroapi.com/v1/muhurta/vivah?date=2026-04-19&time=06%3A30&tz=%2B05%3A30&lat=28.61&lon=77.21" \
  -H "Authorization: Bearer dv_live_0123456789abcdef0123456789abcdef"

Response (200 OK)

Successful requests return a JSON body. Field names are stable across versions.

200 response

{
  "candidate": "2027-02-15T10:45:00+05:30",
  "score": 82,
  "max": 100,
  "verdict": "excellent",
  "factors": {
    "tithi":       { "value": "Dwadashi",  "score": 90, "weight": 15, "note": "Highly auspicious tithi for vivah" },
    "nakshatra":   { "value": "Rohini",    "score": 95, "weight": 20, "note": "Classical vivah nakshatra" },
    "yoga":        { "value": "Siddhi",    "score": 85, "weight": 10, "note": "Auspicious yoga" },
    "karana":      { "value": "Bava",      "score": 80, "weight": 5,  "note": "Movable karana, acceptable" },
    "vara":        { "value": "Thursday",  "score": 90, "weight": 10, "note": "Guruvar — excellent for vivah" },
    "chandra_bala":{ "value": 1,           "score": 90, "weight": 15, "note": "Moon in strong natal relation" },
    "tarabala":    { "value": 2,           "score": 75, "weight": 10, "note": "Sampad tara" },
    "panchaka":    { "value": "none",      "score": 100,"weight": 5,  "note": "No Panchaka — safe" },
    "bhadra":      { "value": false,       "score": 100,"weight": 10, "note": "No Bhadra (Vishti) karana" }
  },
  "warnings": []
}

Field reference

Every field in the response, with its type, a real example, and what it means.

Field	Type	Meaning
candidate	string (ISO)	Local datetime being scored. example: `"2027-02-15T10:45:00+05:30"`
score	number (0–100)	Weighted composite score. example: `82`
verdict	string	poor (0–40), acceptable (40–60), good (60–75), excellent (75+). example: `"excellent"`
factors	object	Per-factor breakdown. Each has value, score, weight, note. example: `…`
factors.tithi.score	number (0–100)	How favorable the current tithi is for vivah. example: `90`
factors.tithi.weight	integer	How much this factor contributes to the total. All weights sum to 100. example: `15`
factors.chandra_bala	object	Moon's position relative to natal — critical for vivah muhurta. example: `…`
factors.tarabala	object	Tarabala category (1–9). 2, 4, 6, 8 are favorable; 3, 5, 7 require care. example: `…`
warnings	string[]	Any dealbreakers present. Empty = clean muhurta. example: `[]`

Usage tips

How to use it

Show factor bars
Horizontal bars for each factor, colored by score. Users love seeing exactly *why* a muhurta is good or bad.
Warnings override verdict
If `warnings` is non-empty, show the warning prominently even if the score is high.

Errors

Every error follows the same envelope. Use the error.code field (not the message) for conditional logic in your integration.

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "missing or invalid API key",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

402 Payment Required

{
  "error": {
    "code": "trial_exhausted",
    "message": "your free trial credits are exhausted — pick a plan to continue",
    "top_up_url": "https://divyastroapi.com/pricing",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded; retry after 12 seconds",
    "request_id": "req_01hqy7k8c3e7m1n"
  }
}

Try it

Get a dv_live_* key from your dashboard and paste into the cURL snippet above. New accounts get 500 free credits. Sign up.