Nakshatra Timeline API

Generate continuous nakshatra and pada residence windows for one supported body across a UTC interval. This is a Pro-only, sidereal calculation endpoint.

Plan and quota

Pro includes 1,000 timeline units per UTC calendar month. Each request admitted through the usage reservation consumes one unit, regardless of interval length, even if subsequent validation or calculation fails. Free and Developer (Basic) accounts receive 402 Pro plan required.

Endpoint

POST https://api.cosmicephemeris.com/api/astro/nakshatra-timeline

Request contract

  • planet is required and normalized to lowercase.
  • Supported values are sun, moon, mars, mercury, jupiter, venus, saturn, rahu, and ketu.
  • start_utc and end_utc are required ISO 8601 timestamps with Z or an explicit UTC offset. Values are normalized to UTC before interval/date checks. The end must be after the start.
  • The interval may not exceed 180 days and both dates must be inside 1900-01-01 through 2050-12-31.
  • ayanamsa is required and accepts one of the eleven documented sidereal choices.
  • The public API uses fixed one-hour coarse sampling with sub-second boundary refinement. Callers cannot set step_seconds.

Example request

{
  "planet": "saturn",
  "start_utc": "2026-01-01T00:00:00Z",
  "end_utc": "2026-01-03T00:00:00Z",
  "ayanamsa": "lahiri"
}

Response schema

The endpoint returns the timeline object directly; it does not add a second gateway envelope.

FieldTypeMeaning
planetstringNormalized requested body
zodiac_usedstringAlways sidereal
ayanamsa_usedstringSelected ayanamsa
start_utc, end_utcstringNormalized UTC interval
step_secondsintegerServer sampling step; currently 3600
segmentsarrayOrdered, gap-free residence intervals

Segment fields

  • nakshatra_index (1–27), nakshatra_name, and pada (1–4)
  • start_utc and end_utc defining the segment
  • sidereal_longitude_start and sidereal_longitude_end
  • retrograde reports net longitude motion across the residence; motion can reverse inside a station-containing segment. Repeated planet and ayanamsa identify the model.

Example response

This verified result is abbreviated only by containing a two-day interval with one segment.

{
  "planet": "saturn",
  "zodiac_used": "sidereal",
  "ayanamsa_used": "lahiri",
  "start_utc": "2026-01-01T00:00:00Z",
  "end_utc": "2026-01-03T00:00:00Z",
  "step_seconds": 3600,
  "segments": [
    {
      "planet": "saturn",
      "ayanamsa": "lahiri",
      "nakshatra_index": 25,
      "nakshatra_name": "Purva Bhadrapada",
      "pada": 4,
      "start_utc": "2026-01-01T00:00:00Z",
      "end_utc": "2026-01-03T00:00:00Z",
      "sidereal_longitude_start": 331.9469,
      "sidereal_longitude_end": 332.0666,
      "retrograde": false
    }
  ]
}

Calculation boundary

  • Planetary positions use geocentric apparent longitudes from the bundled JPL DE421 ephemeris.
  • Rahu is the engine's mean north node and Ketu is its opposite south node.
  • The result contains geometry only—no meanings, predictions, dashas, yogas, tithis, or Panchanga calculations.

Errors

Sub-second refinement is numerical resolution for detected crossings, not an absolute accuracy guarantee. A brief crossing and return within one hourly sample can be missed near a station. Frame differences can also shift boundary times; see methodology and measured accuracy.

  • 400 missing fields, unsupported body/ayanamsa, invalid interval, or date outside the public window
  • 401 missing or invalid API key
  • 402 Pro plan required
  • 429 1,000-unit monthly timeline limit or edge rate limit reached
  • 502, 503, or 504 temporary calculation-service failure