Birth-time rectification grid

Somebody knows they were born "in the morning, sometime around six". Rectification is the work of narrowing that down from what actually happened in their life. This endpoint does the expensive, mechanical half: for every candidate minute in a window it computes the facts that move with the clock, so a client can score them against events without asking the ephemeris five hundred times.

It does not rectify anything. There is no scoring here, no interview, no verdict — those are the client's, and they differ per product. What you get is a grid.

POST /v1/rectification/grid

Required scope: charts:read.

Stateless. Nothing is persisted and no chart_id is involved; the same request always returns the same grid.

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "window_start": "1984-12-21T04:00:00+07:00",
        "window_end":   "1984-12-21T08:00:00+07:00",
        "latitude": 55.0084,
        "longitude": 82.9357,
        "step_minutes": 10,
        "detail": "coarse",
        "transit_dates": ["2011-06-14", "2019-03-02"]
      }' \
  https://api.astrolinkers.com/v1/rectification/grid

Request

Field	Type	Default	Notes
window_start	datetime	—	ISO 8601 with an offset. A naive datetime is rejected: a birth time without a zone is not a moment.
window_end	datetime	—	Must be after window_start.
latitude	float	—	Birth place.
longitude	float	—
step_minutes	integer 1…60	10	Distance between candidates.
detail	coarse | fine	coarse	How much of the Vimshottari chain each point carries — see below.
ayanamsha	string	lahiri	Same values as Charts.
transit_dates	date[]	[]	Up to 20 dates of reported life events. Each returns a snapshot of the slow grahas, so a client can score a candidate against what was transiting when the event happened. Duplicates are collapsed.

Limits. The window may not exceed 48 hours — wide enough for the night-birth case where even the calendar date is uncertain. The grid may not exceed 2000 points, a backstop that a real request never approaches (24 h at one-minute steps is 1441).

Two passes, and why detail exists

Antardashas are the expensive part. The widest window at the default step is 289 candidates (48 h ÷ 10 min), computing the sub-period chain for each costs far more than the lagna does, and in the first pass almost all of those candidates are about to be discarded.

So the intended use is two calls:

1. coarse over the whole window at a 10-minute step. Each point carries its mahadashas only. Score, and keep the region that survives.
2. fine over that region at a 1-minute step. Now each point also carries antardashas, which is what separates times that share a mahadasha.

On coarse, antardashas is null — absent, not empty. An empty list would say "this candidate has no sub-periods", which is never true.

Response

Trimmed — the real answer to the request above carries 25 points, and constants carries eight bodies (everything except the Moon, which travels with each point):

{
  "constants": [
    {"planet": "sun", "sign": "sagittarius", "longitude": 245.62, "is_retrograde": false},
    {"planet": "mars", "sign": "aquarius", "longitude": 303.06, "is_retrograde": false}
  ],
  "points": [
    {
      "moment": "1984-12-21T04:00:00+07:00",
      "lagna_longitude": 181.55,
      "lagna_sign": "libra",
      "navamsa_lagna_sign": "libra",
      "dashamsha_lagna_sign": "libra",
      "moon_longitude": 224.63,
      "moon_sign": "scorpio",
      "moon_nakshatra": "Anuradha",
      "moon_nakshatra_fraction": 0.8471,
      "mahadashas": [
        {"lord": "saturn", "start": "1968-11-17T04:00:00+07:00", "end": "1987-11-17T04:00:00+07:00"}
      ],
      "antardashas": null
    }
  ],
  "transits": [
    {
      "date": "2011-06-14",
      "positions": [
        {"planet": "jupiter", "sign": "aries", "longitude": 7.95, "is_retrograde": false},
        {"planet": "saturn", "sign": "virgo", "longitude": 166.42, "is_retrograde": false}
      ]
    }
  ],
  "meta": {"point_count": 25, "step_minutes": 10, "detail": "coarse"}
}

Note the mahadasha starting in 1968, sixteen years before the birth. That is not a bug: the Moon sits 84.7% of the way through Anuradha, so most of Saturn's period has already elapsed at birth and the timeline is reported from its true start. The elapsed fraction is what moves with the clock — a few minutes later in the window shifts that boundary by months, which is precisely the signal a rectification client scores against.

constants[]

Eight bodies — the Sun, Mars, Mercury, Jupiter, Venus, Saturn, Rahu and Ketu — computed once. Over a window of hours the Sun moves a fraction of a degree and Saturn does not meaningfully move at all, so repeating them per point would be several hundred copies of the same numbers. The Moon is the exception, moves about half a degree an hour, and therefore travels inside each point rather than sitting here.

points[]

One per candidate time, in ascending order.

Field	Type	Notes
moment	datetime	The candidate, in the offset you sent.
lagna_longitude / lagna_sign	float / enum	The rising degree and its sign. This is the fastest-moving fact in the chart and the main thing rectification is trying to pin.
navamsa_lagna_sign	enum	D9 lagna. Changes several times faster than the rasi lagna, so it discriminates inside a single rising sign.
dashamsha_lagna_sign	enum	D10 lagna, for career-dated events.
moon_longitude / moon_sign	float / enum
moon_nakshatra	string	Which nakshatra the Moon is in — it sets the Vimshottari starting point.
moon_nakshatra_fraction	float [0, 1)	How far through it. This is what makes the dasha timeline move across the window: a few minutes of birth time shift the balance of the first mahadasha by months.
mahadashas	object[]	lord, start, end.
antardashas	object[] or null	maha_lord, lord, start, end. null on coarse.

transits[]

One snapshot per requested date, each a list in the same shape as constants. Empty when you sent no transit_dates.

meta

point_count, and the step_minutes and detail actually used. Read them back rather than assuming — they confirm what the server did with your request.

Failures

A rejected grid returns 422 with a detail.reason you can branch on:

reason	Meaning
naive_datetime	window_start or window_end arrived without a timezone offset.
window_invalid	window_end is not after window_start.
window_too_wide	More than 48 hours.
step_out_of_range	step_minutes outside 1…60.
too_many_points	Window ÷ step exceeds 2000. Widen the step.
too_many_transit_dates	More than 20 distinct dates.

An engine failure during the computation itself is also a 422, with reason grid_failed and the engine's message.

What this is not

There is no claim here that rectification works. The endpoint publishes chart facts at a series of moments; whether scoring them against a life recovers a birth time is a question about the technique, and this API takes no position on it. Compare the calibration note on Career affinity, where we did measure a related claim and it came out negative.

Build the Bayesian scoring, the event interview and the confidence interval on your side, and tell your users what they are getting.