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 calendar month. Each accepted timeline request uses exactly one unit, regardless of interval length. Free and Basic accounts receive 402 Pro plan required.

Endpoint

POST https://api.astroapi.io/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. 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: lahiri, raman, or krishnamurti.
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.

Field	Type	Meaning
`planet`	string	Normalized requested body
`zodiac_used`	string	Always `sidereal`
`ayanamsa_used`	string	Selected ayanamsa
`start_utc`, `end_utc`	string	Normalized UTC interval
`step_seconds`	integer	Server sampling step; currently `3600`
`segments`	array	Ordered, 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, plus repeated planet and ayanamsa identifiers

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

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