/v1/muhurta/best-time

Scan window for highest-scoring muhurta.

What this tells you

The muhurta scanner walks the date window in hora-sized steps, scoring each moment via the relevant event-specific muhurta function, and returns the top candidates. Perfect for wedding-date pickers and auspicious-timing apps.

Costs 2 credits regardless of window size — the scanner is bounded internally to prevent abuse.

Request

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

example request

curl "https://api.divyastroapi.com/v1/muhurta/best-time?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

{
  "event_type": "vivah",
  "window": { "from": "2026-11-01", "to": "2026-12-15" },
  "candidates": [
    {
      "start_local": "2026-11-12T08:45:00+05:30",
      "end_local":   "2026-11-12T10:15:00+05:30",
      "score": 87,
      "factors": { "tithi": 90, "nakshatra": 95, "chandra_bala": 85, "tarabala": 80, "yoga": 82 }
    },
    {
      "start_local": "2026-11-24T10:12:00+05:30",
      "end_local":   "2026-11-24T11:42:00+05:30",
      "score": 84,
      "factors": { "tithi": 88, "nakshatra": 80, "chandra_bala": 90, "tarabala": 85, "yoga": 78 }
    },
    {
      "start_local": "2026-12-08T09:30:00+05:30",
      "end_local":   "2026-12-08T11:00:00+05:30",
      "score": 80,
      "factors": { "tithi": 75, "nakshatra": 85, "chandra_bala": 80, "tarabala": 80, "yoga": 80 }
    }
  ],
  "total_candidates_scanned": 126,
  "min_score_threshold": 75
}

Field reference

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

Field	Type	Meaning
event_type	string	Type of muhurta: vivah, graha-pravesh, naamkaran, yatra, vyapar, sarvartha-siddhi. example: `"vivah"`
window	object	Date range that was scanned. example: `…`
candidates[]	array	Top-scored windows, sorted descending. Default top 10 returned. example: `[…]`
candidates[].score	number	Composite score at the window midpoint. example: `87`
total_candidates_scanned	integer	Number of hora-steps the scanner evaluated. example: `126`
min_score_threshold	integer	Only candidates >= this score are returned. example: `75`

Usage tips

How to use it

Event-type dropdown
Make event type a required UI input. Different types have different scoring logic.
Show top 3–5
The endpoint returns up to 10 candidates, but UX is cleaner with the top 3–5 cards.

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.