Rectification
Rectification is the search for a birth time that is not on the record — or not on it to the minute. It is the most expensive handwork in the trade, and most of those hours go into something a computer does better: taking hundreds of candidate times, working out the chart each one implies, and comparing all of them against the same list of dated events.
POST /api/calc/rectification does that comparison. You give it a birth date, a place, how uncertain the time is, and the life events you can date. It gives back a ranking of candidate times, with the reasoning per candidate, and a statement about how much the evidence actually separated them.
What this is and is not
There is no validated ground truth for rectification. No astrological technique is known to recover a birth time, and this endpoint does not claim to. What it does is rank candidate times by how well each fits the rules you turned on, and show you why — a structured, repeatable way of working, not an oracle.
Three consequences, and they are part of the response format:
- There is never one answer.
candidatesis always a ranking. - The reasoning comes with it. Every candidate lists what each rule contributed and on what grounds, so you can read the ranking and reject it.
- Flatness is reported. When the evidence separates nothing,
discrimination.verdictsaysnoneand the ranking is arbitrary. Show that to whoever is reading it. An answer that crowns the accidental winner of a tie is an answer that lies.
Required Module
rectification:calc, from module:rectification. Included in Deluxe, and available separately. It is deliberately not part of the Calculations bundle.
Why a birth time is findable at all
Almost nothing in a chart moves with the birth time, and that is the whole opening.
| Moves with the time | How fast |
|---|---|
| Ascendant | ~1° per 4 minutes |
| Midheaven | ~1° per 4 minutes |
| House cusps and everything placed in a house | follows the angles |
| Moon | ~0.55° per hour |
| Anything derived from the ascendant (Fortune, Spirit, profections) | follows the ascendant |
| Every other planet | negligible — the Sun covers 0.04° in an hour |
So the evidence that can pin a time is angular evidence. A rule that looks at an aspect between two planets gives near enough the same score to every candidate in the window: it contributes nothing and dilutes what the other rules found. Every rule in this endpoint is angle-sensitive, and that is the single sharpest decision in its design.
A request
curl -X POST "https://api.astroapi.cloud/api/calc/rectification" \
-H "X-Api-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"dateTime": "1978-03-22T15:00",
"location": {
"latitude": 52.37,
"longitude": 4.89,
"timezone": "Europe/Amsterdam"
},
"windowMinutes": 120,
"resolutionMinutes": 1,
"sigmaMinutes": 45,
"events": [
{ "date": "2003-06-14", "type": "marriage", "description": "married in Utrecht" },
{ "date": "2006-02-01", "type": "child-born", "description": "first child" },
{ "date": "2009-09-30", "type": "job-loss" },
{ "date": "2011-05-12", "type": "relocation", "description": "moved to Rotterdam" },
{ "date": "2014-11-03", "type": "career-change" },
{ "date": "2019-01-21", "type": "bereavement", "description": "father died" }
]
}'Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dateTime | string | Yes | Birth date and stated time, YYYY-MM-DDTHH:mm, local clock time at location. The date is fixed; the time is the centre of the search |
location | object | Yes | latitude, longitude and an IANA timezone |
events | array | Yes | 1 to 25 dated events. See the taxonomy below |
windowMinutes | number | No | Half-width of the search, 1–720. Default 120, so ±2 hours |
resolutionMinutes | number | No | Minutes between candidates, 1–60. Default 1 |
sigmaMinutes | number | No | Spread of the prior around the stated time. Default 60 |
rules | array | No | Which rules to score with. Defaults to all implemented rules |
orbDegrees | number | No | Orb for a contact with an angle, 0.1–5. Default 1 |
transitingPoints | array | No | Transiting bodies the angular rules look at. Defaults to the slow bodies |
maxCandidates | number | No | How many candidates come back, 1–200. Default 20 |
houseSystem | string | No | Default placidus |
An event is { date, type, description?, weight? }. date is YYYY-MM-DD or YYYY-MM-DDTHH:mm; a bare date is taken as 12:00 UTC. description is your own wording — it is carried into the evidence lines and never interpreted. weight (0–5, default 1) says how much this event counts against the others.
The window and the resolution together are a limit
The search is capped at 1441 candidates, which is exactly ±12 hours at one minute: the grid is symmetric around the stated time and includes it, so the count is 2 × (window ÷ resolution) + 1. Anything past that is rejected with a 400 telling you so — never quietly narrowed. A whole day fits at a 4-minute resolution (361 candidates), which is the right trade when the time is completely unknown: find the region first, then run a second, finer search inside it.
The rules
| Rule | What it looks for | Weight |
|---|---|---|
transit-to-angle | A transiting body on an angle on the event date | 3.0 |
house-placement | A transiting body in a house the event type is about | 1.5 |
solar-arc-to-angle | A solar arc direction reaching an angle, either way round | 2.0 |
progressed-moon | The progressed Moon on an angle, or in a matching house | 1.0 |
stated-time | The time you gave, as a normal prior | 1.0 |
profection | Annual profections and zodiacal releasing | not yet available |
transit-to-angle is the heaviest, because the angles are the fastest thing in the chart. A transiting body within a degree of an angle pins the birth time to about eight minutes; nothing else here comes close. The question is asked backwards from the usual one — not "when does Saturn reach my midheaven" but "given that it happened on 3 May 2019, which midheaven would that be" — which needs no crossing search at all.
house-placement is coarse on purpose. A house is thirty degrees wide, so it divides the window into blocks of roughly two hours rather than pinning a minute. What it buys is a different kind of evidence: it keeps scoring when no transit happened to land on an angle.
solar-arc-to-angle is as sharp as the first. The arc itself is the same for every candidate — it comes from the Sun, which barely moves in a two-hour window — but the angles it is directed to are not.
progressed-moon is the lightest, and honestly so. The progressed Moon covers a degree a month, far too slow to pin a minute on its own; what ties it to the birth time is that it starts from the natal Moon and meets the candidate's own angles and cusps.
stated-time should stay on. "Around three in the afternoon" is information, and without it the endpoint regularly returns a time six hours away because one transit happened to line up. It is a normal prior: a candidate one sigmaMinutes out gives up half a log unit, one four out gives up eight.
profection is declared but not implemented yet. It is reported as available: false in method.rules rather than quietly scoring zero — a rule that contributes nothing looks exactly like a rule that found nothing, and you should be able to tell those apart.
Why the Moon is not a transiting body by default
Most events are dated to the day, not the minute. A transiting body therefore carries a whole day of uncertainty in its position: ±6.5° for the Moon and ±0.5° for the Sun, against an orb of 1°. A Moon contact with an angle says nothing about the birth time — but it scores, and it scores for some candidate on every event. That is noise dressed as evidence. Saturn moves 0.1° a day; those are the bodies a dated event can actually pin an angle with. If your events are timed to the minute, add the fast bodies through transitingPoints.
The event taxonomy
Fixed, and not free text. A description interpreted by a language model would make the same request answer differently on two days, and reproducibility is what this endpoint has to offer.
| Type | Subject | Houses (weight) |
|---|---|---|
marriage | marriage or committed partnership | 7 (1.0), 5 (0.4), 1 (0.3) |
separation | separation or divorce | 7 (1.0), 8 (0.5), 12 (0.3) |
child-born | birth of a child | 5 (1.0), 4 (0.4), 11 (0.2) |
relocation | move of home | 4 (1.0), 3 (0.4) |
emigration | emigration or long stay abroad | 9 (1.0), 4 (0.6), 3 (0.3) |
career-change | change of career or standing | 10 (1.0), 6 (0.5), 2 (0.3) |
job-loss | loss of work | 6 (1.0), 10 (0.6), 12 (0.3) |
education | start of a course of study | 9 (1.0), 3 (0.5) |
illness | illness | 6 (1.0), 12 (0.6), 8 (0.3) |
surgery | surgery | 8 (1.0), 6 (0.8), 12 (0.4) |
accident | accident or injury | 6 (0.8), 8 (0.8), 1 (0.6) |
bereavement | death of someone close | 8 (1.0), 4 (0.4), 12 (0.3) |
financial-gain | windfall or substantial gain | 2 (1.0), 11 (0.5), 8 (0.4) |
financial-loss | substantial financial loss | 2 (1.0), 8 (0.8), 12 (0.4) |
public-recognition | public recognition | 10 (1.0), 11 (0.6), 1 (0.3) |
other | unclassified | — |
other scores nothing in house-placement and everything in the angular rules, which is the right behaviour for an event you can date but do not want to classify.
The response
{
"data": {
"statedDateTime": "1978-03-22T14:00:00Z",
"candidates": [
{
"dateTime": "1978-03-22T13:56:00Z",
"localDateTime": "1978-03-22T14:56",
"time": "14:56",
"offsetMinutes": -4,
"score": 0.081,
"logScore": 21.4362,
"ascendant": 132.4188,
"midheaven": 41.0072,
"rules": [
{
"rule": "transit-to-angle",
"contribution": 2.41,
"evidence": "transiting saturn conjunction midheaven, orb 0.21° — married in Utrecht (2003-06-14)"
},
{
"rule": "house-placement",
"contribution": 1.05,
"evidence": "transiting jupiter in house 7, which marriage or committed partnership activates — married in Utrecht (2003-06-14)"
},
{
"rule": "stated-time",
"contribution": -0.0099,
"evidence": "4 min before the stated time (σ 45 min)"
}
]
}
],
"discrimination": {
"entropy": 0.62,
"effectiveCandidates": 31.4,
"verdict": "moderate",
"message": "The evidence narrows 241 candidates to about 31. The evidence favours part of the window, but several candidates remain live. Read the per-rule contributions before preferring one."
},
"method": {
"rules": [
{ "rule": "transit-to-angle", "weight": 3, "available": true },
{ "rule": "house-placement", "weight": 1.5, "available": true },
{ "rule": "solar-arc-to-angle", "weight": 2, "available": true },
{ "rule": "progressed-moon", "weight": 1, "available": true },
{ "rule": "stated-time", "weight": 1, "available": true }
],
"resolutionMinutes": 1,
"window": { "start": "1978-03-22T12:00:00Z", "end": "1978-03-22T16:00:00Z" },
"candidates": 241,
"events": 6,
"houseSystem": "placidus",
"orbDegrees": 1,
"sigmaMinutes": 45,
"transitingPoints": ["mars", "jupiter", "saturn", "uranus", "neptune", "pluto", "chiron"],
"requestCost": 16
}
}
}Reading score
score is a candidate's share of the total weight over every candidate in the window, not only the ones returned. The shares of all of them sum to 1.
It is a relative weight inside this one ranking. It is not a probability that this is the birth time, and it cannot be compared between two responses: logScore, which it is derived from, depends on how many events you supplied and which rules you turned on.
Reading discrimination
This is the part that keeps the endpoint honest, and it is worth putting in front of whoever reads the result.
entropy is the Shannon entropy of the ranking's weights divided by the entropy of a flat distribution over the same candidates. It runs from 0 to 1. effectiveCandidates is the same number expressed as a count: how many candidates the evidence effectively leaves standing.
verdict | entropy | What it means |
|---|---|---|
none | ≥ 0.99 | Nothing was separated. The order is arbitrary; treat the list as unsorted |
weak | ≥ 0.95 | Barely a narrowing. Indicative at best |
moderate | ≥ 0.85 | Part of the window is favoured, several candidates remain live |
strong | < 0.85 | A narrow band, well supported under the rules you chose |
Even strong is a statement about the shape of the ranking, not about the truth of the top entry. message is written to be shown as it is.
method
Always present, and not decoration: without knowing which rules ran, at what weight, over which window and at what resolution, an outcome cannot be reproduced — and an outcome that cannot be reproduced cannot be used in a consultation. Keep it with the result.
What it costs
This is the most expensive route on the API, and it is priced to say so:
cost = 5 + events + ceil(candidates / 60) capped at 60An everyday question — ±2 hours at one minute, 8 events — counts as 18 requests. The largest possible one counts as 55. A request that fails counts as nothing. What was actually charged comes back in method.requestCost.
The answer is synchronous; there is no job to poll. The search itself is quick — the ephemeris is consulted a few dozen times in total, and the candidates cost nothing but arithmetic after that — so even the largest question answers in well under a second of calculation.
How to use it in practice
- Start wide and coarse if the time is genuinely unknown. A whole day at 4 minutes (361 candidates) finds the region. Then run ±30 minutes at 1 minute inside it.
- Six to ten events beats twenty. Events you can date confidently and classify honestly are worth more than a long list of approximations. A
weightbelow 1 is the right way to include one you are unsure of, rather than leaving it out. - Do not classify an event from the chart. If you pick
typebecause the chart suggested it, the test is circular and the ranking tells you what you already assumed. - Read the evidence before the score. The list exists so you can disagree with it.
- Open the top candidates as charts.
/api/calc/natalat each candidate'sdateTime. The judgement is yours; this endpoint narrows the field it is made in.
What it deliberately does not do
- It does not return one time. Not with a flag, not with a parameter.
- It does not interpret your event descriptions. A fixed taxonomy, so the same request gives the same answer next month.
- It does not search an unknown date. The date is fixed; only the time is searched. An unknown date multiplies the search space by hundreds and is a different problem.
- It does not explain its own winner with a language model. The rules are arithmetic and tables; a model asked to say why candidate 3 won would invent a story to fit a number.