POST /v1/rectification/event-score
The main rectification engine. Tests every candidate time inside ±time_range_minutes of approx_tob (and, when day_unknown=True, every day of that month too), scoring each by matching active Vimshottari dasha lords on your known event dates to the event-relevant houses, GATED by transiting Jupiter/Saturn/Rahu/Ketu/Mars on those same dates (Gochar) — dasha sets multi-year eligibility, transit is the trigger within it. Optionally (use_kp=true, OFF by default — see EventScoreRequest.use_kp) also gates by the real KP significator method (reuses this API's own /v1/kp house-significator logic); tested against the real case this engine is validated against and found genuinely neutral (no demonstrated benefit, plus real added computation cost), so it's available for callers who want the extra corroborating signal, not shipped as an on-by-default improvement. Also optionally (use_primary_directions=true, OFF by default — see EventScoreRequest.use_primary_directions) gates by classical Western Primary Directions; tested and found essentially no discriminating effect on the real case. Each `event_breakdown[]` entry exposes `dasha_score`/`transit_score`/`kp_score`/`primary_directions_score` separately alongside the combined `score`. Set `use_transit=false` to fall back to pure dasha-only scoring. Returns ranked candidates with confidence scores — the top result is your best-estimate rectified birth time (and date, when day_unknown=True).
curl -X POST https://api.grahaapi.com/v1/rectification/event-score -H "Authorization: Bearer sk-test-your-key" -H "Content-Type: application/json" -d '{"approx_tob":"22:00","day_unknown":false,"dob":"1990-06-15","events":[{"date":"2015-11-23","note":"","type":"marriage"},{"date":"2010-07-01","note":"First tech job","type":"job_start"}],"lat":28.6139,"lon":77.209,"step_minutes":4,"time_range_minutes":60,"tz":5.5}'Test keys (sk-test-…) are free and unlimited, and return the exact production response structure computed from a fixed sample chart. The response is JSON: {"success": true, "data": {…}, "meta": {…}} with Hindi + English strings, computed on the Lahiri ayanamsa.
| Field | Type | Required | Description |
|---|---|---|---|
dob | string | ✅ | Date of birth. YYYY-MM-DD if day is known; YYYY-MM (day omitted) when day_unknown=True. |
day_unknown | boolean | — | True if only year+month of birth are known, not the exact day. When True, dob must be YYYY-MM and every day of that month is scanned in addition to every candidate time — at least 5 events are required (vs. 1 normally) for a confident result. |
approx_tob | string | ✅ | A GUESS at birth time HH:MM, not a confirmed value — this is what the endpoint solves for. Centre of the search window; a wider uncertainty just means a larger time_range_minutes, not a blocker. |
time_range_minutes | integer | — | Search window ± minutes around approx_tob — how uncertain the guess is. Wider window = more candidate times tested (slower), not less accurate. |
step_minutes | integer | — | Step size in minutes between tested candidates (2–10 recommended; floored at 8 automatically when day_unknown=True, to keep a full-month scan bounded) |
lat | number | ✅ | Latitude |
lon | number | ✅ | Longitude |
tz | number | — | UTC offset (IST = 5.5) |
events | RectEvent[] | ✅ | Life events the person is CERTAIN about (exact dates — they already happened). 2+ recommended for a confident ranking (5+ REQUIRED when day_unknown=True); each needs a fixed `type` from the closed EventType vocabulary, not free text. |
use_transit | boolean | — | Also score each event against transiting Jupiter/Saturn/Rahu/Ketu/Mars on that event's date (Gochar), gated onto the dasha score rather than averaged with it — dasha sets multi-year eligibility, transit is the trigger within it. Set False to fall back to pure dasha-only scoring (the previous behaviour) for comparison. |
use_kp | boolean | — | Also gate the score by the real KP (Krishnamurti Paddhati) significator method — reuses this API's own /v1/kp house-significator logic (occupant's star lord / occupant / house-lord's star lord / house lord, computed under self-consistent KP-ayanamsa planets and Placidus cusps), checking whether the active dasha lord on the event date is a genuine significator of that event's relevant houses. Defaults OFF: tested against a real known-birth-time case and found genuinely NEUTRAL — small, mixed changes in both directions (raw rank very slightly worse, smoothing-stability very slightly better, confidence up on every candidate roughly equally), not a clear win or loss either way, plus real added computation cost (a full extra KP-ayanamsa planet+house pass per candidate). Kept off by default given no demonstrated benefit; set True to enable if you want this extra corroborating signal anyway. |
use_primary_directions | boolean | — | Also gate the score by classical Western Primary Directions — a genuinely different technique from dasha/transit/KP (all Vedic period/house-based methods): as the celestial sphere rotates, the Ascendant symbolically 'directs' to each natal planet's Oblique Ascension; the resulting arc, converted to age via the Naibod key (1 degree = 1 year), is compared to the customer's real age at each event. Computed in TROPICAL coordinates (Right Ascension is inherently tied to the true equinox, not the sidereal zodiac); every formula independently cross-checked against a real chart before use (RAMC via two methods, Oblique Ascension against the classical identity OA(Ascendant)=RAMC+90, both matching to full float precision). Defaults OFF: tested against a real known-birth-time case and found essentially NO discriminating effect at the current 1-year orb — rank shifted by at most 1 place out of 361 candidates, smoothing-stability barely moved, and the algorithm's top pick never changed, in both a 5-event and 8-event version of the case. Confidence numbers shift down uniformly (most candidate/significator pairings miss the 1-year orb) without changing relative ranking. Kept off by default given no demonstrated benefit; set True to enable if you want this extra corroborating signal, or if you want to experiment with a different orb. |
predispositions | object | — | Optional. Self-reported answers to static, date-independent life-pattern questions (e.g. 'were you married early') — a third signal alongside dated events, checked against each candidate chart's overall structure rather than a specific date. Keys are one of the fixed PredispositionType categories; values are 'yes_strong' (uniquely characteristic), 'yes' (typical, not definitive), 'unsure' (skip — no info, not a penalty), 'no' (not typical but possible), or 'no_strong' (definitely not typical). The customer answers plain questions about their own life — never astrology terms, never their own Ascendant; this endpoint does the chart-matching automatically per candidate. Leave empty (default) to fall back to pure event-based scoring (previous behaviour) — this signal only activates when at least one non-'unsure' answer is supplied. |
{
"approx_tob": "22:00",
"day_unknown": false,
"dob": "1990-06-15",
"events": [
{
"date": "2015-11-23",
"note": "",
"type": "marriage"
},
{
"date": "2010-07-01",
"note": "First tech job",
"type": "job_start"
}
],
"lat": 28.6139,
"lon": 77.209,
"step_minutes": 4,
"time_range_minutes": 60,
"tz": 5.5
}Get a free API key Try it in the playground
/v1/rectification/ai-suggest · /v1/rectification/ascendant-options · /v1/rectification/kp-ruling-planets