/v1/muhurta/best-time

Scan window for highest-scoring muhurta.

What this tells you

Scans a date range in 1-hour steps and scores every slot that starts between sunrise and sunset, using the same scoring as /v1/muhurta/vivah, /v1/muhurta/graha-pravesh or /v1/muhurta/naamkaran. It returns the highest-scoring slots. Use it for wedding-date pickers and similar tools.

Params: start_date and end_date (YYYY-MM-DD, end after start, at most 31 days apart), tz, lat, lon. Optional: purpose, top_n (1–20, default 5), birth_date (YYYY-MM-DD, used by purpose=naamkaran — without it the 10-day check always passes), ayanamsa. date and time are not read. Slots start on whole UTC hours. Slots with the same score are not sorted by time. Costs 30 credits regardless of range.

Request

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

example request

curl "https://api.lifeastroapi.com/v1/muhurta/best-time?start_date=2027-01-01&end_date=2027-01-31&tz=Asia%2FKolkata&lat=28.6139&lon=77.209&purpose=vivah" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters

Checked against the API: a parameter is marked required when the request fails without it.

Name	Required	Example	Description
`start_date`	yes	`2027-01-01`	First date of the range (YYYY-MM-DD).
`end_date`	yes	`2027-01-31`	Max 31 days from start_date.
`tz`	yes	`Asia/Kolkata`	Timezone: IANA name (Asia/Kolkata) or UTC offset (+05:30).
`lat`	yes	`28.6139`	Latitude in decimal degrees.
`lon`	yes	`77.209`	Longitude in decimal degrees.
`purpose`	no	`vivah`
`top_n`	no	—
`birth_date`	no	—	Optional birth date for Chandra Bala and Tara Bala scoring.
`ayanamsa`	no	—	Ayanamsa (sidereal offset) to use. Defaults to lahiri.

Response (200 OK)

The real response to the example request above, generated from the API itself. Long arrays are trimmed to their first two items. Field names are stable across versions.

200 response

{
  "purpose": "vivah",
  "start_date": "2027-01-01",
  "end_date": "2027-01-31",
  "lat": 28.6139,
  "lon": 77.209,
  "ayanamsa": "lahiri",
  "windows": [
    {
      "start_jd": 2461425.916667,
      "end_jd": 2461425.958333,
      "start_iso": "2027-01-20T10:00:00Z",
      "end_iso": "2027-01-20T11:00:00Z",
      "score": 91,
      "grade": "excellent",
      "is_acceptable": true,
      "factors": [
        {
          "name": "Tithi",
          "value": "Trayodashi",
          "weight": 12,
          "score": 12,
          "ok": true
        },
        {
          "name": "Vara",
          "value": "Wednesday",
          "weight": 10,
          "score": 10,
          "ok": true
        }
      ],
      "warnings": [
        "Sun is in Capricorn (Kharmaas/inauspicious solar month) — vivah should be avoided"
      ]
    },
    {
      "start_jd": 2461425.875,
      "end_jd": 2461425.916667,
      "start_iso": "2027-01-20T09:00:00Z",
      "end_iso": "2027-01-20T10:00:00Z",
      "score": 91,
      "grade": "excellent",
      "is_acceptable": true,
      "factors": [
        {
          "name": "Tithi",
          "value": "Trayodashi",
          "weight": 12,
          "score": 12,
          "ok": true
        },
        {
          "name": "Vara",
          "value": "Wednesday",
          "weight": 10,
          "score": 10,
          "ok": true
        }
      ],
      "warnings": [
        "Sun is in Capricorn (Kharmaas/inauspicious solar month) — vivah should be avoided"
      ]
    }
  ]
}

Field reference

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

Field	Type	Meaning
purpose	string	Scoring used: vivah, graha_pravesh, naamkaran or general (the default). general uses the vivah scoring. example: `"vivah"`
start_date, end_date	string	Range that was scanned, echoed from the request. The scan runs from start_date 00:00 UTC up to end_date 00:00 UTC, so end_date itself is not scanned. example: `"2027-01-01", "2027-01-31"`
lat, lon	number	Location, used for sunrise, sunset and the time windows. example: `28.6139, 77.209`
ayanamsa	string	Ayanamsa used. example: `"lahiri"`
windows[]	array	Best slots, highest score first. Up to top_n items (default 5, max 20). Empty array when no daylight slot was scored. example: `[…]`
windows[].start_jd, windows[].end_jd	number	Slot bounds as Julian Days (UT). Every slot is 1 hour long. example: `2461425.916667, 2461425.958333`
windows[].start_iso, windows[].end_iso	string	Slot bounds in UTC (RFC3339, "Z" suffix). Convert to local time for display. example: `"2027-01-20T10:00:00Z", "2027-01-20T11:00:00Z"`
windows[].score	integer (0–100)	Score of the slot, taken at its start. example: `91`
windows[].grade	string	excellent (90+), good (80–89), acceptable (60–79), inauspicious (below 60). example: `"excellent"`
windows[].is_acceptable	boolean	True when score is 60 or more. example: `true`
windows[].factors[]	array	Factor breakdown, same shape and factors as the matching single-check endpoint (/v1/muhurta/vivah, /v1/muhurta/graha-pravesh or /v1/muhurta/naamkaran). example: `{ "name": "Vara", "value": "Friday", "weight": 10, "score": 10, "ok": true }`
windows[].warnings	string[] \| null	Problems found for the slot. null when there are none. example: `null`

Usage tips

How to use it

Purpose dropdown
Make purpose a required UI input: vivah, graha_pravesh (with an underscore) or naamkaran. Each uses different factors and weights.
Show top 3–5
The default top_n=5 fits a card list. Raise it (up to 20) if you want to filter further on your side.
Group by day
Neighbouring hours on the same day often score the same. Group slots by local date before display.

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://lifeastroapi.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 1,500 free credits. Sign up.